logixia 1.3.0 → 1.4.0

package/README.md

@@ -2,7 +2,7 @@
 
 <p align="center">
   <strong>The async-first logging library that ships complete.</strong><br/>
-  TypeScript-first &middot; Non-blocking by design &middot; NestJS &middot; Database &middot; Tracing &middot; OTel
+  TypeScript-first &middot; Non-blocking by design &middot; NestJS &middot; Database &middot; Cloud &middot; Tracing &middot; OTel &middot; Browser
 </p>
 
 <p align="center">
@@ -41,7 +41,7 @@ npm install winston winston-daily-rotate-file
 npm install logixia
 ```
 
-logixia ships **console + file rotation + database + request tracing + NestJS module + field redaction + log search + OpenTelemetry** in one package — non-blocking on every transport, zero extra installs.
+logixia ships **console + file rotation + database + request tracing + NestJS module + field redaction + log search + OpenTelemetry + plugin API + Prometheus metrics + visual TUI explorer** in one package — non-blocking on every transport, zero extra installs.
 
 ```typescript
 import { createLogger } from 'logixia';
@@ -82,6 +82,10 @@ await logger.info('Server started', { port: 3000 });
   - [Analytics](#analytics)
   - [Multiple transports simultaneously](#multiple-transports-simultaneously)
   - [Custom transport](#custom-transport)
+- [Cloud adapters](#cloud-adapters)
+  - [AWS CloudWatch](#aws-cloudwatch)
+  - [Google Cloud Logging](#google-cloud-logging)
+  - [Azure Monitor](#azure-monitor)
 - [Request tracing](#request-tracing)
   - [Core trace utilities](#core-trace-utilities)
   - [Express / Fastify middleware](#express--fastify-middleware)
@@ -89,6 +93,14 @@ await logger.info('Server started', { port: 3000 });
   - [Kafka trace interceptor](#kafka-trace-interceptor)
   - [WebSocket trace interceptor](#websocket-trace-interceptor)
 - [NestJS integration](#nestjs-integration)
+  - [@LogMethod decorator](#logmethod-decorator)
+  - [LogixiaExceptionFilter](#logixiaexceptionfilter)
+- [Correlation ID propagation](#correlation-id-propagation)
+  - [Express middleware](#correlation-express-middleware)
+  - [Fastify hook](#correlation-fastify-hook)
+  - [Outbound fetch / axios](#outbound-fetch--axios)
+  - [Kafka / SQS helpers](#kafka--sqs-helpers)
+- [Browser support](#browser-support)
 - [Log redaction](#log-redaction)
 - [Timer API](#timer-api)
 - [Field management](#field-management)
@@ -96,8 +108,20 @@ await logger.info('Server started', { port: 3000 });
 - [Log search](#log-search)
 - [OpenTelemetry](#opentelemetry)
 - [Graceful shutdown](#graceful-shutdown)
+- [Plugin / extension API](#plugin--extension-api)
+  - [Writing a plugin](#writing-a-plugin)
+  - [Registering plugins globally](#registering-plugins-globally)
+  - [Per-logger plugins](#per-logger-plugins)
+  - [Cancelling a log entry](#cancelling-a-log-entry)
+- [Metrics → Prometheus](#metrics--prometheus)
+  - [Quick start (counters)](#quick-start-counters)
+  - [Histograms](#histograms)
+  - [Gauges](#gauges)
+  - [Exposing the /metrics endpoint](#exposing-the-metrics-endpoint)
+  - [Metric configuration reference](#metric-configuration-reference)
 - [Logger instance API](#logger-instance-api)
 - [CLI tool](#cli-tool)
+  - [explore — Visual TUI log explorer](#explore--visual-tui-log-explorer)
 - [Configuration reference](#configuration-reference)
 - [Contributing](#contributing)
 - [License](#license)
@@ -112,16 +136,22 @@ logixia takes a different approach: **everything ships built-in, and nothing blo
 
 - **Async by design** — every log call is non-blocking, even to file and database transports
 - **Built-in database transports** — PostgreSQL, MySQL, MongoDB, SQLite with zero extra drivers
-- **NestJS module** — plug in with `LogixiaLoggerModule.forRoot()`, inject anywhere in the DI tree
+- **Cloud adapters** — AWS CloudWatch (EMF), Google Cloud Logging, and Azure Monitor out of the box
+- **NestJS module** — plug in with `LogixiaLoggerModule.forRoot()`, inject anywhere in the DI tree; `@LogMethod()` for auto-logging method entry/exit
 - **File rotation** — `maxSize`, `maxFiles`, gzip archive, time-based rotation — no extra packages needed
 - **Log search** — query your in-memory log store without shipping to an external service
 - **Field redaction** — mask passwords, tokens, and PII before they touch any transport; supports dot-notation paths and regex patterns
 - **Request tracing** — `AsyncLocalStorage`-based trace propagation with no manual thread-locals; includes Kafka and WebSocket interceptors
+- **Correlation ID propagation** — auto-generate and forward `X-Correlation-ID` through `fetch`, axios, Kafka, and SQS across microservice boundaries
+- **Browser support** — tree-shakeable `logixia/browser` entry point with console and remote batch transports; no Node.js built-ins
 - **OpenTelemetry** — W3C `traceparent` and `tracestate` support, zero extra dependencies
 - **Multi-transport** — write to console, file, and database concurrently with one log call
 - **TypeScript-first** — typed log entries, typed metadata, custom-level IntelliSense throughout
 - **Adaptive log level** — auto-configures based on `NODE_ENV` and CI environment
-- **Custom transports** — ship to Slack, Datadog, S3, or anywhere else via a simple interface
+- **Custom transports** — ship to Slack, PagerDuty, S3, or anywhere else via a simple interface
+- **Plugin / extension API** — lifecycle hooks (`onInit`, `onLog`, `onError`, `onShutdown`); plugins can mutate or cancel log entries; register globally or per-logger
+- **Prometheus metrics** — turn log events into counters, histograms, and gauges with zero code; expose `GET /metrics` in Prometheus text format; works with any HTTP framework
+- **Visual TUI explorer** — `logixia explore` opens a full-screen terminal log browser with real-time search, level filtering, syntax-highlighted JSON detail panel, stack trace rendering, and one-key export to JSON / CSV / NDJSON
 
 ---
 
@@ -133,16 +163,22 @@ logixia takes a different approach: **everything ships built-in, and nothing blo
 | Async / non-blocking writes          |     yes     |     no      |            no             |   no    |
 | NestJS module (built-in)             |     yes     |     no      |            no             |   no    |
 | Database transports (built-in)       |     yes     |     no      |            no             |   no    |
+| Cloud transports (CW, GCP, Azure)    |     yes     |     no      |            no             |   no    |
 | File rotation (built-in)             |     yes     |  pino-roll  | winston-daily-rotate-file |   no    |
 | Multi-transport concurrent           |     yes     |     no      |            yes            |   no    |
 | Log search                           |     yes     |     no      |            no             |   no    |
 | Field redaction (built-in)           |     yes     | pino-redact |            no             |   no    |
 | Request tracing (AsyncLocalStorage)  |     yes     |     no      |            no             |   no    |
 | Kafka + WebSocket trace interceptors |     yes     |     no      |            no             |   no    |
+| Correlation ID propagation           |     yes     |     no      |            no             |   no    |
+| Browser / Edge / Bun / Deno support  |     yes     |   partial   |            no             |   no    |
 | OpenTelemetry / W3C headers          |     yes     |     no      |            no             |   no    |
 | Graceful shutdown / flush            |     yes     |     no      |            no             |   no    |
 | Custom log levels                    |     yes     |     yes     |            yes            |   yes   |
 | Adaptive log level (NODE_ENV)        |     yes     |     no      |            no             |   no    |
+| Plugin / extension API               |     yes     |     no      |            no             |   no    |
+| Prometheus metrics extraction        |     yes     |     no      |            no             |   no    |
+| Visual TUI log explorer              |     yes     |     no      |            no             |   no    |
 | Actively maintained                  |     yes     |     yes     |            yes            |   no    |
 
 ---
@@ -195,11 +231,20 @@ const logger = createLogger({
   environment: 'production',
 });
 
+// ✅ Structured data — machine-readable, searchable, alertable
 await logger.info('Server started', { port: 3000 });
-await logger.warn('High memory usage', { used: '87%' });
-await logger.error('Request failed', new Error('Connection timeout'));
+await logger.warn('High memory usage', { used: '87%', threshold: '80%' });
+await logger.error('Request failed', { orderId: 'ord_123', retryable: true });
+
+// ✅ Pass an Error object directly — logixia serializes the full cause chain
+await logger.error(new Error('Connection timeout'));
+
+// ❌ Avoid string interpolation — you lose structured fields
+// await logger.info(`Server started on port ${port}`);
 ```
 
+No `try/catch` needed — logixia swallows transport errors internally so a flaky DB or disk-full condition never crashes your app.
+
 Without a `transports` key, logs go to stdout/stderr. Add a `transports` key to write to file, database, or anywhere else — all transports run concurrently.
 
 There is also a pre-configured default instance you can import directly:
@@ -658,7 +703,7 @@ const logger = createLogger({
 });
 ```
 
-The `TransportLogEntry` shape is:
+The `write` method may return `void` or `Promise<void>` — both are supported. The `TransportLogEntry` shape is:
 
 ```typescript
 interface TransportLogEntry {
@@ -675,6 +720,102 @@ interface TransportLogEntry {
 
 ---
 
+## Cloud adapters
+
+logixia ships three production-ready cloud transports. All are batched, non-blocking, and implement the same `flush()` / `close()` lifecycle as the built-in transports. Import and pass directly to the `custom` transport array.
+
+### AWS CloudWatch
+
+Batches log events and sends them to a CloudWatch Logs stream using `PutLogEvents`. Supports **EMF** (Embedded Metric Format) so numeric fields in your log entries are automatically promoted to CloudWatch Metrics — no separate SDK needed.
+
+```typescript
+import { CloudWatchTransport } from 'logixia';
+
+const logger = createLogger({
+  appName: 'api',
+  environment: 'production',
+  transports: {
+    custom: [
+      new CloudWatchTransport({
+        region: 'us-east-1', // or set AWS_REGION env var
+        logGroupName: '/app/api',
+        logStreamName: 'api-server-1', // defaults to hostname + PID
+        // Credentials fall back to AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY env vars,
+        // or the EC2/ECS/Lambda metadata service — no hard-coding needed.
+        batchSize: 100, // default: 100
+        flushIntervalMs: 5000, // default: 5000
+        emf: true, // emit numeric fields as CloudWatch Metrics
+        level: 'warn', // forward only warn+ to CloudWatch
+      }),
+    ],
+  },
+});
+```
+
+With `emf: true`, any numeric field in your log data is published as a CloudWatch Metric under the `Logixia` namespace:
+
+```typescript
+await logger.info('Request completed', { duration: 142, statusCode: 200 });
+// → CloudWatch Metric: Logixia/duration, Logixia/statusCode
+```
+
+### Google Cloud Logging
+
+Maps logixia levels to GCP `severity` values (`DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`), auto-injects `logging.googleapis.com/trace` for Cloud Trace correlation, and supports Application Default Credentials (ADC) — no service account JSON required when running on GKE / Cloud Run / App Engine.
+
+```typescript
+import { GCPTransport } from 'logixia';
+
+const logger = createLogger({
+  appName: 'api',
+  environment: 'production',
+  transports: {
+    custom: [
+      new GCPTransport({
+        projectId: 'my-gcp-project', // or set GOOGLE_CLOUD_PROJECT env var
+        logName: 'projects/my-gcp-project/logs/api',
+        resource: { type: 'k8s_container', labels: { cluster_name: 'prod' } },
+        // credentials: { client_email: '...', private_key: '...' }
+        // Omit to use ADC (recommended on GCP-hosted infrastructure)
+        batchSize: 200,
+        flushIntervalMs: 5000,
+      }),
+    ],
+  },
+});
+```
+
+### Azure Monitor
+
+Sends logs to Azure Monitor via the **Logs Ingestion API** (Data Collection Rule). Uses OAuth2 client-credentials to obtain a bearer token automatically.
+
+```typescript
+import { AzureMonitorTransport } from 'logixia';
+
+const logger = createLogger({
+  appName: 'api',
+  environment: 'production',
+  transports: {
+    custom: [
+      new AzureMonitorTransport({
+        endpoint: 'https://<dce-name>.ingest.monitor.azure.com',
+        ruleId: 'dcr-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
+        streamName: 'Custom-LogixiaLogs_CL',
+        tenantId: process.env.AZURE_TENANT_ID,
+        clientId: process.env.AZURE_CLIENT_ID,
+        clientSecret: process.env.AZURE_CLIENT_SECRET,
+        batchSize: 200,
+        flushIntervalMs: 5000,
+      }),
+    ],
+  },
+});
+```
+
+All three cloud transports expose `flush()` and `close()` so they participate in logixia's [graceful shutdown](#graceful-shutdown) flow automatically.
+
+---
+
 ## Request tracing
 
 logixia uses `AsyncLocalStorage` to propagate trace IDs through your entire async call graph automatically — no passing of context objects, no manual threading.
@@ -908,6 +1049,261 @@ export class OrdersService {
 
 `LogixiaLoggerService` exposes the full `LogixiaLogger` API: `info`, `warn`, `error`, `debug`, `trace`, `verbose`, `logLevel`, `time`, `timeEnd`, `timeAsync`, `setLevel`, `getLevel`, `setContext`, `child`, `close`, `getCurrentTraceId`, and more.
 
+### @LogMethod decorator
+
+Automatically logs method entry, exit, duration, and errors — no manual `try/catch` or `logger.debug` calls needed. Works on both sync and async methods. Reads the `logger` property from the class instance (the NestJS convention).
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { LogixiaLoggerService, LogMethod } from 'logixia';
+
+@Injectable()
+export class PaymentService {
+  constructor(private readonly logger: LogixiaLoggerService) {}
+
+  // Logs entry with args, exit with duration, and errors with full stack trace
+  @LogMethod({ level: 'info', logArgs: true, logResult: false })
+  async processPayment(orderId: string, amount: number): Promise<void> {
+    // your business logic — no try/catch needed for logging
+  }
+
+  // Minimal — just tracks duration at debug level
+  @LogMethod()
+  async fetchExchangeRate(currency: string): Promise<number> {
+    return 1.0;
+  }
+}
+```
+
+`@LogMethod` options:
+
+| Option      | Type                             | Default   | Description                                             |
+| ----------- | -------------------------------- | --------- | ------------------------------------------------------- |
+| `level`     | `'debug' \| 'info' \| 'verbose'` | `'debug'` | Log level for entry / exit messages                     |
+| `logArgs`   | `boolean`                        | `true`    | Include method arguments in the entry log               |
+| `logResult` | `boolean`                        | `false`   | Include the return value in the exit log                |
+| `logErrors` | `boolean`                        | `true`    | Log errors with stack trace when the method throws      |
+| `label`     | `string`                         | auto      | Override the auto-detected `ClassName.methodName` label |
+
+### LogixiaExceptionFilter
+
+A global NestJS exception filter that automatically logs unhandled exceptions — HTTP exceptions as `warn`, everything else as `error` — and returns a consistent JSON error shape. Reads the injected `LogixiaLoggerService`; works even without it.
+
+```typescript
+// main.ts
+import { NestFactory } from '@nestjs/core';
+import { LogixiaExceptionFilter } from 'logixia';
+import { AppModule } from './app.module';
+
+async function bootstrap() {
+  const app = await NestFactory.create(AppModule);
+  app.useGlobalFilters(new LogixiaExceptionFilter());
+  await app.listen(3000);
+}
+bootstrap();
+```
+
+With `LogixiaLoggerModule` set up, inject the service directly so it logs to your configured transports:
+
+```typescript
+import { APP_FILTER } from '@nestjs/core';
+import { LogixiaExceptionFilter, LogixiaLoggerService } from 'logixia';
+
+// In AppModule providers:
+{
+  provide: APP_FILTER,
+  useFactory: (logger: LogixiaLoggerService) => new LogixiaExceptionFilter(logger),
+  inject: [LogixiaLoggerService],
+}
+```
+
+The filter returns this shape on error:
+
+```json
+{
+  "statusCode": 500,
+  "message": "Internal server error",
+  "timestamp": "2025-03-14T10:22:01.412Z",
+  "path": "/api/orders"
+}
+```
+
+---
+
+## Correlation ID propagation
+
+`import { ... } from 'logixia/correlation'`
+
+In a microservice architecture each incoming request should carry a `correlationId` that flows through every downstream service call, message queue event, and log line — so you can reconstruct the full request trace in any log aggregator.
+
+logixia ships this as a dedicated `logixia/correlation` sub-package. It uses the same `AsyncLocalStorage` store as the main logger, so every `logger.*` call inside a correlated context automatically includes the ID.
+
+### Correlation Express middleware
+
+```typescript
+import { correlationMiddleware } from 'logixia/correlation';
+
+// Zero-config — reads X-Correlation-ID / X-Request-ID from the incoming request.
+// Generates a UUID v4 if no header is present.
+// Sets X-Correlation-ID on the response.
+app.use(correlationMiddleware());
+
+// Custom config:
+app.use(
+  correlationMiddleware({
+    header: 'X-Correlation-ID', // header to read / write. Default: 'X-Correlation-ID'
+    generateId: () => crypto.randomUUID(),
+    trustIncoming: true, // honour the header from the client. Default: true
+    setResponseHeader: true, // echo the ID back in the response. Default: true
+  })
+);
+```
+
+### Correlation Fastify hook
+
+```typescript
+import Fastify from 'fastify';
+import { correlationFastifyHook } from 'logixia/correlation';
+
+const app = Fastify();
+app.addHook('onRequest', correlationFastifyHook());
+```
+
+### Outbound fetch / axios
+
+Every outbound HTTP call made inside a correlated context automatically carries the `X-Correlation-ID` header.
+
+**fetch:**
+
+```typescript
+import { correlationFetch } from 'logixia/correlation';
+
+// Drop-in replacement for global fetch — forwards the active correlation ID automatically
+const res = await correlationFetch('https://inventory-service/api/items', {
+  method: 'GET',
+  headers: { Authorization: `Bearer ${token}` },
+});
+```
+
+**axios:**
+
+```typescript
+import axios from 'axios';
+import { createCorrelationAxiosInterceptor } from 'logixia/correlation';
+
+const client = axios.create({ baseURL: 'https://inventory-service' });
+createCorrelationAxiosInterceptor(client); // attaches X-Correlation-ID to every request
+```
+
+### Kafka / SQS helpers
+
+```typescript
+import {
+  buildKafkaCorrelationHeaders, // → { 'X-Correlation-ID': '...', 'X-Request-ID': '...' }
+  extractMessageCorrelationId, // read correlationId from a Kafka/SQS message body
+  childFromRequest, // create a child logger pre-seeded with request context
+  withCorrelationId, // run a callback inside an explicit correlation context
+  getCurrentCorrelationId, // read the active correlation ID (or undefined)
+  generateCorrelationId, // generate a new UUID v4 correlation ID
+} from 'logixia/correlation';
+
+// Kafka producer — attach correlation headers to every message
+const producer = kafka.producer();
+await producer.send({
+  topic: 'orders',
+  messages: [{ value: JSON.stringify(order), headers: buildKafkaCorrelationHeaders() }],
+});
+
+// Kafka consumer — restore context for the handler
+const correlationId = extractMessageCorrelationId(message.value);
+withCorrelationId(correlationId, async () => {
+  await orderService.process(message.value);
+  // all logger.* calls inside carry correlationId automatically
+});
+
+// Create a child logger pre-loaded with request identifiers
+const reqLogger = childFromRequest(logger, req);
+await reqLogger.info('Order created', { orderId: 'ord_123' });
+// → log includes correlationId, requestId, originService
+```
+
+**Standalone context (no HTTP framework):**
+
+```typescript
+import { withCorrelationId, generateCorrelationId } from 'logixia/correlation';
+
+const id = generateCorrelationId(); // UUID v4
+
+withCorrelationId(id, async () => {
+  await processJob(job);
+  // all nested logger calls carry id
+});
+```
+
+---
+
+## Browser support
+
+`import { ... } from 'logixia/browser'`
+
+The `logixia/browser` entry point is a fully tree-shakeable, Node.js-free logger for browsers, Cloudflare Workers, Deno, Bun, and any other non-Node runtime. It has zero imports from `node:fs`, `node:async_hooks`, `node:worker_threads`, or any other Node.js built-in.
+
+```typescript
+import { createBrowserLogger } from 'logixia/browser';
+
+const logger = createBrowserLogger({
+  appName: 'my-app',
+  minLevel: 'info',
+  pretty: true, // colorized dev-friendly output via console.group
+});
+
+logger.info('App loaded', { route: '/home' });
+logger.warn('Feature flag missing', { flag: 'new-checkout' });
+logger.error('API call failed', { url: '/api/orders', status: 500 });
+```
+
+**Browser console transport** — uses the native `console` API and maps levels to their correct methods (`console.error`, `console.warn`, `console.info`, `console.debug`):
+
+```typescript
+import { BrowserLogger, BrowserConsoleTransport } from 'logixia/browser';
+
+const logger = new BrowserLogger({
+  appName: 'my-app',
+  transports: [new BrowserConsoleTransport({ pretty: true })],
+});
+```
+
+**Remote batch transport** — buffers log entries and ships them to a remote endpoint in batches. Zero `XMLHttpRequest` or Node.js `http` — uses the global `fetch` API:
+
+```typescript
+import { BrowserLogger, BrowserRemoteTransport } from 'logixia/browser';
+
+const logger = new BrowserLogger({
+  appName: 'my-app',
+  transports: [
+    new BrowserRemoteTransport({
+      endpoint: 'https://logs.my-company.com/ingest',
+      batchSize: 20, // flush when 20 entries accumulate
+      flushIntervalMs: 5000, // or every 5 seconds, whichever comes first
+      headers: { Authorization: `Bearer ${TOKEN}` },
+      minLevel: 'warn', // only ship warn+ to the remote endpoint
+    }),
+  ],
+});
+```
+
+The following utilities from the main package are also re-exported from `logixia/browser` (safe for non-Node runtimes):
+
+```typescript
+import {
+  createTypedLogger, // typed schema-enforced logger factory
+  defineLogSchema, // define a compile-time log schema
+  createOtelBridge, // OpenTelemetry bridge
+  isOtelActive,
+  withOtelSpan,
+} from 'logixia/browser';
+```
+
 ---
 
 ## Log redaction
@@ -1160,6 +1556,273 @@ const { healthy, details } = await logger.healthCheck();
 
 ---
 
+## Plugin / extension API
+
+logixia's plugin system lets you hook into every stage of the log lifecycle without touching core logger code. Plugins are plain objects that implement one or more lifecycle methods.
+
+```typescript
+import type { LogixiaPlugin, LogEntry } from 'logixia';
+```
+
+### Writing a plugin
+
+```typescript
+const myPlugin: LogixiaPlugin = {
+  name: 'my-plugin',
+
+  // Called once when the logger is constructed (global plugins)
+  // or when .use() is called (per-logger plugins).
+  onInit() {
+    console.log('Plugin initialised');
+  },
+
+  // Called for every log entry before it is formatted and written.
+  // Return the (optionally mutated) entry to let it through,
+  // or return null to silently drop it.
+  onLog(entry: LogEntry): LogEntry | null {
+    // Example: enrich every entry with a deployment tag
+    return { ...entry, data: { ...entry.data, deployId: process.env.DEPLOY_ID } };
+  },
+
+  // Called whenever logger.error() receives an Error object.
+  onError(error: Error, entry?: LogEntry) {
+    // Example: forward to a Sentry-compatible sink
+    externalErrorTracker.capture(error, { extra: entry?.data });
+  },
+
+  // Called during logger.close() — await-able for graceful teardown.
+  async onShutdown() {
+    await flushBufferedEvents();
+  },
+};
+```
+
+### Registering plugins globally
+
+Plugins registered on `globalPluginRegistry` are automatically seeded into every logger created after the call.
+
+```typescript
+import { usePlugin } from 'logixia';
+
+usePlugin(myPlugin);
+
+// All loggers created from this point forward will run myPlugin.
+const logger = createLogger({
+  /* ... */
+});
+```
+
+### Per-logger plugins
+
+Register or remove plugins on a specific logger instance at any time:
+
+```typescript
+const logger = createLogger({ context: 'PaymentService' });
+
+// Register
+logger.use(myPlugin);
+
+// Deregister by name
+logger.unuse('my-plugin');
+```
+
+`use()` is chainable:
+
+```typescript
+createLogger({ context: 'api' }).use(metricsPlugin).use(auditPlugin).use(samplerPlugin);
+```
+
+### Cancelling a log entry
+
+Returning `null` from `onLog` drops the entry before it reaches any transport — useful for sampling, deduplication, or environment-based suppression:
+
+```typescript
+const devOnlyPlugin: LogixiaPlugin = {
+  name: 'dev-only',
+  onLog(entry) {
+    // Suppress debug/trace entries in production
+    if (process.env.NODE_ENV === 'production' && entry.level <= 20) {
+      return null; // drop it
+    }
+    return entry;
+  },
+};
+```
+
+Multiple `onLog` hooks run in registration order. If any hook returns `null` the pipeline stops and no further hooks are called.
+
+---
+
+## Metrics → Prometheus
+
+`MetricsPlugin` converts log events into Prometheus-compatible counters, histograms, and gauges — no separate instrumentation library required. The `/metrics` endpoint serves the standard Prometheus text exposition format.
+
+```typescript
+import { createMetricsPlugin } from 'logixia';
+```
+
+### Quick start (counters)
+
+```typescript
+import { createLogger, createMetricsPlugin } from 'logixia';
+import http from 'node:http';
+
+const metrics = createMetricsPlugin({
+  http_requests_total: {
+    type: 'counter',
+    help: 'Total HTTP requests processed',
+    // Which log fields become Prometheus labels
+    labels: ['method', 'status', 'route'],
+  },
+  auth_failures_total: {
+    type: 'counter',
+    help: 'Authentication failures',
+    labels: ['reason'],
+  },
+});
+
+const logger = createLogger({ context: 'api' }).use(metrics);
+
+// Every log entry automatically increments the matching counter
+await logger.info('request handled', { method: 'GET', status: 200, route: '/users' });
+await logger.warn('auth failed', { reason: 'bad-token' });
+
+// Expose /metrics
+http.createServer(metrics.httpHandler()).listen(9100);
+```
+
+The `/metrics` response looks like:
+
+```
+# HELP logixia_http_requests_total Total HTTP requests processed
+# TYPE logixia_http_requests_total counter
+logixia_http_requests_total{method="GET",status="200",route="/users"} 1
+
+# HELP logixia_auth_failures_total Authentication failures
+# TYPE logixia_auth_failures_total counter
+logixia_auth_failures_total{reason="bad-token"} 1
+```
+
+### Histograms
+
+Histograms record the distribution of a numeric field extracted from log entries. Typical use: request latency in milliseconds.
+
+```typescript
+const metrics = createMetricsPlugin({
+  http_request_duration_ms: {
+    type: 'histogram',
+    help: 'HTTP request latency in milliseconds',
+    // The log field whose numeric value is recorded as the observation
+    valueField: 'durationMs',
+    labels: ['route', 'method'],
+    // Custom bucket boundaries (defaults: [1, 5, 10, 25, 50, 100, 250, 500, 1000, 2500, 5000, 10000])
+    buckets: [10, 50, 100, 200, 500, 1000, 5000],
+  },
+});
+
+await logger.info('request complete', { route: '/api/orders', method: 'POST', durationMs: 142 });
+```
+
+Prometheus output includes `_bucket`, `_sum`, and `_count` lines, compatible with `histogram_quantile()`:
+
+```
+# HELP logixia_http_request_duration_ms HTTP request latency in milliseconds
+# TYPE logixia_http_request_duration_ms histogram
+logixia_http_request_duration_ms_bucket{le="10",route="/api/orders",method="POST"} 0
+logixia_http_request_duration_ms_bucket{le="50",route="/api/orders",method="POST"} 0
+logixia_http_request_duration_ms_bucket{le="100",route="/api/orders",method="POST"} 0
+logixia_http_request_duration_ms_bucket{le="200",route="/api/orders",method="POST"} 1
+...
+logixia_http_request_duration_ms_bucket{le="+Inf",route="/api/orders",method="POST"} 1
+logixia_http_request_duration_ms_sum{route="/api/orders",method="POST"} 142
+logixia_http_request_duration_ms_count{route="/api/orders",method="POST"} 1
+```
+
+### Gauges
+
+Gauges track the current value of a numeric field — useful for queue depths, active connections, cache sizes:
+
+```typescript
+const metrics = createMetricsPlugin({
+  queue_depth: {
+    type: 'gauge',
+    help: 'Current number of items in the processing queue',
+    valueField: 'depth',
+    labels: ['queue'],
+  },
+});
+
+await logger.info('queue snapshot', { queue: 'email', depth: 47 });
+```
+
+### Exposing the /metrics endpoint
+
+**Plain Node.js `http` module:**
+
+```typescript
+import http from 'node:http';
+
+http.createServer(metrics.httpHandler()).listen(9100);
+// GET http://localhost:9100/ → Prometheus text format
+```
+
+**Express:**
+
+```typescript
+import express from 'express';
+
+const app = express();
+app.get('/metrics', metrics.expressHandler());
+app.listen(3000);
+```
+
+**Manual render (any framework):**
+
+```typescript
+// Returns the full Prometheus text string
+const text = metrics.render();
+res.setHeader('Content-Type', 'text/plain; version=0.0.4; charset=utf-8');
+res.end(text);
+```
+
+**Reset all counters** (e.g., between tests):
+
+```typescript
+metrics.reset();
+```
+
+### Metric configuration reference
+
+```typescript
+interface CounterConfig {
+  type: 'counter';
+  help?: string; // # HELP line in Prometheus output
+  labels?: string[]; // Log entry fields to use as label keys
+}
+
+interface HistogramConfig {
+  type: 'histogram';
+  help?: string;
+  valueField: string; // The log field holding the numeric observation
+  labels?: string[];
+  buckets?: number[]; // Upper-inclusive bucket boundaries (ms or any unit)
+}
+
+interface GaugeConfig {
+  type: 'gauge';
+  help?: string;
+  valueField: string; // The log field whose value sets the gauge
+  labels?: string[];
+}
+
+// Map of Prometheus metric name → config
+type MetricsMap = Record<string, CounterConfig | HistogramConfig | GaugeConfig>;
+```
+
+All metric names are automatically prefixed with `logixia_` in the output. If a histogram or gauge entry is missing the `valueField`, the entry is still counted but no numeric observation is recorded.
+
+---
+
 ## Logger instance API
 
 Complete reference for every method available on a logger instance returned by `createLogger` or `LogixiaLoggerService`:
@@ -1201,6 +1864,10 @@ logger.setTransportLevels(transportId: string, levels: string[]): void
 logger.getTransportLevels(transportId: string): string[] | undefined
 logger.clearTransportLevelPreferences(): void
 
+// Plugin API
+logger.use(plugin: LogixiaPlugin): this         // register a plugin; chainable
+logger.unuse(pluginName: string): this          // remove a plugin by name; chainable
+
 // Lifecycle
 await logger.flush(): Promise<void>
 await logger.close(): Promise<void>
@@ -1224,7 +1891,40 @@ import {
   registerForShutdown, // (logger) => void
   deregisterFromShutdown, // (logger) => void
   resetShutdownHandlers, // () => void — useful in tests
+  // NestJS extras
+  InjectLogger, // @InjectLogger() parameter decorator
+  LogMethod, // @LogMethod() method decorator
+  LogixiaExceptionFilter, // global exception filter
+} from 'logixia';
+
+// Cloud transports (import directly):
+import { CloudWatchTransport } from 'logixia';
+import { GCPTransport } from 'logixia';
+import { AzureMonitorTransport } from 'logixia';
+
+// Plugin API:
+import type { LogixiaPlugin } from 'logixia';
+import { globalPluginRegistry, PluginRegistry, usePlugin } from 'logixia';
+
+// Metrics → Prometheus:
+import type {
+  CounterConfig,
+  GaugeConfig,
+  HistogramConfig,
+  MetricConfig,
+  MetricsMap,
 } from 'logixia';
+import { createMetricsPlugin, MetricsPlugin } from 'logixia';
+
+// Correlation ID sub-package:
+import { correlationMiddleware, correlationFetch, withCorrelationId } from 'logixia/correlation';
+
+// Browser / Edge sub-package:
+import {
+  createBrowserLogger,
+  BrowserConsoleTransport,
+  BrowserRemoteTransport,
+} from 'logixia/browser';
 ```
 
 ---
@@ -1237,6 +1937,18 @@ logixia ships a CLI for working with log files directly. After installing, the `
 npx logixia --help
 ```
 
+Seven subcommands are available:
+
+| Command   | One-line summary                                             |
+| --------- | ------------------------------------------------------------ |
+| `tail`    | Stream a log file in real-time with level highlighting       |
+| `search`  | Full-text or field-specific search with table / JSON output  |
+| `stats`   | Level counts and time distribution summary                   |
+| `analyze` | Pattern recognition and anomaly detection                    |
+| `export`  | Convert between NDJSON, JSON, and CSV                        |
+| `query`   | SQL-like queries with aggregations, sorting, and live follow |
+| `explore` | Full-screen interactive TUI browser with search and export   |
+
 **`tail`** — stream a log file in real-time, with optional filtering and level highlighting:
 
 ```bash
@@ -1286,6 +1998,135 @@ npx logixia analyze ./logs/app.log
 npx logixia export ./logs/app.log --format csv --output ./logs/app.csv
 ```
 
+**`query`** — run SQL-like queries over NDJSON / JSON log files directly in your terminal:
+
+```bash
+# Basic filter
+npx logixia query ./logs/app.log --sql "SELECT * FROM logs WHERE level='error'"
+
+# Multiple conditions
+npx logixia query ./logs/app.log --sql "WHERE level='error' AND duration > 500"
+
+# Select specific fields
+npx logixia query ./logs/app.log --sql "SELECT level, message, duration FROM logs WHERE level='warn'"
+
+# Time-range shortcuts
+npx logixia query ./logs/app.log --since "last 2 hours"
+npx logixia query ./logs/app.log --since "last 30 minutes" --until "last 5 minutes"
+npx logixia query ./logs/app.log --since today
+npx logixia query ./logs/app.log --since yesterday
+
+# Aggregations
+npx logixia query ./logs/app.log --sql "COUNT BY level"
+npx logixia query ./logs/app.log --sql "GROUP BY statusCode"
+npx logixia query ./logs/app.log --sql "AVG(duration) BY endpoint"
+npx logixia query ./logs/app.log --sql "SUM(duration) BY service"
+
+# Sorting and limiting
+npx logixia query ./logs/app.log --sql "WHERE level='error' ORDER BY timestamp DESC LIMIT 20"
+npx logixia query ./logs/app.log --order-by duration --limit 10
+
+# Output formats
+npx logixia query ./logs/app.log --sql "COUNT BY level" --format table
+npx logixia query ./logs/app.log --sql "WHERE level='error'" --format json
+
+# Live tail with a SQL filter — streams new entries as they are written
+npx logixia query ./logs/app.log --follow --sql "WHERE level='error'"
+npx logixia query ./logs/app.log --follow --since "last 1 hour" --sql "WHERE duration > 1000"
+```
+
+Supported SQL features:
+
+| Clause / keyword             | Example                                  |
+| ---------------------------- | ---------------------------------------- |
+| `SELECT fields`              | `SELECT level, message, duration`        |
+| `WHERE` conditions           | `WHERE level='error' AND duration > 500` |
+| Comparison ops               | `=  !=  >  >=  <  <=`                    |
+| `LIKE` / `NOT LIKE`          | `WHERE message LIKE '%timeout%'`         |
+| `IN` / `NOT IN`              | `WHERE level IN ('error', 'warn')`       |
+| `COUNT BY field`             | `COUNT BY statusCode`                    |
+| `GROUP BY field`             | `GROUP BY endpoint`                      |
+| `AVG(f) BY g`                | `AVG(duration) BY endpoint`              |
+| `SUM / MIN / MAX(f) BY g`    | `MAX(duration) BY service`               |
+| `ORDER BY field [ASC\|DESC]` | `ORDER BY timestamp DESC`                |
+| `LIMIT n`                    | `LIMIT 50`                               |
+
+`--since` / `--until` accept: `"last N minutes"`, `"last N hours"`, `"last N days"`, `"today"`, `"yesterday"`, or any ISO 8601 date string.
+
+### explore — Visual TUI log explorer
+
+`logixia explore` opens a full-screen interactive terminal UI built on raw ANSI + chalk — no extra runtime dependencies required.
+
+```bash
+# Open a log file in the TUI
+npx logixia explore ./logs/app.log
+
+# Start with only error and warn entries visible
+npx logixia explore ./logs/app.log --levels error,warn
+
+# Pre-populate the search field
+npx logixia explore ./logs/app.log --search "payment"
+
+# Follow mode: append new entries as the file grows
+npx logixia explore ./logs/app.log --follow
+```
+
+**Options:**
+
+| Flag               | Default | Description                                                           |
+| ------------------ | ------- | --------------------------------------------------------------------- |
+| `--follow`         | off     | Tail the file; append new entries as they are written                 |
+| `--levels <list>`  | all     | Comma-separated levels to show: `error,warn,info,debug,trace,verbose` |
+| `--search <query>` | —       | Pre-populate the search field on open                                 |
+
+**Layout:**
+
+```
+┌────────────────────────────────────────────────────────────────────────────┐
+│ LOGIXIA EXPLORE  app.log  [42/127]  /payment                               │
+│  E  W  I  D  T  V                                    /: search             │
+│  TIME           LVL  MESSAGE                                               │
+│ 08:00:01.042   ERR  Request failed   status=500 user=abc                   │
+│▶08:00:02.117   INF  Request completed  status=200 user=def    ← selected   │
+│ 08:00:03.890   WRN  Slow query detected  duration=1240                     │
+│──────────────────────────────────────────────────────────────── ▼ DETAIL ─│
+│  {                                                                         │
+│    "timestamp": "...",                                                     │
+│    "level": "info",                                                        │
+│    "message": "Request completed",                                         │
+│    "status": 200,                                                          │
+│    "user": "def"                                                           │
+│  }                                                                         │
+│  j/k move  /search  x export  E/W/I/D/T/V filter  J/K detail↕  q quit    │
+└────────────────────────────────────────────────────────────────────────────┘
+```
+
+**Keyboard shortcuts:**
+
+| Key             | Action                                                                         |
+| --------------- | ------------------------------------------------------------------------------ |
+| `j` / `↓`       | Move selection down                                                            |
+| `k` / `↑`       | Move selection up                                                              |
+| `g` / `Home`    | Jump to first entry                                                            |
+| `G` / `End`     | Jump to last entry                                                             |
+| `PgUp` / `PgDn` | Page up / page down                                                            |
+| `J` / `K`       | Scroll detail panel down / up                                                  |
+| `/`             | Enter search mode (type query → `Enter` to confirm, `Esc` to clear)            |
+| `E W I D T V`   | Toggle error / warn / info / debug / trace / verbose filter                    |
+| `f`             | Toggle real-time follow mode                                                   |
+| `x`             | Export filtered entries (enter a path ending in `.json`, `.csv`, or `.ndjson`) |
+| `q` / `Ctrl+C`  | Quit and return to terminal                                                    |
+
+**Detail panel** shows syntax-highlighted JSON of the selected entry. For error entries with a `stack` field, the full stack trace is rendered below the JSON with frame locations highlighted.
+
+**Export** supports three formats determined by the file extension you type:
+
+- `.json` — pretty-printed JSON array
+- `.csv` — comma-separated with auto-detected column headers
+- `.ndjson` / `.jsonl` — newline-delimited JSON (one entry per line)
+
+The explorer works in any TTY-capable terminal (macOS Terminal, iTerm2, Windows Terminal, VS Code integrated terminal) and degrades gracefully in non-TTY environments (useful when piping to other commands).
+
 ---
 
 ## Configuration reference