logixia 2.0.0 → 2.0.6

package/README.md

@@ -1,2754 +1,329 @@
 # logixia
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/Logixia/logixia/main/.github/assets/logixia-banner.png" alt="logixia: the async-first TypeScript logger. One install, every transport, never blocks the event loop." width="100%"/>
+  <img src="https://raw.githubusercontent.com/Logixia/logixia/main/.github/assets/logixia-banner.png" alt="logixia: the async-first TypeScript logger" width="100%"/>
 </p>
 
 <p align="center">
-  <strong>The async-first TypeScript logger that ships complete.</strong><br/>
-  Wide events &middot; OpenTelemetry (OTLP) &middot; Runtime log levels &middot; Redaction &middot; Adaptive sampling<br/>
-  NestJS &middot; Express &middot; Fastify &middot; Database &middot; Cloud &middot; Tracing &middot; Prometheus &middot; Browser
+  <strong>An async-first TypeScript logger with request tracing, redaction, OpenTelemetry export and the transports you usually have to assemble yourself.</strong>
 </p>
 
 <p align="center">
   <a href="https://www.npmjs.com/package/logixia"><img src="https://img.shields.io/npm/v/logixia" alt="npm version"/></a>
   <a href="https://www.npmjs.com/package/logixia"><img src="https://img.shields.io/npm/dm/logixia" alt="npm downloads"/></a>
-  <a href="https://bundlephobia.com/package/logixia"><img src="https://img.shields.io/bundlephobia/minzip/logixia" alt="bundle size"/></a>
   <a href="https://github.com/Logixia/logixia/actions/workflows/ci.yml"><img src="https://github.com/Logixia/logixia/actions/workflows/ci.yml/badge.svg" alt="CI"/></a>
-  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="MIT"/></a>
+  <a href="https://www.npmjs.com/package/logixia"><img src="https://img.shields.io/badge/npm-provenance-brightgreen" alt="npm provenance"/></a>
+  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/npm/l/logixia" alt="MIT license"/></a>
   <a href="https://www.typescriptlang.org/"><img src="https://img.shields.io/badge/TypeScript-5.0%2B-blue" alt="TypeScript"/></a>
-  <a href="https://logixia.github.io/logixia/"><img src="https://img.shields.io/badge/website-logixia.github.io-a855f7" alt="website"/></a>
-  <a href="#sponsor"><img src="https://img.shields.io/badge/sponsor-%E2%99%A5-a855f7" alt="sponsor"/></a>
 </p>
 
 <p align="center">
-  <a href="https://logixia.github.io/logixia/"><strong>Website</strong></a> &middot;
-  <a href="https://github.com/Logixia/logixia">GitHub</a> &middot;
-  <a href="https://www.npmjs.com/package/logixia">npm</a> &middot;
+  <a href="https://logixia.github.io/logixia/"><strong>Documentation</strong></a> &middot;
+  <a href="https://logixia.github.io/logixia/guide/getting-started">Getting started</a> &middot;
+  <a href="https://logixia.github.io/logixia/guide/migration-v2">Upgrading to 2.x</a> &middot;
   <a href="https://github.com/Logixia/logixia/issues">Issues</a>
 </p>
 
 ---
 
-## The logging setup you copy-paste into every new project
+## Why logixia
 
