logixia 2.0.4 → 2.0.7

package/README.md

@@ -1,2771 +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:
-
-```typescript
-logger.setLevel('debug');
-console.log(logger.getLevel()); // 'debug'
-```
+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/).
 
-### Per-namespace log levels
+→ [NestJS guide](https://logixia.github.io/logixia/guide/nestjs)
 
-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
-```
-
-Environment variable overrides use the pattern `LOGIXIA_LEVEL_<NS>` where `<NS>` is the first segment of the namespace, uppercased:
-
-```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
+await logger.info('Login', { user: 'alice', password: 'hunter2' });
+// → {"user":"alice","password":"[REDACTED]"}
 ```
 
----
+Paths support `*` (one segment) and `**` (any depth), match case-insensitively, and the input object is never mutated. Circular references are printed as `[Circular]`.
 
-## 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
-    },
-  },
-});
-```
+import { createLogger, OtlpLogTransport, SlackTransport } from 'logixia';
 
-### File with rotation
-
-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,
-    },
-  },
-},
-```
-
-With a `rotation` block every file is timestamped, including the one being written.
+import { createLogger, initOtelBridge } from 'logixia';
 
-Multiple file transports are supported — pass an array:
+initOtelBridge(); // call once, after your OTel SDK starts
 
-```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
-
-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).
+→ [Metrics](https://logixia.github.io/logixia/guide/metrics)
 
-```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 { createExpressContextMiddleware, createFastifyContextHook } from 'logixia';
-
-// Express: trace ID = first present header of traceIdHeader (default
-// DEFAULT_TRACE_HEADERS: traceparent, x-trace-id, x-request-id, x-correlation-id,
-// trace-id; traceparent is parsed to its 32-hex trace id), else request.id, else a
-// generated UUID. The ID is available via getCurrentTraceId() and is the logger's
-// top-level traceId for everything inside the request. No response header is set
-// unless you ask for one with responseHeader.
-app.use(createExpressContextMiddleware({ responseHeader: 'X-Trace-Id' }));
-
-// Fastify: same resolution; fastify's default counter ids ('req-1', ...) are never
-// used as trace IDs. Also shared with createFastifyPlugin() from 'logixia/middleware'.
-// traceIdHeader accepts a single name or a list; responseHeader works as above.
-fastify.addHook('onRequest', createFastifyContextHook());
-
-// Prefer full control? Wrap the request yourself:
-app.use((req, res, next) => {
-  const traceId =
-    extractTraceId(req, { header: DEFAULT_TRACE_HEADERS, query: ['traceId'] }) ?? generateTraceId();
-  res.setHeader('X-Trace-Id', traceId);
-  runWithTraceId(traceId, () => next());
-});
-
-// Request/response logging (separate from tracing) lives in 'logixia/middleware':
-//   app.use(createExpressMiddleware(logger));
-//   await fastify.register(createFastifyPlugin(logger));
-// NestJS: import { TraceMiddleware } from 'logixia/nest';
-
-// 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
-    }),
-  ],
-});
-```
-
-Delivery failures (network errors and non-OK HTTP statuses) are counted in `failedFlushes` / `lastError` and passed to the optional `onError` callback. A throttled (at most one per minute) console report containing only the error name, HTTP status and endpoint host is printed everywhere except real browser pages, where it is silent by default; set `silent: true` or `silent: false` to override. Entries written to the transport from inside `onError` or while a report is printed are dropped (counted in `dropped`) to avoid feedback loops.
-
-**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/search';
-
-const search = new SearchManager({ maxIndexSize: 10_000 });
-
-// Index a batch of entries (from a file, database query, or any source)
-await search.indexLogs(logEntries); // or: await search.indexLog(entry)
-
-// Search by text, with filters and options
-const results = await search.search(
-  'payment failed',
-  { levels: ['error'], timeRange: { start: new Date('2025-01-01'), end: new Date() } },
-  { limit: 50 }
-);
-// → sorted by relevance, each result is { log, score, ... }
-
-const nl = await search.naturalLanguageSearch('payment errors'); // plain-English query
-const trace = await search.correlateByTraceId('req-001'); // every log of one request
-```
-
-The same code runs as [`examples/search-readme.ts`](examples/search-readme.ts).
-
----
-
-## 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.
-```
-
-Import it from `logixia` or `logixia/transports`. Ready-made configs (URL and auth headers) for Grafana Loki / Grafana Cloud, Axiom, Better Stack and a local OpenTelemetry Collector are in [docs/otlp-recipes.md](docs/otlp-recipes.md).
-
----
-
-## 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)