-```bash
-# The pino route:
-npm install pino pino-pretty pino-roll pino-redact pino-nestjs pino-http
-
-# The winston route:
-npm install winston winston-daily-rotate-file
-# ...then wire 4 separate config objects
-# ...then discover there's no built-in DB transport
-# ...then discover request tracing is manual
-# ...then discover both block your event loop under I/O pressure
-
-# Or:
-npm install logixia
-```
-
-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';
-
-const logger = createLogger({
-  appName: 'api',
-  environment: 'production',
-  transports: {
-    console: { format: 'json' },
-    file: { filename: 'app.log', dirname: './logs', maxSize: '50MB' },
-    database: { type: 'postgresql', host: 'localhost', database: 'appdb', table: 'logs' },
-  },
-});
-
-await logger.info('Server started', { port: 3000 });
-// Writes to console + file + postgres simultaneously. Non-blocking. Done.
-```
-
----
-
-## Table of Contents
-
-- [Why logixia?](#why-logixia)
-- [Feature comparison](#feature-comparison)
-- [Performance](#performance)
-- [Installation](#installation)
-- [Quick start](#quick-start)
-- [Core concepts](#core-concepts)
-  - [Log levels](#log-levels)
-  - [Structured logging](#structured-logging)
-  - [Child loggers](#child-loggers)
-  - [Adaptive log level](#adaptive-log-level)
-  - [Per-namespace log levels](#per-namespace-log-levels)
-- [Transports](#transports)
-  - [Console](#console)
-  - [File with rotation](#file-with-rotation)
-  - [Database](#database)
-  - [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)
-  - [NestJS trace middleware](#nestjs-trace-middleware)
-  - [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)
-- [Transport level control](#transport-level-control)
-- [Transport filter predicate](#transport-filter-predicate)
-- [Log search](#log-search)
-- [OpenTelemetry](#opentelemetry)
-- [OTLP logs export](#otlp-logs-export-opentelemetry-native)
-- [Wide events / canonical log lines](#wide-events--canonical-log-lines)
-- [Dynamic runtime reconfiguration](#dynamic-runtime-reconfiguration)
-- [Adaptive sampling](#adaptive-sampling)
-- [Robust serialization](#robust-serialization)
-- [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)
-- [Sponsor](#sponsor)
-- [Contributing](#contributing)
-- [License](#license)
-
----
-
-## Why logixia?
-
-`console.log` doesn't scale. `pino` is fast but leaves database persistence, NestJS integration, log search, and field redaction entirely to plugins. `winston` is flexible but synchronous and requires substantial boilerplate to get production-ready.
-
-logixia takes a different approach: **everything ships built-in, and nothing blocks your event loop.**
-
-- **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
-- **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, 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
-
----
-
-## Feature comparison
-
-| Feature                               | **logixia** |    pino     |          winston          | bunyan  |
-| ------------------------------------- | :---------: | :---------: | :-----------------------: | :-----: |
-| TypeScript-first                      |     yes     |   partial   |          partial          | partial |
-| 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 + message 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    |
-| **OTLP logs export (OTel-native)**    |   **yes**   |  transport  |            no             |   no    |
-| **Wide events / canonical log lines** |   **yes**   |     no      |            no             |   no    |
-| **Runtime log-level reconfig**        |   **yes**   |  external   |            no             |   no    |
-| **Adaptive (anomaly) sampling**       |   **yes**   |     no      |            no             |   no    |
-| Graceful shutdown / flush (no loss)   |     yes     |   partial   |            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    |
-
----
-
-## Performance
-
-logixia is async-first and built for the hot path: a synchronous fast path for in-process transports (no Promise allocated when the write completes synchronously), a millisecond-cached timestamp, lazy formatting (each transport formats once), and per-call work (level check, namespace resolution, redaction decision) served off pre-built caches.
-
-Every library below writes the **same JSON output** to a null sink, so this measures serialization and framework overhead, not disk or terminal speed. Node 22, Apple Silicon, ops/sec (higher is better). Reproduce with `npm run benchmark`.
-
-| Scenario                     |      pino | logixia (json) |   winston |
-| ---------------------------- | --------: | -------------: | --------: |
-| Simple string log            | 3,396,000 |      1,804,000 | 1,533,000 |
-| Structured log (5 fields)    | 1,308,000 |        931,000 |   729,000 |
-| Error object logging         | 1,192,000 |      1,587,000 | 1,078,000 |
-| Child / per-request logger   | 1,134,000 |        892,000 |   494,000 |
-| Deep nested object           | 1,327,000 |      1,023,000 |   549,000 |
-| High-cardinality (12 fields) |   734,000 |        525,000 |   400,000 |
+Most Node loggers give you a fast `info()` and leave the rest to you. logixia keeps the call simple and ships the parts you end up writing anyway:
 
-**What this means:**
+- **Request tracing built in.** Trace IDs travel through `await` via `AsyncLocalStorage`. Express and Fastify helpers read `traceparent`, `x-request-id` and friends, and every log line inside the request carries the ID.
+- **Redaction before dispatch.** Mask paths (`*.password`, `req.headers.authorization`) and regex patterns once, before any transport sees the entry. Transport credentials are also kept out of serialized output and error text.
+- **Transports for real destinations.** Console, rotating files, PostgreSQL, MySQL, MongoDB, SQLite, CloudWatch, Google Cloud Logging, Azure Monitor, Datadog, OTLP, Slack, Discord, and a worker-thread wrapper. Several can run on one log call.
+- **OpenTelemetry-native.** Read the active span for trace/log correlation, or export logs as OTLP/HTTP records. The OTLP transport builds the JSON itself, so no `@opentelemetry/*` SDK is required to emit logs.
+- **Runs outside Node too.** `logixia/browser` has no Node built-ins and is written for browsers and edge runtimes such as Cloudflare Workers.
+- **Small footprint.** Three runtime dependencies (`commander`, `fast-json-stringify`, `picocolors`), no install scripts, ESM and CommonJS builds with types.
 
-- **pino is the fastest raw JSON serializer here.** It leads in 5 of 6 scenarios, by 21–47%. If raw throughput is the only thing you need, pino is a great choice.
-- **logixia is 1.2–1.9× faster than winston in every scenario**, with p99 latency of 1–5µs, against winston's 2.5–7.5µs.
-- logixia is ahead on error logging, partly because pino also serializes the full stack through its error serializer.
-- logixia's default human-readable console format is faster than its JSON mode. `npm run benchmark` prints both.
-- The point of logixia is everything else in one package: non-blocking file and database transports, tracing, redaction, OpenTelemetry, NestJS and the CLI. It aims to be fast enough that you never notice it, without six extra installs.
+Log calls are `async` and transport failures are caught internally, so a full disk or a flaky database does not crash your process.
 
-**Distinctive-feature throughput** (no cross-library equivalent — `npm run benchmark:features`):
-
-| Operation                                |   ops/sec |   p99 |
-| ---------------------------------------- | --------: | ----: |
-| Wide event (accumulate 6 fields + emit)  |   742,000 | 3.7µs |
-| `safeStringify` (BigInt + circular)      | 2,735,000 | 0.5µs |
-| `decycle` + `retrocycle` round-trip      | 1,003,000 | 1.3µs |
-| Adaptive-sampling decision (hot path)    | 1,950,000 | 0.9µs |
-| Namespace child logging (`db.*` → debug) | 1,966,000 | 0.8µs |
-
-Sampling and namespace resolution add **negligible overhead** (~µs), so you can keep them on in production.
-
-To reproduce: `npm run benchmark` (core) and `npm run benchmark:features` (distinctive APIs).
-
----
-
-## Installation
+## Install
 
 ```bash
 npm install logixia
-pnpm add logixia
-yarn add logixia
-bun add logixia
-```
-
-For database transports, install the relevant driver alongside logixia:
-
-```bash
-npm install pg          # PostgreSQL
-npm install mysql2      # MySQL
-npm install mongodb     # MongoDB
-npm install sqlite3     # SQLite
+# or: pnpm add logixia | yarn add logixia | bun add logixia
 ```
 
-**Requirements:** TypeScript 5.0+, Node.js 18+
+**Node.js:** the library declares `node >=16` and is tested in CI on Node 18, 20 and 22. TypeScript 5.0+ is recommended for the bundled types. Building logixia from source needs a newer toolchain (Node `^22.19 || ^24.11 || >=26`); see [CONTRIBUTING.md](./CONTRIBUTING.md).
 
----
+Database transports use optional drivers that you install yourself: `pg`, `mysql2`, `mongodb`, or `sqlite3` plus `sqlite`.
 
 ## Quick start
 
 ```typescript
-import { createLogger } from 'logixia';
+import { createLogger, runWithTraceId } from 'logixia';
 
 const logger = createLogger({
   appName: 'api',
-  environment: 'production',
+  environment: 'development',
+  traceId: true,
+  redact: { paths: ['password'] },
 });
 
-// ✅ Structured data — machine-readable, searchable, alertable
 await logger.info('Server started', { port: 3000 });
-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:
-
-```typescript
-import { logger } from 'logixia';
-
-await logger.info('Ready');
-```
-
----
-
-## Core concepts
-
-### Log levels
-
-logixia ships with six built-in levels in priority order: `error`, `warn`, `info`, `debug`, `trace`, `verbose`. Logs at or above the configured minimum level are emitted; the rest are dropped.
+await runWithTraceId('req-8f3a', async () => {
+  await logger.warn('Slow query', { table: 'orders', ms: 842 });
+  await logger.info('Login', { user: 'alice', password: 'hunter2' });
+});
 
-```typescript
-await logger.error('Something went wrong');
-await logger.warn('Approaching rate limit', { remaining: 5 });
-await logger.info('Order created', { orderId: 'ord_123' });
-await logger.debug('Cache miss', { key: 'user:456' });
-await logger.trace('Entering function', { fn: 'processPayment' });
-await logger.verbose('Full request payload', { body: req.body });
+await logger.error(new Error('Connection timeout'), { orderId: 'ord_123' });
 ```
 
-The `error` method also accepts an `Error` object directly — the full cause chain and standard Node.js fields (`code`, `statusCode`, `errno`, `syscall`) are serialized automatically:
+Output (colors omitted, stack trace shortened):
 
-```typescript
-await logger.error(new Error('Connection refused'));
-
-// With extra metadata alongside:
-await logger.error(new Error('Payment declined'), { orderId: 'ord_123', retryable: true });
-
-// AggregateError is handled too:
-const err = new AggregateError([new Error('A'), new Error('B')], 'Multiple failures');
-await logger.error(err);
+```text
+[2026-10-30T14:24:30.621Z] [INFO] [api] [ec339fb5-5afb-4675-8c39-ecbad4353818] Server started {"port":3000}
+[2026-10-30T14:24:30.623Z] [WARN] [api] [req-8f3a] Slow query {"table":"orders","ms":842}
+[2026-10-30T14:24:30.623Z] [INFO] [api] [req-8f3a] Login {"user":"alice","password":"[REDACTED]"}
+[2026-10-30T14:24:30.625Z] [ERROR] [api] [ec339fb5-5afb-4675-8c39-ecbad4353818] Connection timeout {"orderId":"ord_123","error":{"name":"Error","message":"Connection timeout","stack":"Error: Connection timeout\n    at main (...)"}}
 ```
 
-You can also define **custom levels** for your domain:
-
-```typescript
-const logger = createLogger({
-  appName: 'payments',
-  levelOptions: {
-    level: 'payment', // show everything down to 'payment'
-    levels: {
-      error: 0,
-      warn: 1,
-      info: 2,
-      debug: 3,
-      // domain-specific levels — lower number = higher priority
-      payment: 1, // same priority as warn
-      audit: 2, // same priority as info
-      kafka: 2,
-    },
-    colors: {
-      error: 'red',
-      warn: 'yellow',
-      info: 'blue',
-      debug: 'green',
-      // IntelliSense now suggests 'payment' | 'audit' | 'kafka' as valid keys:
-      payment: 'brightYellow',
-      audit: 'magenta',
-      // kafka omitted → auto-palette assigns a visible color (cyan in this case)
-    },
-  },
-});
+Without a `transports` key logs go to the console. Add `transports` to write to files, databases or cloud services, all concurrently. There is also a ready-made default instance: `import { logger } from 'logixia'`.
 
-// Custom level methods are available immediately, fully typed
-await logger.payment('Charge captured', { orderId: 'ord_123', amount: 99.99 });
-await logger.audit('Refund approved', { orderId: 'ord_123', by: 'admin' });
-await logger.kafka('Message published', { topic: 'order.created' });
-
-// logLevel() is the typed escape hatch — equivalent to the proxy methods above
-await logger.logLevel('payment', 'Subscription renewed', { userId: 'usr_456' });
-```
+→ [Getting started](https://logixia.github.io/logixia/guide/getting-started) · [Configuration](https://logixia.github.io/logixia/guide/configuration) · [Log levels](https://logixia.github.io/logixia/guide/log-levels)
 
-**Auto-palette colors** — if you omit a color for a custom level, logixia assigns one automatically from the palette `magenta → cyan → yellow → green → blue` (cycling). No more "uncolored" custom levels blending into terminal noise.
+## Feature tour
 
-**NestJS service IntelliSense** — `LogixiaLoggerService.create<T>(config)` carries the level names into the return type, so the IDE autocompletes `service.kafka(...)`, `service.payment(...)` etc. with the correct signature:
+### Request tracing
 
 ```typescript
-const svc = LogixiaLoggerService.create({
-  levelOptions: {
-    levels: { error: 0, warn: 1, info: 2, kafka: 3, payment: 4 },
-    colors: { error: 'red', kafka: 'magenta' }, // ← IDE suggests 'kafka' | 'payment' here
-  },
-});
-
-svc.kafka('Producer connected'); // ✅ fully typed, no 'as any'
-svc.payment('Charge captured', { txnId }); // ✅
-```
+import { createExpressContextMiddleware, createLogger, getCurrentTraceId } from 'logixia';
+import { createExpressMiddleware } from 'logixia/middleware';
 
-### Structured logging
+const logger = createLogger({ appName: 'api', traceId: true });
 
-Every log call accepts a metadata object as its second argument — serialized as structured fields alongside the message, never concatenated into a string:
+app.use(createExpressContextMiddleware({ responseHeader: 'X-Trace-Id' }));
+app.use(createExpressMiddleware(logger)); // one request/response log line per call
 
-```typescript
-await logger.info('User authenticated', {
-  userId: 'usr_123',
-  method: 'oauth',
-  provider: 'google',
-  durationMs: 42,
-  ip: '203.0.113.4',
+app.get('/orders', async (_req, res) => {
+  await logger.info('Listing orders', { traceId: getCurrentTraceId() });
+  res.json([]);
 });
 ```
 
-Development output (colorized text):
-
-```
-[2025-03-14T10:22:01.412Z] [INFO] [api] [abc123def456] User authenticated {"userId":"usr_123","method":"oauth",...}
-```
+The trace ID is the first present header of `traceparent` (parsed to its 32-hex trace id), `x-trace-id`, `x-request-id`, `x-correlation-id` or `trace-id`, otherwise a generated UUID. Fastify has `createFastifyContextHook()` and `createFastifyPlugin()`; for anything else, wrap the handler in `runWithTraceId()`. `logixia/correlation` adds `X-Correlation-ID` propagation through `fetch`, axios, Kafka and SQS.
 
-Production output (JSON, via `format: { json: true }`):
-
-```json
-{
-  "timestamp": "2025-03-14T10:22:01.412Z",
-  "level": "info",
-  "appName": "api",
-  "environment": "production",
-  "message": "User authenticated",
-  "traceId": "abc123def456",
-  "payload": { "userId": "usr_123", "method": "oauth", "provider": "google", "durationMs": 42 }
-}
-```
+→ [Tracing](https://logixia.github.io/logixia/guide/tracing) · [HTTP logging](https://logixia.github.io/logixia/guide/http-logging) · [Child loggers and context](https://logixia.github.io/logixia/guide/child-loggers-and-context)
 
-### Child loggers
+### NestJS
 
-Create child loggers that inherit their parent's configuration and transport setup, but carry their own context string and optional extra fields:
+Everything NestJS-specific lives in `logixia/nest`, so plain Node apps never load `@nestjs/common`.
 
 ```typescript
-const reqLogger = logger.child('OrderService', {
-  requestId: req.id,
-  userId: req.user.id,
-});
-
-await reqLogger.info('Processing order'); // includes requestId + userId in every entry
-await reqLogger.info('Payment confirmed'); // same context, no repetition
-```
-
-### Adaptive log level
-
-logixia automatically selects a sensible default level when no explicit level is configured:
-
-| Condition              | Default level |
-| ---------------------- | :-----------: |
-| `NODE_ENV=development` |    `debug`    |
-| `NODE_ENV=test`        |    `warn`     |
-| `NODE_ENV=production`  |    `info`     |
-| `CI=true`              |    `info`     |
-| None of the above      |    `info`     |
-
-You can override this at any time via the `LOGIXIA_LEVEL` environment variable:
+import { Module } from '@nestjs/common';
+import { LogixiaLoggerModule } from 'logixia/nest';
 
-```bash
-LOGIXIA_LEVEL=debug node server.js
+@Module({
+  imports: [
+    LogixiaLoggerModule.forRoot({
+      appName: 'nestjs-api',
+      traceId: true,
+      transports: { console: {}, file: { filename: 'app.log', dirname: './logs' } },
+    }),
+  ],
+})
+export class AppModule {}
 ```
 
-Or change it at runtime:
+The module registers the trace middleware, provides `LogixiaLoggerService` for injection and also ships `forRootAsync`, `@LogMethod()`, `LogixiaExceptionFilter`, and Kafka and WebSocket trace interceptors. A full app with Docker Compose is in [`examples/nestjs-app`](./examples/nestjs-app/).
 
-```typescript
-logger.setLevel('debug');
-console.log(logger.getLevel()); // 'debug'
-```
+→ [NestJS guide](https://logixia.github.io/logixia/guide/nestjs)
 
-### Per-namespace log levels
-
-Child loggers use their context string as a **namespace**. You can pin different log levels to different namespaces in config, or override them with environment variables at runtime — without redeploying:
+### Redaction
 
 ```typescript
 const logger = createLogger({
   appName: 'api',
-  environment: 'production',
-  namespaceLevels: {
-    db: 'debug', // child('db') and child('db.queries') → DEBUG
-    'db.*': 'debug', // wildcard: all db.* children
-    'http.*': 'warn', // only warn+ from HTTP layer
-    payment: 'trace', // full trace for payment namespace
+  redact: {
+    paths: ['password', '*.token', 'req.headers.authorization', '**.creditCard'],
+    patterns: [/Bearer\s+\S+/gi],
+    censor: '[REDACTED]',
   },
 });
 
-const dbLogger = logger.child('db'); // resolves to DEBUG
-const httpLogger = logger.child('http.req'); // resolves to WARN
+await logger.info('Login', { user: 'alice', password: 'hunter2' });
+// → {"user":"alice","password":"[REDACTED]"}
 ```
 
-Environment variable overrides use the pattern `LOGIXIA_LEVEL_<NS>` where `<NS>` is the first segment of the namespace, uppercased:
+Paths support `*` (one segment) and `**` (any depth), match case-insensitively, and the input object is never mutated. Circular references are printed as `[Circular]`.
 
-```bash
-# Override just the db namespace to trace, without changing anything else:
-LOGIXIA_LEVEL_DB=trace node server.js
-
-# Override the payment namespace:
-LOGIXIA_LEVEL_PAYMENT=info node server.js
-```
-
----
-
-## Transports
+→ [Redaction](https://logixia.github.io/logixia/guide/redaction)
 
-All transports are configured under the `transports` key and run concurrently on every log call.
+### Transports
 
-### Console
+All transports run concurrently. Built-in ones are configured under `transports`; the rest are classes you pass in `transports.custom`.
 
 ```typescript
-const logger = createLogger({
-  appName: 'api',
-  environment: 'development',
-  format: {
-    colorize: true, // ANSI colour output
-    timestamp: true, // include ISO timestamp
-    json: false, // text format; set to true for JSON
-  },
-  transports: {
-    console: {
-      level: 'debug', // minimum level for this transport only
-    },
-  },
-});
-```
-
-### File with rotation
+import { createLogger, OtlpLogTransport, SlackTransport } from 'logixia';
 
-No extra packages. Rotation by size or time interval, automatic gzip compression, configurable retention — all built-in:
-
-```typescript
 const logger = createLogger({
   appName: 'api',
-  environment: 'production',
   transports: {
+    console: { level: 'info' },
     file: {
       filename: 'app.log',
       dirname: './logs',
-      maxSize: '50MB', // rotate before the file passes this size ('500KB', '1GB' or bytes)
-      maxFiles: 14, // keep the 14 newest rotated files, delete older ones
-      zippedArchive: true, // compress old files with gzip
-      datePattern: 'YYYY-MM-DD', // optional: also rotate when the day changes
-      format: 'json', // 'json' | 'text' | 'csv'
-      batchSize: 100, // buffer up to 100 entries before writing
-      flushInterval: 2000, // flush buffer every 2 seconds
+      maxSize: '50MB',
+      maxFiles: 14,
+      zippedArchive: true,
     },
+    custom: [
+      new OtlpLogTransport({ url: 'http://localhost:4318/v1/logs', serviceName: 'api' }),
+      new SlackTransport({ webhookUrl: process.env.SLACK_WEBHOOK_URL!, level: 'error' }),
+    ],
   },
 });
 ```
 
-The live file keeps its name, so `tail -f logs/app.log` keeps working. Rotated files are renamed beside it: `app-2026-10-22T09-30-00-000.log.gz`, or `app-2026-10-22.log.gz` when `datePattern` is set. Files are split on line boundaries, so no line is cut in half. On restart the transport carries on from the size of the existing `app.log`.
-
-**Bounding memory under load.** Entries wait in memory until the disk accepts them, and by default there is no limit. Set `maxQueue` to cap how many unwritten entries (the batch being written included) the transport holds, and `queuePolicy` to choose what happens at the cap:
-
-```typescript
-file: {
-  filename: 'app.log',
-  maxQueue: 10000,
-  queuePolicy: 'drop-oldest', // 'drop-oldest' (default) | 'drop-newest' | 'block'
-}
-```
+| Transport                                                                           | Where it comes from                                  | Use it for                                         |
+| ----------------------------------------------------------------------------------- | ---------------------------------------------------- | -------------------------------------------------- |
+| [Console](https://logixia.github.io/logixia/guide/transports/console)               | `transports.console`                                 | Colorized dev output or JSON to stdout             |
+| [File](https://logixia.github.io/logixia/guide/transports/file)                     | `transports.file`                                    | Size/date rotation, gzip, retention                |
+| [Database](https://logixia.github.io/logixia/guide/transports/database)             | `transports.database`                                | PostgreSQL, MySQL, MongoDB, SQLite                 |
+| [CloudWatch](https://logixia.github.io/logixia/guide/transports/cloudwatch)         | `logixia/cloudwatch`                                 | AWS CloudWatch Logs, optional EMF metrics          |
+| [Google Cloud](https://logixia.github.io/logixia/guide/transports/gcp)              | `logixia/gcp`                                        | Cloud Logging with Cloud Trace correlation         |
+| [Azure Monitor](https://logixia.github.io/logixia/guide/transports/azure)           | `logixia/azure`                                      | Logs Ingestion API (Data Collection Rule)          |
+| [Datadog](https://logixia.github.io/logixia/guide/transports/datadog)               | `transports.analytics.datadog`, `logixia/transports` | Logs and metrics to Datadog                        |
+| [OTLP](https://logixia.github.io/logixia/guide/transports/otlp)                     | `logixia`, `logixia/transports`                      | OTLP/HTTP to Grafana, Axiom, SigNoz, a Collector   |
+| [Analytics](https://logixia.github.io/logixia/guide/transports/analytics)           | `transports.analytics`                               | Mixpanel, Segment, Google Analytics, Datadog       |
+| [Slack / Discord](https://logixia.github.io/logixia/guide/transports/slack-discord) | `logixia`, `logixia/transports`                      | Alerting to a chat channel via webhooks            |
+| [Worker thread](https://logixia.github.io/logixia/guide/transports/worker)          | `logixia/worker`                                     | Move file/database/console I/O off the main thread |
+| [Custom](https://logixia.github.io/logixia/guide/transports/custom)                 | `transports.custom` with `ITransport`                | Anything else: S3, queues, internal services       |
 
-`drop-oldest` discards the oldest waiting entry, `drop-newest` discards the incoming one, and `block` makes `write()` wait until there is room. Dropped lines are counted and reported on stderr at most once every 5 seconds, and once more on `close()`.
+→ [All transports](https://logixia.github.io/logixia/guide/transports/)
 
-You can also use **time-based rotation** via the `rotation` sub-key:
+### OpenTelemetry
 
 ```typescript
-transports: {
-  file: {
-    filename: 'app.log',
-    dirname: './logs',
-    rotation: {
-      interval: '1d',      // rotate daily: '1h' | '6h' | '12h' | '1d' | '1w'
-      maxSize: '100MB',    // and on size
-      maxFiles: 30,
-      compress: true,
-      // or decide yourself, checked before each write:
-      // shouldRotate: (file, { size, created }) => size > 100 * 1024 * 1024,
-    },
-  },
-},
-```
+import { createLogger, initOtelBridge } from 'logixia';
 
-With a `rotation` block every file is timestamped, including the one being written.
+initOtelBridge(); // call once, after your OTel SDK starts
 
-Multiple file transports are supported — pass an array:
-
-```typescript
-transports: {
-  file: [
-    { filename: 'app.log',   dirname: './logs', format: 'json' },
-    { filename: 'error.log', dirname: './logs', format: 'json', level: 'error' },
-  ],
-},
+const logger = createLogger({ appName: 'checkout' });
+await logger.info('Payment processed', { orderId: 'ord_123' });
+// the active span's traceId and spanId are added to the entry
 ```
 
-### Database
-
-Write structured logs directly to your database — batched, non-blocking, with configurable flush intervals:
-
-```typescript
-// PostgreSQL
-const logger = createLogger({
-  appName: 'api',
-  environment: 'production',
-  transports: {
-    database: {
-      type: 'postgresql',
-      host: 'localhost',
-      port: 5432,
-      database: 'appdb',
-      table: 'logs',
-      username: 'dbuser',
-      password: process.env.DB_PASSWORD,
-      batchSize: 100, // write in batches of 100
-      flushInterval: 5000, // flush every 5 seconds
-    },
-  },
-});
-
-// MongoDB
-const logger = createLogger({
-  appName: 'api',
-  environment: 'production',
-  transports: {
-    database: {
-      type: 'mongodb',
-      connectionString: process.env.MONGO_URI,
-      database: 'appdb',
-      collection: 'logs',
-    },
-  },
-});
-
-// MySQL
-const logger = createLogger({
-  appName: 'api',
-  environment: 'production',
-  transports: {
-    database: {
-      type: 'mysql',
-      host: 'localhost',
-      database: 'appdb',
-      table: 'logs',
-      username: 'root',
-      password: process.env.MYSQL_PASSWORD,
-    },
-  },
-});
+`initOtelBridge()` uses `@opentelemetry/api` when it is installed and does nothing when it is not. To export logs rather than only correlate them, add `OtlpLogTransport` (see Transports above). Ready-made OTLP configs for Grafana, Axiom, Better Stack and a local Collector are in the [OTLP transport guide](https://logixia.github.io/logixia/guide/transports/otlp).
 
-// SQLite — great for local development and small apps
-const logger = createLogger({
-  appName: 'api',
-  environment: 'development',
-  transports: {
-    database: {
-      type: 'sqlite',
-      database: './logs/app.sqlite',
-      table: 'logs',
-    },
-  },
-});
-```
+→ [OpenTelemetry](https://logixia.github.io/logixia/guide/opentelemetry) · [OTLP transport](https://logixia.github.io/logixia/guide/transports/otlp)
 
-Multiple database targets are supported — pass an array:
+### Browser and edge
 
 ```typescript
-transports: {
-  database: [
-    { type: 'postgresql', host: 'primary-db', database: 'appdb', table: 'logs' },
-    { type: 'mongodb', connectionString: process.env.MONGO_URI, database: 'appdb', collection: 'logs' },
-  ],
-},
+import { createBrowserLogger } from 'logixia/browser';
+
+const logger = createBrowserLogger({ appName: 'web', level: 'info' });
+logger.info('Page loaded', { route: '/home' });
 ```
 
-### Analytics
+`logixia/browser` has no Node built-ins and ships a console transport plus a batching `BrowserRemoteTransport` that uses `fetch`. Working examples: [`examples/cloudflare-worker`](./examples/cloudflare-worker/) and [`examples/nextjs`](./examples/nextjs/).
 
-logixia includes built-in support for Datadog, Mixpanel, Segment, and Google Analytics. All analytics transports are batched and non-blocking.
+→ [Browser and edge](https://logixia.github.io/logixia/guide/browser-and-edge)
 
-**Datadog** — sends logs, metrics, and traces to your Datadog account:
+### Sampling and runtime levels
 
 ```typescript
-import { DataDogTransport } from 'logixia/transports';
-
 const logger = createLogger({
   appName: 'api',
-  environment: 'production',
-  transports: {
-    analytics: {
-      datadog: {
-        apiKey: process.env.DD_API_KEY!,
-        site: 'datadoghq.com', // or 'datadoghq.eu', 'us3.datadoghq.com', 'us5.datadoghq.com', 'ap1.datadoghq.com', 'ddog-gov.com'
-        service: 'api',
-        env: 'production',
-        enableLogs: true,
-        enableMetrics: true,
-        enableTraces: true,
-      },
-    },
+  namespaceLevels: { 'db.*': 'debug', '*': 'info' },
+  sampling: {
+    rate: 0.1, // keep 10% in steady state
+    traceConsistent: true, // keep or drop a whole trace together
+    adaptive: { errorRateThreshold: 0.05, boostRate: 1.0, windowMs: 10_000 },
   },
 });
 ```
 
-**Mixpanel:**
-
-```typescript
-transports: {
-  analytics: {
-    mixpanel: {
-      token: process.env.MIXPANEL_TOKEN!,
-      enableSuperProperties: true,
-      superProperties: { platform: 'web', version: '2.0' },
-    },
-  },
-},
-```
-
-**Segment:**
+When the windowed error rate crosses the threshold, the sample rate is raised until things calm down. You can also change levels in a running process: `registerLevelSignal(logger)` cycles the level on `SIGUSR2`, and `createLevelControlHandler(logger)` gives you an HTTP handler to mount behind your own auth.
 
-```typescript
-transports: {
-  analytics: {
-    segment: {
-      writeKey: process.env.SEGMENT_WRITE_KEY!,
-      enableBatching: true,
-      flushAt: 20,
-      flushInterval: 10_000,
-    },
-  },
-},
-```
+→ [Sampling](https://logixia.github.io/logixia/guide/sampling) · [Log levels](https://logixia.github.io/logixia/guide/log-levels) · [Graceful shutdown](https://logixia.github.io/logixia/guide/graceful-shutdown)
 
-**Google Analytics:**
+### Metrics
 
 ```typescript
-transports: {
-  analytics: {
-    googleAnalytics: {
-      measurementId: process.env.GA_MEASUREMENT_ID!,
-      apiSecret: process.env.GA_API_SECRET!,
-      enableEcommerce: false,
-    },
-  },
-},
-```
-
-### Multiple transports simultaneously
-
-All configured transports receive every log entry concurrently — no sequential bottleneck:
+import { createLogger, createMetricsPlugin } from 'logixia';
 
-```typescript
-const logger = createLogger({
-  appName: 'api',
-  environment: 'production',
-  transports: {
-    console: { format: 'json' },
-    file: { filename: 'app.log', dirname: './logs', maxSize: '100MB' },
-    database: {
-      type: 'postgresql',
-      host: 'localhost',
-      database: 'appdb',
-      table: 'logs',
-    },
-    analytics: {
-      datadog: {
-        apiKey: process.env.DD_API_KEY!,
-        service: 'api',
-      },
-    },
-  },
+const metrics = createMetricsPlugin({
+  http_requests_total: { type: 'counter', help: 'HTTP requests', labels: ['method', 'status'] },
 });
+const logger = createLogger({ appName: 'api' }).use(metrics);
 
-// One call → console + file + postgres + datadog. All concurrent. All non-blocking.
-await logger.info('Order placed', { orderId: 'ord_789' });
+await logger.info('request handled', { method: 'GET', status: 200 });
+app.get('/metrics', metrics.expressHandler()); // Prometheus text format
 ```
 
-### Slack and Discord webhook transports
+→ [Metrics](https://logixia.github.io/logixia/guide/metrics)
 
-Send alerts to a chat channel. Both default to `level: 'error'`, batch entries that arrive within `minIntervalMs` (default 1000) into one message, and cap a message at 10 entries (the rest are dropped and counted in the message).
-
-```typescript
-import { createLogger } from 'logixia';
-import { DiscordTransport, SlackTransport } from 'logixia';
+### CLI and log search
 
-const logger = createLogger({
-  appName: 'api',
-  transports: {
-    custom: [
-      new SlackTransport({ webhookUrl: process.env.SLACK_WEBHOOK_URL!, level: 'error' }),
-      new DiscordTransport({ webhookUrl: process.env.DISCORD_WEBHOOK_URL!, level: 'warn' }),
-    ],
-  },
-});
+```bash
+npx logixia tail ./logs/app.log --follow --filter level:error
+npx logixia search ./logs/app.log --query "payment failed"
+npx logixia explore ./logs/app.log   # interactive terminal explorer
 ```
 
-- The webhook URL is a secret. It must be `https:` on `hooks.slack.com` (Slack) or `discord.com` / `discordapp.com` (Discord) unless you pass `allowCustomUrl: true`. It is never logged and never appears in error messages (only the host does).
-- Logged text is escaped: Slack `&`, `<`, `>` (so `<!channel>` and `<@U123>` in log data cannot ping anyone); Discord markdown, plus `allowed_mentions: { parse: [] }` on every request.
-- Platform limits are enforced by truncation (Slack header 150 and data 2,500 chars; Discord title 256, description 4,096, 25 fields, 6,000 per message).
-- HTTP 429 waits for `Retry-After` (Discord: `retry_after`), then retries up to `maxRetries` (default 1). Other failures keep the batch queued with backoff; `flush()` rejects with a host-only error. The queue is bounded by `maxBufferSize` (default 1000, oldest dropped).
-- Also available: `username`, `iconEmoji` (Slack), `avatarUrl` (Discord), `filter`, `formatter`, `flush()` and `close()` (flushes pending entries).
+The CLI also has `stats`, `analyze`, `export` and `query`. For in-process search, `logixia/search` exports `SearchManager`, which indexes entries in memory and supports text, filters, natural-language queries and trace correlation.
 
-### Custom transport
+→ [CLI](https://logixia.github.io/logixia/guide/cli) · [Log search](https://logixia.github.io/logixia/guide/log-search)
 
-Implement `ITransport` to send logs anywhere — Slack, PagerDuty, S3, an internal queue:
+### More
 
-```typescript
-import type { ITransport, TransportLogEntry } from 'logixia';
-
-class SlackTransport implements ITransport {
-  name = 'slack';
-
-  async write(entry: TransportLogEntry): Promise<void> {
-    if (entry.level !== 'error' && entry.level !== 'fatal') return;
-    await fetch(process.env.SLACK_WEBHOOK_URL!, {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({
-        text: `*[${entry.level.toUpperCase()}]* ${entry.message}`,
-        attachments: [{ text: JSON.stringify(entry.data, null, 2) }],
-      }),
-    });
-  }
-
-  async close(): Promise<void> {
-    // optional cleanup
-  }
-}
+Typed fields with `createTypedLogger` and `defineLogSchema` ([typed logger](https://logixia.github.io/logixia/guide/typed-logger)), wide events / canonical log lines with `wideEventMiddleware` and `addEventFields`, a plugin API with `onInit` / `onLog` / `onError` / `onShutdown` hooks, and `createMockLogger` from `logixia/testing` for unit tests ([testing](https://logixia.github.io/logixia/guide/testing)).
 
-const logger = createLogger({
-  appName: 'api',
-  environment: 'production',
-  transports: {
-    custom: [new SlackTransport()],
-  },
-});
-```
+## Upgrading from 1.x
 
-The `write` method may return `void` or `Promise<void>` — both are supported. The `TransportLogEntry` shape is:
+2.0 has one breaking change: everything NestJS-specific moved from the root entry to `logixia/nest`.
 
-```typescript
-interface TransportLogEntry {
-  timestamp: Date;
-  level: string;
-  message: string;
-  data?: Record<string, unknown>;
-  context?: string;
-  traceId?: string;
-  appName?: string;
-  environment?: string;
-}
+```diff
+- import { LogixiaLoggerModule, LogMethod, InjectLogger } from 'logixia';
++ import { LogixiaLoggerModule, LogMethod, InjectLogger } from 'logixia/nest';
 ```
 
----
+The root `logixia` entry no longer loads `@nestjs/common`, so Express, Fastify and plain Node apps work without NestJS installed. → [Migration guide](https://logixia.github.io/logixia/guide/migration-v2)
 
-## Cloud adapters
+## Security
 
-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.
+- **Redaction** runs before any transport sees an entry, and HTTP logging redacts sensitive headers and query parameters by default.
+- **Secrets stay out of output.** Transport credentials (API keys, passwords, webhook URLs, tokens) are hidden from `JSON.stringify`, `util.inspect` and error messages.
+- **Supply chain.** Releases are published from CI with [npm provenance](https://docs.npmjs.com/generating-provenance-statements) through npm trusted publishing, so there is no long-lived npm token. The package has no install scripts and three runtime dependencies.
+- **Reporting.** Please report vulnerabilities privately through [GitHub private vulnerability reporting](https://github.com/Logixia/logixia/security/advisories/new). See [SECURITY.md](./SECURITY.md).
 
-### AWS CloudWatch
+→ [Security guide](https://logixia.github.io/logixia/guide/security)
 
-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.
+## Documentation and examples
 
-```typescript
-import { CloudWatchTransport } from 'logixia/cloudwatch';
+| Topic                                                                | Link                                                                         |
+| -------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
+| Full documentation                                                   | [logixia.github.io/logixia](https://logixia.github.io/logixia/)              |
+| Configuration reference                                              | [guide/configuration](https://logixia.github.io/logixia/guide/configuration) |
+| API reference                                                        | [guide/api](https://logixia.github.io/logixia/guide/api)                     |
+| Runnable examples (Express, Fastify, Hono, NestJS, Next.js, Workers) | [`examples/`](./examples/)                                                   |
+| Changelog                                                            | [CHANGELOG.md](./CHANGELOG.md)                                               |
 
-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: see "Credential sources" below — 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
-      }),
-    ],
-  },
-});
-```
+## Contributing
 
-With `emf: true`, any numeric field in your log data is published as a CloudWatch Metric in the `Logixia` namespace (override with `emfNamespace`), with a `level` dimension:
+Pull requests are welcome. For larger changes, open an issue first. Setup, scripts and the commit convention are in [CONTRIBUTING.md](./CONTRIBUTING.md).
 
-```typescript
-await logger.info('Request completed', { duration: 142, statusCode: 200 });
-// → CloudWatch Metrics in namespace "Logixia": duration, statusCode
+```bash
+git clone https://github.com/Logixia/logixia.git
+cd logixia
+npm ci --ignore-scripts
+npm test
 ```
 
-**Credential sources**, tried in this order (no SDK needed):
-
-1. `accessKeyId` / `secretAccessKey` / `sessionToken` in the transport config
-2. `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` / `AWS_SESSION_TOKEN`
-3. The shared credentials file: `~/.aws/credentials`, or `AWS_SHARED_CREDENTIALS_FILE`, using the `AWS_PROFILE` profile (default `default`)
-4. ECS container credentials: `AWS_CONTAINER_CREDENTIALS_RELATIVE_URI` or `AWS_CONTAINER_CREDENTIALS_FULL_URI` (with `AWS_CONTAINER_AUTHORIZATION_TOKEN` or `_FILE`)
-5. EC2 instance role through IMDSv2 (set `AWS_EC2_METADATA_DISABLED=true` to skip)
-
-Not supported: SSO, assume-role profiles, `credential_process`, web identity (EKS IRSA). If no source yields credentials, events stay buffered (and the buffer cap applies) rather than being dropped, and a warning is logged.
-
-The log group and stream are created on first use; an already-existing one is fine. The IAM role needs `logs:CreateLogGroup`, `logs:CreateLogStream` and `logs:PutLogEvents` (if the group and stream already exist, only `PutLogEvents` is required, and a failed `CreateLogGroup` is tolerated). Use `endpoint` to point at LocalStack or a VPC endpoint.
-
-### 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/gcp';
-
-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,
-      }),
-    ],
-  },
-});
-```
+## Sponsor
 
-### Azure Monitor
+logixia is free and MIT-licensed, and it is built and maintained by one person. If it saves you time, sponsoring keeps it moving:
 
-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/azure';
-
-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.
-
-### Core trace utilities
-
-```typescript
-import {
-  generateTraceId, // create a UUID v4 trace ID
-  getCurrentTraceId, // read trace ID from current async context
-  runWithTraceId, // run a callback inside a new trace context
-  setTraceId, // set trace ID in the CURRENT context (use sparingly)
-  extractTraceId, // extract a trace ID from a request-like object
-} from 'logixia';
-
-// Generate a new trace ID
-const traceId = generateTraceId();
-// → 'a3f1c2b4-...'
-
-// Run code inside a trace context — every logger.* call within the callback
-// (including across await boundaries and Promise.all) will carry this trace ID
-runWithTraceId(traceId, async () => {
-  await logger.info('Processing job'); // traceId attached automatically
-  await processItems(); // all nested async calls carry it too
-});
-
-// Read the trace ID currently in context (returns undefined if none is set)
-const current = getCurrentTraceId();
-
-// Extract a trace ID from an incoming request object
-const incomingTraceId = extractTraceId(req, {
-  header: ['traceparent', 'x-trace-id', 'x-request-id'],
-  query: ['traceId'],
-});
-```
-
-### Express / Fastify middleware
-
-```typescript
-import { traceMiddleware } from 'logixia';
-
-// Zero-config — reads from traceparent / x-trace-id / x-request-id / x-correlation-id
-// and generates a UUID v4 if none is present. Sets X-Trace-Id on the response.
-app.use(traceMiddleware());
-
-// With custom config:
-app.use(
-  traceMiddleware({
-    enabled: true,
-    generator: () => `req_${crypto.randomUUID()}`,
-    extractor: {
-      header: ['x-trace-id', 'traceparent'],
-      query: ['traceId'],
-    },
-  })
-);
-
-// Service layer — no parameters needed, trace ID propagates automatically
-class OrderService {
-  async createOrder(data: OrderData) {
-    await logger.info('Creating order', { items: data.items.length });
-    // ^ trace ID is automatically included
-    await this.processPayment(data);
-  }
-
-  async processPayment(data: OrderData) {
-    await logger.info('Processing payment', { amount: data.total });
-    // ^ same trace ID, propagated automatically through await
-  }
-}
-```
-
-The default headers checked for an incoming trace ID (in priority order) are: `traceparent`, `x-trace-id`, `x-request-id`, `x-correlation-id`, `trace-id`.
-
-### Hono
-
-On Node, Hono needs nothing beyond `runWithTraceId()` — wrap `await next()` and every log line in the request carries the trace ID:
-
-```typescript
-app.use(async (c, next) => {
-  const traceId =
-    extractTraceId({ headers: c.req.header() }, { header: DEFAULT_TRACE_HEADERS }) ??
-    generateTraceId();
-  await runWithTraceId(traceId, next);
-});
-```
-
-See [`examples/hono-example.ts`](./examples/hono-example.ts) (`npm run dev:hono`) for the full version.
-
-### Next.js (App Router)
-
-In a route handler on the Node.js runtime (`export const runtime = 'nodejs'`) the regular `logixia` entry works: wrap the handler body in `runWithTraceId(traceId, ...)`. See [`examples/nextjs/`](./examples/nextjs/) for a copy-paste route handler.
-
-### NestJS trace middleware
-
-The `TraceMiddleware` class integrates directly with NestJS's middleware system. `LogixiaLoggerModule.forRoot()` applies it automatically across all routes — no manual wiring needed:
-
-```typescript
-// Applied automatically by LogixiaLoggerModule.forRoot().
-// For manual use in a custom module:
-
-import { MiddlewareConsumer, Module, NestModule } from '@nestjs/common';
-import { TraceMiddleware } from 'logixia/nest';
-
-@Module({})
-export class AppModule implements NestModule {
-  configure(consumer: MiddlewareConsumer) {
-    consumer.apply(TraceMiddleware).forRoutes('*');
-  }
-}
-```
-
-### Kafka trace interceptor
-
-Propagates trace IDs through Kafka message handlers. Reads `traceId` / `trace_id` / `x-trace-id` from the message body or headers and runs the handler inside that trace context:
-
-```typescript
-import { KafkaTraceInterceptor } from 'logixia/nest';
-import { UseInterceptors, Controller } from '@nestjs/common';
-import { MessagePattern } from '@nestjs/microservices';
-
-@UseInterceptors(new KafkaTraceInterceptor())
-@Controller()
-export class OrdersConsumer {
-  @EventPattern('order.created')
-  async handle(@Payload() data: OrderCreatedEvent) {
-    // getCurrentTraceId() works here — extracted from the Kafka message body/headers
-    await logger.info('Processing order event', { orderId: data.orderId });
-  }
-}
-```
-
-> **Note:** Pass `new KafkaTraceInterceptor()` (an instance), not the class reference. The interceptor's constructor takes an optional config and is not a NestJS DI provider.
-
-### WebSocket trace interceptor
-
-Propagates trace IDs through WebSocket event handlers. Reads `traceId` from the message body, event payload, or handshake query:
-
-```typescript
-import { WebSocketTraceInterceptor } from 'logixia/nest';
-import { UseInterceptors, WebSocketGateway, SubscribeMessage } from '@nestjs/websockets';
-
-@UseInterceptors(new WebSocketTraceInterceptor())
-@WebSocketGateway({ namespace: '/events', cors: { origin: '*' } })
-export class EventsGateway {
-  @SubscribeMessage('ping')
-  async handlePing(@MessageBody() data: { traceId?: string }) {
-    // trace ID propagated from the WS message body / handshake headers
-    await logger.info('WS ping received', { traceId: getCurrentTraceId() });
-  }
-}
-```
-
-> **Note:** Pass `new WebSocketTraceInterceptor()` (an instance), not the class reference. `UseInterceptors` must be imported from `@nestjs/common`, not `@nestjs/websockets`.
-
-````
-
----
-
-## NestJS integration
-
-> **Upgrading from 1.x:** since 2.0.0, everything NestJS-specific lives in `logixia/nest` only.
-> Change `import { LogixiaLoggerModule, LogixiaLoggerService, LogixiaExceptionFilter, InjectLogger, LogMethod } from 'logixia'`
-> to `... from 'logixia/nest'`. The root `logixia` entry no longer loads `@nestjs/common`, so plain Node, Express and Fastify apps
-> work without NestJS installed.
-
-Drop-in module with zero boilerplate. Registers `TraceMiddleware` for all routes, provides `LogixiaLoggerService`, `KafkaTraceInterceptor`, and `WebSocketTraceInterceptor` via the global DI container.
-
-> **Full working example** — see [`examples/nestjs-app/`](./examples/nestjs-app/) for a complete NestJS app with Docker Compose (Postgres, MongoDB, Kafka, Kafdrop) that exercises every feature: `LogixiaLoggerModule`, `TraceMiddleware`, `LogixiaExceptionFilter`, `HttpLoggingInterceptor`, `WebSocketTraceInterceptor`, `KafkaTraceInterceptor`, `@LogMethod`, `child()` loggers, `timeAsync`, real Kafka producer + consumer.
->
-> ```bash
-> cd examples/nestjs-app
-> cp .env.example .env
-> docker compose up -d
-> curl http://localhost:3000/health
-> ```
-
-```typescript
-// app.module.ts
-import { Module } from '@nestjs/common';
-import { LogixiaLoggerModule } from 'logixia/nest';
-
-@Module({
-  imports: [
-    LogixiaLoggerModule.forRoot({
-      appName: 'nestjs-api',
-      environment: process.env.NODE_ENV ?? 'development',
-      traceId: true,
-      transports: {
-        console: {},
-        file: { filename: 'app.log', dirname: './logs', maxSize: '50MB' },
-      },
-    }),
-  ],
-})
-export class AppModule {}
-````
-
-**Async configuration** (for credentials from a config service):
-
-```typescript
-LogixiaLoggerModule.forRootAsync({
-  imports: [ConfigModule],
-  useFactory: async (config: ConfigService) => ({
-    appName: 'nestjs-api',
-    environment: config.get('NODE_ENV'),
-    traceId: true,
-    transports: {
-      database: {
-        type: 'postgresql',
-        host: config.get('DB_HOST'),
-        database: config.get('DB_NAME'),
-        password: config.get('DB_PASSWORD'),
-        table: 'logs',
-      },
-    },
-  }),
-  inject: [ConfigService],
-});
-```
-
-**Inject the logger** in any service or controller. Since `LogixiaLoggerModule` is globally scoped, no per-module import is needed:
-
-```typescript
-// orders.service.ts
-import { Injectable } from '@nestjs/common';
-import { LogixiaLoggerService } from 'logixia/nest';
-
-@Injectable()
-export class OrdersService {
-  constructor(private readonly logger: LogixiaLoggerService) {}
-
-  async createOrder(dto: CreateOrderDto) {
-    await this.logger.info('Creating order', { userId: dto.userId });
-    // ...
-  }
-}
-```
-
-**Feature-scoped child logger** — create a logger pre-scoped to a specific context string:
-
-```typescript
-// orders.module.ts
-import { Module } from '@nestjs/common';
-import { LogixiaLoggerModule } from 'logixia/nest';
-import { OrdersService } from './orders.service';
-
-@Module({
-  imports: [LogixiaLoggerModule.forFeature('OrdersModule')],
-  providers: [OrdersService],
-})
-export class OrdersModule {}
-```
-
-```typescript
-// orders.service.ts — inject the feature-scoped token
-import { Inject, Injectable } from '@nestjs/common';
-import { LOGIXIA_LOGGER_PREFIX, LogixiaLoggerService } from 'logixia/nest';
-
-@Injectable()
-export class OrdersService {
-  constructor(
-    @Inject(`${LOGIXIA_LOGGER_PREFIX}ORDERSMODULE`)
-    private readonly logger: LogixiaLoggerService
-  ) {}
-}
-```
-
-`LogixiaLoggerService` exposes the full `LogixiaLogger` API: `info`, `warn`, `error`, `debug`, `trace`, `verbose`, `logLevel`, `time`, `timeEnd`, `timeAsync`, `setLevel`, `getLevel`, `setContext`, `child`, `close`, `getCurrentTraceId`, and more.
-
-**Custom level proxy methods** — every key you add to `levelOptions.levels` automatically becomes a method on the service instance. Use `LogixiaLoggerService.create<T>(config)` (instead of `new`) to get full IntelliSense for those methods:
-
-```typescript
-const logger = LogixiaLoggerService.create({
-  levelOptions: {
-    levels: { error: 0, warn: 1, info: 2, kafka: 2, mysql: 2, payment: 1 },
-    colors: {
-      error: 'red',
-      warn: 'yellow',
-      info: 'blue',
-      kafka: 'magenta',
-      payment: 'brightYellow',
-    },
-  },
-});
-
-// Methods are created at construction time — no casting required
-await logger.kafka('Consumer rebalanced', { groupId: 'app-group' });
-await logger.mysql('Slow query detected', { query, ms: 1240 });
-await logger.payment('Charge captured', { txnId, amount: 99.99 });
-```
-
-**TraceId** — with `traceId: true`, every log line carries a correlation ID automatically. Use `runWithTraceId()` to scope a trace to a block (the `TraceMiddleware` does this per-request automatically):
-
-```typescript
-import { runWithTraceId } from 'logixia';
-
-await runWithTraceId(String(req.headers['x-request-id']), async () => {
-  await logger.info('Request received'); // traceId: "abc-123" in every line
-  await logger.kafka('Event published'); // same traceId
-});
-
-// Read the active traceId at any point
-const traceId = logger.getCurrentTraceId();
-```
-
-### @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/nest';
-
-@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/nest';
-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/nest';
-
-// In AppModule providers:
-{
-  provide: APP_FILTER,
-  useFactory: (logger: LogixiaLoggerService) => new LogixiaExceptionFilter(logger),
-  inject: [LogixiaLoggerService],
-}
-```
-
-The filter returns a consistent structured shape on every error:
-
-```json
-{
-  "success": false,
-  "error": {
-    "type": "validation_error",
-    "code": "ORD-001",
-    "message": "Order amount must be greater than zero.",
-    "param": "amount"
-  },
-  "meta": {
-    "request_id": "req_8579ef8ff7a64c3cbc752fd1cb9852df",
-    "timestamp": "2026-03-24T16:30:19.217Z",
-    "path": "/orders/boom",
-    "status": 400
-  },
-  "debug": {
-    "stack": "LogixiaException: Order amount must be greater than zero.\n    at ..."
-  }
-}
-```
-
-The `debug` block (stack trace, service, duration) is **off by default** and is never sent to clients unless you opt in, for example in local development only:
-
-```typescript
-new LogixiaExceptionFilter(undefined, undefined, {
-  exposeDebug: process.env.NODE_ENV === 'development',
-  // exposeCause: true,  // also include the underlying error message (may contain internal detail)
-});
-```
-
-And every log line carries `method`, `url`, `status`, `request_id` as structured fields — not a plain string:
-
-```
-WARN  [NestApplication] (traceId) [ORD-001] Order amount must be greater than zero.
-      { method: "GET", url: "/orders/boom", status: 400, request_id: "req_..." }
-
-ERROR [NestApplication] (traceId) DB connection timed out after 5000ms
-      { method: "GET", url: "/orders/crash", status: 500, request_id: "req_...", error: { ... } }
-```
-
----
-
-## 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 from the incoming request.
-// Generates a UUID v4 if the header is missing or invalid.
-// Sets X-Correlation-ID on the response.
-app.use(correlationMiddleware());
-
-// Custom config:
-app.use(
-  correlationMiddleware({
-    header: 'X-Correlation-ID', // header to read / write (matched case-insensitively). Default: 'x-correlation-id'
-    generate: () => crypto.randomUUID(), // used when no usable incoming ID. Default: crypto.randomUUID()
-    trustIncoming: true, // honour the header from the client. Default: true
-    setResponseHeader: true, // echo the ID back in the response. Default: true
-  })
-);
-```
-
-An incoming ID is only used if it is at most 128 characters long and contains only
-`A-Z`, `a-z`, `0-9`, `.`, `_`, `:` and `-`. Anything else (newlines, spaces, or base64-style
-`+`, `/`, `=`) is replaced with a freshly generated ID, so client-supplied text can't end up in
-every log line. Set `trustIncoming: false` to ignore the incoming header entirely and always
-generate a new ID. `correlationFastifyHook()` takes the same options.
-
-### Correlation Fastify hook
-
-```typescript
-import Fastify from 'fastify';
-import { correlationFastifyHook } from 'logixia/correlation';
-
-const app = Fastify();
-app.addHook('onRequest', correlationFastifyHook());
-```
-
-> **Full working example** — see [`examples/fastify-example.ts`](./examples/fastify-example.ts) (`npm run dev:fastify`) for request logging, trace IDs and redaction on Fastify.
-
-### 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
-    }),
-  ],
-});
-```
-
-**Cloudflare Workers** — see [`examples/cloudflare-worker/`](./examples/cloudflare-worker/) for a Worker that logs JSON, tags each request with `child({ requestId })` and flushes a `BrowserRemoteTransport` with `ctx.waitUntil()`. Pass `flushIntervalMs: 0` to the transport: Workers don't allow timers at global scope.
-
-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
-
-Redact sensitive fields before they reach **any** transport — passwords, tokens, PII, credit card numbers. Redaction is applied once before dispatch; no transport can accidentally log sensitive data. The original object is never mutated.
-
-**Path-based redaction** supports dot-notation, `*` (single segment wildcard), and `**` (any-depth wildcard):
-
-```typescript
-const logger = createLogger({
-  appName: 'api',
-  environment: 'production',
-  redact: {
-    paths: [
-      'password',
-      'token',
-      'accessToken',
-      'refreshToken',
-      '*.secret', // any field named 'secret' at one level deep
-      'req.headers.*', // all headers
-      'user.creditCard', // nested path
-      '**.password', // 'password' at any depth
-    ],
-    censor: '[REDACTED]', // default if omitted
-  },
-});
-
-await logger.info('User login', {
-  username: 'alice',
-  password: 'hunter2', // → '[REDACTED]'
-  token: 'eyJhbGc...', // → '[REDACTED]'
-  user: {
-    creditCard: '4111...', // → '[REDACTED]'
-    email: 'alice@example.com', // untouched
-  },
-});
-```
-
-**Regex-based redaction** — mask patterns in string values across all fields:
-
-```typescript
-const logger = createLogger({
-  appName: 'api',
-  environment: 'production',
-  redact: {
-    patterns: [
-      /Bearer\s+\S+/gi, // Authorization header values
-      /sk-[a-z0-9]{32,}/gi, // OpenAI / Stripe secret keys
-      /\b\d{4}[\s-]?\d{4}[\s-]?\d{4}[\s-]?\d{4}\b/g, // credit card numbers
-    ],
-  },
-});
-```
-
-Both `paths` and `patterns` can be combined in the same config.
-
-Path rules follow these conventions:
-
-- Matching is case-insensitive, so `req.headers.authorization` also redacts `Authorization`.
-- Array elements are addressed by index: `users.*.password` and `users.0.password` both match, and the older index-free form `users.password` still works. Nested arrays are walked the same way.
-- Circular references are printed as `[Circular]` instead of throwing.
-- Plain objects, class instances (ORM entities, documents) and arrays are walked. Built-ins such as `URL`, `Date`, `Buffer`, `Map`, `Set` and `Error` pass through unchanged unless a rule targets them directly.
-
----
-
-## Timer API
-
-Measure the duration of any operation — synchronous or async. The result is logged automatically when the timer ends:
-
-```typescript
-// Manual start/stop
-logger.time('db-query');
-const rows = await db.query('SELECT * FROM orders');
-await logger.timeEnd('db-query');
-// → logs: Timer 'db-query' finished { duration: '42ms', startTime: '...', endTime: '...' }
-
-// Wrap an async function — timer starts before and stops after, even if the function throws
-const result = await logger.timeAsync('process-batch', async () => {
-  return await processBatch(items);
-});
-```
-
-`timeEnd` returns the duration in milliseconds so you can use it in your own logic:
-
-```typescript
-const ms = await logger.timeEnd('db-query');
-if (ms && ms > 500) {
-  await logger.warn('Slow query detected', { durationMs: ms });
-}
-```
-
----
-
-## Field management
-
-Control which fields appear in log output at runtime, without changing config:
-
-```typescript
-// Disable fields you don't need in a specific context
-logger.disableField('traceId');
-logger.disableField('appName');
-
-// Re-enable them
-logger.enableField('traceId');
-
-// Check whether a field is currently active
-const isOn = logger.isFieldEnabled('timestamp'); // true
-
-// Inspect the current state of all fields
-const state = logger.getFieldState();
-// → { timestamp: true, level: true, appName: false, traceId: false, ... }
-
-// Reset all fields back to the config defaults
-logger.resetFieldState();
-```
-
-Available field names: `timestamp`, `level`, `appName`, `service`, `traceId`, `message`, `payload`, `timeTaken`, `context`, `requestId`, `userId`, `sessionId`, `environment`.
-
----
-
-## Transport level control
-
-By default, every transport receives every log entry that passes the global level filter. You can narrow a specific transport to only receive a subset of levels:
-
-```typescript
-// Only send errors to the database transport — no noise from info/debug
-logger.setTransportLevels('database-0', ['error', 'warn']);
-
-// Check what levels a transport is currently configured for
-const levels = logger.getTransportLevels('database-0'); // ['error', 'warn']
-
-// List all registered transport IDs
-const ids = logger.getAvailableTransports(); // ['console', 'file-0', 'database-0']
-
-// Remove all level overrides — all transports receive everything again
-logger.clearTransportLevelPreferences();
-```
-
-## Transport filter predicate
-
-Every transport (database, file, console, analytics, custom) accepts an optional `filter` function. It runs after the level check and lets you express any condition over the full log entry — by context, message content, payload fields, or anything else. Return `false` to skip the entry for that transport only; other transports are unaffected.
-
-```typescript
-const logger = createLogger({
-  appName: 'api',
-  environment: 'production',
-  transports: {
-    // Only persist error/warn entries that come from PaymentService to the DB
-    database: {
-      type: 'mongodb',
-      connectionString: process.env.MONGO_URI,
-      database: 'appdb',
-      collection: 'logs',
-      filter: (entry) =>
-        ['error', 'warn'].includes(entry.level) && entry.context === 'PaymentService',
-    },
-
-    // Write everything to the main file, but exclude noisy health-check pings
-    file: {
-      filename: 'app.log',
-      dirname: './logs',
-      filter: (entry) => entry.message !== 'health check',
-    },
-
-    // Console gets everything — no filter
-    console: { colorize: true },
-  },
-});
-```
-
-The `filter` predicate receives a `TransportLogEntry`:
-
-```typescript
-interface TransportLogEntry {
-  timestamp: Date;
-  level: string; // 'error' | 'warn' | 'info' | 'debug' | 'trace' | 'verbose' | string
-  message: string;
-  data?: Record<string, unknown>;
-  context?: string; // set via logger.child('MyService') or setContext()
-  traceId?: string;
-  appName?: string;
-  environment?: string;
-}
-```
-
-`filter` and `level` are independent — both must pass for an entry to be written. Use `level` for threshold filtering (everything at or above `warn`) and `filter` for precise, field-level rules.
-
----
-
-## Log search
-
-Query your in-memory log history without shipping to Elasticsearch, Datadog, or any external service. Useful in development and lightweight production setups:
-
-```typescript
-import { SearchManager } from 'logixia';
-
-const search = new SearchManager({ maxEntries: 10_000 });
-
-// Index a batch of entries (from a file, database query, or any source)
-await search.index(logEntries);
-
-// Search by text query, level, and time range
-const results = await search.search({
-  query: 'payment failed',
-  level: 'error',
-  from: new Date('2025-01-01'),
-  to: new Date(),
-  limit: 50,
-});
-// → sorted by relevance, full metadata included
-```
-
----
-
-## OpenTelemetry
-
-W3C `traceparent` and `tracestate` headers are extracted from incoming requests and attached to every log entry automatically — enabling correlation between distributed traces and log events in Jaeger, Zipkin, Honeycomb, Datadog, and similar tools:
-
-```typescript
-const logger = createLogger({
-  appName: 'checkout-service',
-  environment: 'production',
-  traceId: {
-    enabled: true,
-    extractor: {
-      header: ['traceparent', 'tracestate', 'x-trace-id'],
-    },
-  },
-});
-
-// The traceparent header from the incoming request is stored as the trace ID
-// and included in every log entry automatically.
-app.post('/checkout', async (req, res) => {
-  await logger.info('Checkout initiated', { cartId: req.body.cartId });
-  // → log carries the W3C traceparent from the request
-});
-```
-
----
-
-## OTLP logs export (OpenTelemetry-native)
-
-logixia doesn't just _read_ the active OTel span (above) — it can _emit_ logs in the **OTLP/HTTP** format so they land in any OpenTelemetry backend (Grafana Loki, OpenObserve, Better Stack, Axiom, Datadog, SigNoz…) already correlated with traces. No `@opentelemetry/*` packages required (that JS API is still alpha) — the OTLP JSON is built directly, with proper `SeverityNumber` mapping (DEBUG=5, INFO=9, WARN=13, ERROR=17) and resource attributes.
-
-```typescript
-import { OtlpLogTransport } from 'logixia';
-
-const logger = createLogger({
-  appName: 'api',
-  transports: {
-    custom: [
-      new OtlpLogTransport({
-        url: 'http://localhost:4318/v1/logs',
-        serviceName: 'api',
-        serviceVersion: '1.4.0',
-        environment: 'production',
-        headers: { 'x-api-key': process.env.OTLP_KEY! },
-      }),
-    ],
-  },
-});
-// Every log is exported as an OTel LogRecord with traceId/spanId for native
-// trace↔log correlation. Buffers drain on close() — no loss on shutdown.
-```
-
----
-
-## Wide events / canonical log lines
-
-Instead of scattering a request's story across many narrow log lines that you have to JOIN during an incident, emit **one dense, structured event per request** — the "canonical log line" (Stripe) / "wide event" (Honeycomb, _Observability 2.0_) pattern. Fields accumulate as the request flows through middleware and business logic via `AsyncLocalStorage`, then the whole event is emitted **once** — in a teardown path so it fires even on errors.
-
-```typescript
-import { wideEventMiddleware, addEventFields } from 'logixia';
-
-// One canonical line per request, auto-emitted on response finish/close:
-app.use(wideEventMiddleware(logger)); // pre-fills method, url, ip, status, duration
-
-app.get('/checkout', (req, res) => {
-  addEventFields({ userId: req.user.id, planTier: 'pro' }); // from anywhere
-  addEventFields({ dbQueries: 4, cacheHit: true });
-  res.json({ ok: true });
-  // → ONE log line: { method, url, statusCode, durationMs, userId, planTier,
-  //                   dbQueries, cacheHit, traceId } — no JOINs at query time
-});
-```
-
-Or wrap any unit of work manually — the event is emitted once, even if the callback throws:
-
-```typescript
-import { withWideEvent, addEventFields } from 'logixia';
-
-await withWideEvent(logger, { job: 'reindex' }, async () => {
-  addEventFields({ shard: 3 });
-  await doWork(); // throws? → event still emitted with { error: true, errorMessage }
-});
-```
-
----
-
-## Dynamic runtime reconfiguration
-
-Change log levels in a **running** process — no restart — to chase a bug without raising global volume. This is the single most-requested feature across the Winston ([#1107](https://github.com/winstonjs/winston/issues/1107)) and Pino ([#206](https://github.com/pinojs/pino/issues/206)) trackers; logixia ships it first-class.
-
-```typescript
-import { registerLevelSignal, createLevelControlHandler } from 'logixia';
-
-// 1. Per-namespace level, live:
-logger.setNamespaceLevels({ 'db.*': 'debug', '*': 'info' }); // db.* → debug now
-
-// 2. Cycle the global level with one signal (kill -USR2 <pid>):
-registerLevelSignal(logger); // info → debug → trace → … → info
-
-// 3. Ops endpoint (mount behind your auth):
-app.all('/admin/log-level', createLevelControlHandler(logger));
-// GET  → { level, namespaceLevels }
-// POST { "level": "debug", "namespaceLevels": { "db.*": "trace" } }
-```
-
----
-
-## Adaptive sampling
-
-On top of static / per-level / trace-consistent sampling + a token-bucket rate cap, logixia can **boost the sample rate automatically during an incident** — so high-volume cost control never costs you the logs that matter most. When the windowed error rate crosses a threshold, sampling lifts toward 1.0; in steady state it relaxes back to the base rate.
-
-```typescript
-const logger = createLogger({
-  appName: 'api',
-  sampling: {
-    rate: 0.1, // keep 10% in steady state
-    adaptive: {
-      errorRateThreshold: 0.05, // ≥5% errors in the window…
-      boostRate: 1.0, // …keep everything until it subsides
-      windowMs: 10_000,
-    },
-  },
-});
-```
-
-`maxLogsPerSecond` is always enforced after the rate decision, including with `traceConsistent: true` (a kept trace can still lose entries once the cap is hit). With `traceConsistent`, a trace's keep/drop decision is remembered in a bounded LRU (100k traces, dropped after 5 minutes idle) and survives stats resets; logs written outside any trace are sampled one by one.
-
----
-
-## Robust serialization
-
-logixia never throws while serializing a log payload. Circular references become `[Circular]`, and — going beyond what Winston/Pino do — **BigInt** is handled (raw `JSON.stringify` throws on it) and you can opt into **true round-trippable decycling** for shared/circular graphs:
-
-```typescript
-import { safeStringify, decycleValue, retrocycle } from 'logixia';
-
-safeStringify({ id: 9007199254740993n, self: obj }); // BigInt + cycle safe
-const json = safeStringify(graph, { decycle: true }); // $ref pointers, not [Circular]
-const restored = retrocycle(JSON.parse(json)); // shared refs reconstructed
-```
-
----
-
-## Graceful shutdown
-
-Ensures all buffered log entries are flushed to every transport before the process exits. Critical for database and analytics transports that batch writes.
-
-> **Reliability guarantee — no log loss on shutdown.** The most painful, still-open bug in the most popular Node logger is exactly this: Pino's [#1705](https://github.com/pinojs/pino/issues/1705) ("Logs are not flushed, missing log entries after `process.exit()`") has been open since 2023, with its maintainer noting a race condition in the transport flush path that "I won't be able to fix it anytime soon." It recurs across [#542](https://github.com/pinojs/pino/issues/542), [#1774](https://github.com/pinojs/pino/issues/1774), [#1889](https://github.com/pinojs/pino/issues/1889), and [#2054](https://github.com/pinojs/pino/issues/2054). logixia is built the other way around: **every** batching/async transport (database, analytics, CloudWatch/GCP/Azure, worker-thread, browser, OTLP) drains its buffer synchronously on `close()` with bounded retry, and the SIGTERM/SIGINT handler is guarded against concurrent signals so a second Ctrl+C can't truncate the flush. Each guarantee is covered by a regression test.
-
-The simplest approach is to set `gracefulShutdown: true` in config — logixia registers SIGTERM and SIGINT handlers automatically:
-
-```typescript
-const logger = createLogger({
-  appName: 'api',
-  environment: 'production',
-  gracefulShutdown: true,
-  transports: { database: { type: 'postgresql' /* ... */ } },
-});
-// SIGTERM / SIGINT will flush all transports before exit. No extra code needed.
-```
-
-For more control, pass a config object:
-
-```typescript
-const logger = createLogger({
-  appName: 'api',
-  environment: 'production',
-  gracefulShutdown: {
-    enabled: true,
-    timeout: 10_000, // wait up to 10 s; force-exits after
-    signals: ['SIGTERM', 'SIGINT', 'SIGHUP'],
-    exit: 'auto', // 'auto' | 'always' | 'never'
-  },
-  transports: {/* ... */},
-});
-```
-
-**Who ends the process.** By default (`exit: 'auto'`) logixia flushes and then exits only if its handler is the only listener for that signal. If your app registers its own `SIGTERM` handler (`server.close()`, NestJS shutdown hooks, ...), logixia just flushes and leaves the exit to you, so your cleanup is never cut off. When logixia does exit it uses `128 + signal number` (143 for SIGTERM, 130 for SIGINT), so supervisors see a signal exit. Set `exit: 'always'` or `exit: 'never'` to override. Registered loggers are also flushed (not closed) on `beforeExit`, so an app that keeps logging after the event loop first drains still writes.
-
-`flushOnExit` is configured by its first call; later calls with different `timeout`, `signals`, `exit` or hooks print a warning and are ignored.
-
-You can also call `flushOnExit` directly with lifecycle hooks:
-
-```typescript
-import { flushOnExit } from 'logixia';
-
-flushOnExit({
-  timeout: 5000,
-  beforeFlush: async () => {
-    // stop accepting new requests
-  },
-  afterFlush: async () => {
-    // any cleanup after all logs are written
-  },
-});
-```
-
-Or flush and close manually — useful in Kubernetes SIGTERM handlers:
-
-```typescript
-process.on('SIGTERM', async () => {
-  // close() flushes all transports first, then closes connections.
-  // Any log calls that arrive during the flush (e.g. from Kafka/MongoDB
-  // disconnect handlers) are still written before the gate closes.
-  await logger.close();
-  process.exit(0);
-});
-```
-
-For health monitoring:
-
-```typescript
-const { healthy, details } = await logger.healthCheck();
-// → { healthy: true, details: { 'database-0': { ready: true, metrics: { logsWritten: 1042, ... } } } }
-```
-
----
-
-## 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`:
-
-```typescript
-// Log methods
-await logger.error(message: string | Error, data?: Record<string, unknown>): Promise<void>
-await logger.warn(message: string, data?: Record<string, unknown>): Promise<void>
-await logger.info(message: string, data?: Record<string, unknown>): Promise<void>
-await logger.debug(message: string, data?: Record<string, unknown>): Promise<void>
-await logger.trace(message: string, data?: Record<string, unknown>): Promise<void>
-await logger.verbose(message: string, data?: Record<string, unknown>): Promise<void>
-await logger.logLevel(level: string, message: string, data?): Promise<void>  // dynamic dispatch
-
-// Timer API
-logger.time(label: string): void
-await logger.timeEnd(label: string): Promise<number | undefined>          // returns ms
-await logger.timeAsync<T>(label: string, fn: () => Promise<T>): Promise<T>
-
-// Level management
-logger.setLevel(level: string): void
-logger.getLevel(): string
-
-// Context management
-logger.setContext(context: string): void
-logger.getContext(): string | undefined
-logger.child(context: string, data?: Record<string, unknown>): ILogger
-
-// Field management
-logger.enableField(fieldName: string): void
-logger.disableField(fieldName: string): void
-logger.isFieldEnabled(fieldName: string): boolean
-logger.getFieldState(): Record<string, boolean>
-logger.resetFieldState(): void
-
-// Transport management
-logger.getAvailableTransports(): string[]
-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>
-await logger.healthCheck(): Promise<{ healthy: boolean; details: Record<string, unknown> }>
-```
-
-**Utility exports** available at the top level:
-
-```typescript
-import {
-  generateTraceId, // () => string — UUID v4
-  getCurrentTraceId, // () => string | undefined
-  runWithTraceId, // (id, fn, data?) => T
-  setTraceId, // (id, data?) => void
-  extractTraceId, // (req, config) => string | undefined
-  isError, // (value) => value is Error
-  normalizeError, // (value) => Error
-  serializeError, // (error, options?) => Record<string, unknown>
-  applyRedaction, // (payload, config) => payload
-  flushOnExit, // (options?) => void
-  registerForShutdown, // (logger) => void
-  deregisterFromShutdown, // (logger) => void
-  resetShutdownHandlers, // () => void — useful in tests
-} from 'logixia';
-
-// NestJS extras (requires @nestjs/common):
-import {
-  InjectLogger, // @InjectLogger() parameter decorator
-  LogMethod, // @LogMethod() method decorator
-  LogixiaExceptionFilter, // global exception filter
-} from 'logixia/nest';
-
-// Cloud transports (subpath imports):
-import { CloudWatchTransport } from 'logixia/cloudwatch';
-import { GCPTransport } from 'logixia/gcp';
-import { AzureMonitorTransport } from 'logixia/azure';
-
-// 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';
-```
-
----
-
-## CLI tool
-
-logixia ships a CLI for working with log files directly. After installing, the `logixia` command is available via `npx` or globally:
-
-```bash
-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
-# Show last 10 lines
-npx logixia tail ./logs/app.log
-
-# Follow and filter by level
-npx logixia tail ./logs/app.log --follow --filter level:error
-
-# Filter by a specific field value
-npx logixia tail ./logs/app.log --follow --filter user_id:usr_123
-
-# Color output by log level
-npx logixia tail ./logs/app.log --highlight level
-```
-
-**`search`** — query a log file with field-specific or full-text search:
-
-```bash
-# Full-text search
-npx logixia search ./logs/app.log --query "payment failed"
-
-# Field-specific search
-npx logixia search ./logs/app.log --query "level:error"
-npx logixia search ./logs/app.log --query "user_id:usr_123"
-
-# Output as JSON or table
-npx logixia search ./logs/app.log --query "timeout" --format json
-npx logixia search ./logs/app.log --query "timeout" --format table
-```
-
-**`stats`** — summarize a log file with counts by level and time distribution:
-
-```bash
-npx logixia stats ./logs/app.log
-```
-
-**`analyze`** — run pattern recognition and anomaly detection across a log file:
-
-```bash
-npx logixia analyze ./logs/app.log
-```
-
-**`export`** — convert a log file between formats (JSON, CSV, text):
-
-```bash
-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
-
-```typescript
-interface LoggerConfig {
-  // Required
-  appName: string;
-  environment: 'development' | 'production';
-
-  // Output format (applies to console and file text output)
-  format?: {
-    timestamp?: boolean; // include ISO timestamp. Default: true
-    colorize?: boolean; // ANSI color output. Default: true
-    json?: boolean; // JSON lines output. Default: false
-  };
-
-  // Trace ID — true enables UUID v4 auto-generation; pass an object for custom config
-  traceId?:
-    | boolean
-    | {
-        enabled: boolean;
-        generator?: () => string; // custom ID generator
-        contextKey?: string;
-        extractor?: {
-          header?: string | string[]; // headers to check
-          query?: string | string[]; // query params to check
-          body?: string | string[]; // body fields to check
-          params?: string | string[]; // route params to check
-        };
-      };
-
-  // Suppress all output. Useful in test environments
-  silent?: boolean;
-
-  // Level configuration
-  levelOptions?: {
-    level?: 'error' | 'warn' | 'info' | 'debug' | 'trace' | 'verbose' | string;
-    levels?: Record<string, number>; // custom level priority map
-    colors?: Record<string, LogColor>; // color per level
-  };
-
-  // Visible fields in text output
-  fields?: Partial<
-    Record<
-      | 'timestamp'
-      | 'level'
-      | 'appName'
-      | 'service'
-      | 'traceId'
-      | 'message'
-      | 'payload'
-      | 'timeTaken'
-      | 'context'
-      | 'requestId'
-      | 'userId'
-      | 'sessionId'
-      | 'environment',
-      string | boolean
-    >
-  >;
-
-  // Field redaction — applied before any transport receives the entry
-  redact?: {
-    paths?: string[]; // dot-notation paths; supports * and ** wildcards
-    patterns?: RegExp[]; // regex patterns applied to string values
-    censor?: string; // replacement string. Default: '[REDACTED]'
-  };
-
-  // Per-namespace log level overrides; keys are patterns, values are levels
-  namespaceLevels?: Record<string, string>;
-
-  // Graceful shutdown — true for defaults, or a config object for full control
-  gracefulShutdown?:
-    | boolean
-    | {
-        enabled: boolean;
-        timeout?: number; // ms to wait before force-exit. Default: 5000
-        signals?: NodeJS.Signals[]; // Default: ['SIGTERM', 'SIGINT']
-      };
-
-  // Transports — all optional, all concurrent
-  transports?: {
-    console?: {
-      level?: string;
-      colorize?: boolean;
-      timestamp?: boolean;
-      format?: 'json' | 'text';
-      filter?: (entry: TransportLogEntry) => boolean;
-    };
-
-    file?:
-      | {
-          filename: string;
-          dirname?: string;
-          maxSize?: string | number; // e.g. '50MB', '1GB', or bytes
-          maxFiles?: number;
-          datePattern?: string; // e.g. 'YYYY-MM-DD'
-          zippedArchive?: boolean;
-          format?: 'json' | 'text' | 'csv';
-          level?: string;
-          batchSize?: number;
-          flushInterval?: number; // ms
-          maxQueue?: number; // cap on unwritten entries held in memory. Default: no cap
-          queuePolicy?: 'drop-oldest' | 'drop-newest' | 'block'; // Default: 'drop-oldest'
-          rotation?: {
-            interval?: '1h' | '6h' | '12h' | '1d' | '1w' | '1m' | '1y';
-            maxSize?: string | number;
-            maxFiles?: number;
-            compress?: boolean;
-            shouldRotate?: (
-              currentFile: string,
-              stats: { size: number; created: Date; modified: Date }
-            ) => boolean;
-          };
-          filter?: (entry: TransportLogEntry) => boolean;
-        }
-      | Array<FileTransportConfig>; // array for multiple file targets
-
-    database?:
-      | {
-          type: 'postgresql' | 'mysql' | 'mongodb' | 'sqlite';
-          host?: string;
-          port?: number;
-          database: string;
-          table?: string; // SQL databases
-          collection?: string; // MongoDB
-          connectionString?: string; // MongoDB connection string
-          username?: string;
-          password?: string;
-          ssl?: boolean;
-          level?: string; // minimum level threshold for this transport
-          batchSize?: number;
-          flushInterval?: number; // ms
-          filter?: (entry: TransportLogEntry) => boolean; // entry-level predicate
-        }
-      | Array<DatabaseTransportConfig>;
-
-    analytics?: {
-      datadog?: {
-        apiKey: string;
-        site?: 'datadoghq.com' | 'datadoghq.eu' | 'us3.datadoghq.com' | 'us5.datadoghq.com';
-        service?: string;
-        version?: string;
-        env?: string;
-        enableMetrics?: boolean;
-        enableLogs?: boolean;
-        enableTraces?: boolean;
-      };
-      mixpanel?: {
-        token: string;
-        distinct_id?: string;
-        enableSuperProperties?: boolean;
-        superProperties?: Record<string, unknown>;
-      };
-      segment?: {
-        writeKey: string;
-        dataPlaneUrl?: string;
-        enableBatching?: boolean;
-        flushAt?: number;
-        flushInterval?: number;
-      };
-      googleAnalytics?: {
-        measurementId: string;
-        apiSecret: string;
-        clientId?: string;
-        enableEcommerce?: boolean;
-      };
-    };
-
-    custom?: ITransport[]; // any object implementing { name, write, close? }
-  };
-}
-```
-
----
-
-## Sponsor
-
-logixia is free and MIT-licensed, and it is built and maintained by one person. If it saves you time, sponsoring keeps it moving:
-
-- [GitHub Sponsors](https://github.com/sponsors/webcoderspeed)
-- [PayPal](https://paypal.me/Sniperspeed)
+- [GitHub Sponsors](https://github.com/sponsors/webcoderspeed)
+- [PayPal](https://paypal.me/Sniperspeed)
 
 `npm fund logixia` prints the same links.
 
----
-
-## Contributing
-
-```bash
-git clone https://github.com/Logixia/logixia.git
-cd logixia
-npm install
-npm test
-```
-
-Pull requests are welcome. For significant changes, please open an issue first to discuss what you'd like to change.
-
----
-
 ## License
 
-[MIT](https://opensource.org/licenses/MIT) © [Sanjeev Sharma](https://github.com/webcoderspeed)
+[MIT](./LICENSE) © [Sanjeev Sharma](https://github.com/webcoderspeed)