![\"npm](\"https://img.shields.io/npm/v/logixia\")
\n ![\"npm](\"https://img.shields.io/npm/dm/logixia\")
\n ![\"bundle](\"https://img.shields.io/bundlephobia/minzip/logixia\")
\n ![\"CI\"/](\"https://github.com/Logixia/logixia/actions/workflows/ci.yml/badge.svg\"){kind=icon}
\n ![\"MIT\"/](\"https://img.shields.io/badge/License-MIT-blue.svg\"){kind=icon}
\n ![\"TypeScript\"/](\"https://img.shields.io/badge/TypeScript-5.0%2B-blue\"){kind=icon}
\n ![\"website\"/](\"https://img.shields.io/badge/website-logixia.github.io-a855f7\"){kind=icon}
\n\n The async-first TypeScript logger that ships complete.
\n Wide events · OpenTelemetry (OTLP) · Runtime log levels · Redaction · Adaptive sampling
\n NestJS · Express · Fastify · Database · Cloud · Tracing · Prometheus · Browser\n
\n \n \n
\n Website ·\n GitHub ·\n npm ·\n Issues\n
\n\n---\n\n## The logging setup you copy-paste into every new project\n\n```bash\n# The pino route:\nnpm install pino pino-pretty pino-roll pino-redact pino-nestjs pino-http\n\n# The winston route:\nnpm install winston winston-daily-rotate-file\n# ...then wire 4 separate config objects\n# ...then discover there's no built-in DB transport\n# ...then discover request tracing is manual\n# ...then discover both block your event loop under I/O pressure\n\n# Or:\nnpm install logixia\n```\n\nlogixia 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.\n\n```typescript\nimport { createLogger } from 'logixia';\n\nconst logger = createLogger({\n appName: 'api',\n environment: 'production',\n transports: {\n console: { format: 'json' },\n file: { filename: 'app.log', dirname: './logs', maxSize: '50MB' },\n database: { type: 'postgresql', host: 'localhost', database: 'appdb', table: 'logs' },\n },\n});\n\nawait logger.info('Server started', { port: 3000 });\n// Writes to console + file + postgres simultaneously. Non-blocking. Done.\n```\n\n---\n\n## Table of Contents\n\n- [Why logixia?](#why-logixia)\n- [Feature comparison](#feature-comparison)\n- [Performance](#performance)\n- [Installation](#installation)\n- [Quick start](#quick-start)\n- [Core concepts](#core-concepts)\n - [Log levels](#log-levels)\n - [Structured logging](#structured-logging)\n - [Child loggers](#child-loggers)\n - [Adaptive log level](#adaptive-log-level)\n - [Per-namespace log levels](#per-namespace-log-levels)\n- [Transports](#transports)\n - [Console](#console)\n - [File with rotation](#file-with-rotation)\n - [Database](#database)\n - [Analytics](#analytics)\n - [Multiple transports simultaneously](#multiple-transports-simultaneously)\n - [Custom transport](#custom-transport)\n- [Cloud adapters](#cloud-adapters)\n - [AWS CloudWatch](#aws-cloudwatch)\n - [Google Cloud Logging](#google-cloud-logging)\n - [Azure Monitor](#azure-monitor)\n- [Request tracing](#request-tracing)\n - [Core trace utilities](#core-trace-utilities)\n - [Express / Fastify middleware](#express--fastify-middleware)\n - [NestJS trace middleware](#nestjs-trace-middleware)\n - [Kafka trace interceptor](#kafka-trace-interceptor)\n - [WebSocket trace interceptor](#websocket-trace-interceptor)\n- [NestJS integration](#nestjs-integration)\n - [@LogMethod decorator](#logmethod-decorator)\n - [LogixiaExceptionFilter](#logixiaexceptionfilter)\n- [Correlation ID propagation](#correlation-id-propagation)\n - [Express middleware](#correlation-express-middleware)\n - [Fastify hook](#correlation-fastify-hook)\n - [Outbound fetch / axios](#outbound-fetch--axios)\n - [Kafka / SQS helpers](#kafka--sqs-helpers)\n- [Browser support](#browser-support)\n- [Log redaction](#log-redaction)\n- [Timer API](#timer-api)\n- [Field management](#field-management)\n- [Transport level control](#transport-level-control)\n- [Transport filter predicate](#transport-filter-predicate)\n- [Log search](#log-search)\n- [OpenTelemetry](#opentelemetry)\n- [OTLP logs export](#otlp-logs-export-opentelemetry-native)\n- [Wide events / canonical log lines](#wide-events--canonical-log-lines)\n- [Dynamic runtime reconfiguration](#dynamic-runtime-reconfiguration)\n- [Adaptive sampling](#adaptive-sampling)\n- [Robust serialization](#robust-serialization)\n- [Graceful shutdown](#graceful-shutdown)\n- [Plugin / extension API](#plugin--extension-api)\n - [Writing a plugin](#writing-a-plugin)\n - [Registering plugins globally](#registering-plugins-globally)\n - [Per-logger plugins](#per-logger-plugins)\n - [Cancelling a log entry](#cancelling-a-log-entry)\n- [Metrics → Prometheus](#metrics--prometheus)\n - [Quick start (counters)](#quick-start-counters)\n - [Histograms](#histograms)\n - [Gauges](#gauges)\n - [Exposing the /metrics endpoint](#exposing-the-metrics-endpoint)\n - [Metric configuration reference](#metric-configuration-reference)\n- [Logger instance API](#logger-instance-api)\n- [CLI tool](#cli-tool)\n - [explore — Visual TUI log explorer](#explore--visual-tui-log-explorer)\n- [Configuration reference](#configuration-reference)\n- [Contributing](#contributing)\n- [License](#license)\n\n---\n\n## Why logixia?\n\n`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.\n\nlogixia takes a different approach: **everything ships built-in, and nothing blocks your event loop.**\n\n- **Async by design** — every log call is non-blocking, even to file and database transports\n- **Built-in database transports** — PostgreSQL, MySQL, MongoDB, SQLite with zero extra drivers\n- **Cloud adapters** — AWS CloudWatch (EMF), Google Cloud Logging, and Azure Monitor out of the box\n- **NestJS module** — plug in with `LogixiaLoggerModule.forRoot()`, inject anywhere in the DI tree; `@LogMethod()` for auto-logging method entry/exit\n- **File rotation** — `maxSize`, `maxFiles`, gzip archive, time-based rotation — no extra packages needed\n- **Log search** — query your in-memory log store without shipping to an external service\n- **Field redaction** — mask passwords, tokens, and PII before they touch any transport; supports dot-notation paths and regex patterns\n- **Request tracing** — `AsyncLocalStorage`-based trace propagation with no manual thread-locals; includes Kafka and WebSocket interceptors\n- **Correlation ID propagation** — auto-generate and forward `X-Correlation-ID` through `fetch`, axios, Kafka, and SQS across microservice boundaries\n- **Browser support** — tree-shakeable `logixia/browser` entry point with console and remote batch transports; no Node.js built-ins\n- **OpenTelemetry** — W3C `traceparent` and `tracestate` support, zero extra dependencies\n- **Multi-transport** — write to console, file, and database concurrently with one log call\n- **TypeScript-first** — typed log entries, typed metadata, custom-level IntelliSense throughout\n- **Adaptive log level** — auto-configures based on `NODE_ENV` and CI environment\n- **Custom transports** — ship to Slack, PagerDuty, S3, or anywhere else via a simple interface\n- **Plugin / extension API** — lifecycle hooks (`onInit`, `onLog`, `onError`, `onShutdown`); plugins can mutate or cancel log entries; register globally or per-logger\n- **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\n- **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\n\n---\n\n## Feature comparison\n\n| Feature | **logixia** | pino | winston | bunyan |\n| ------------------------------------- | :---------: | :---------: | :-----------------------: | :-----: |\n| TypeScript-first | yes | partial | partial | partial |\n| Async / non-blocking writes | yes | no | no | no |\n| NestJS module (built-in) | yes | no | no | no |\n| Database transports (built-in) | yes | no | no | no |\n| Cloud transports (CW, GCP, Azure) | yes | no | no | no |\n| File rotation (built-in) | yes | pino-roll | winston-daily-rotate-file | no |\n| Multi-transport concurrent | yes | no | yes | no |\n| Log search | yes | no | no | no |\n| Field + message redaction (built-in) | yes | pino-redact | no | no |\n| Request tracing (AsyncLocalStorage) | yes | no | no | no |\n| Kafka + WebSocket trace interceptors | yes | no | no | no |\n| Correlation ID propagation | yes | no | no | no |\n| Browser / Edge / Bun / Deno support | yes | partial | no | no |\n| OpenTelemetry / W3C headers | yes | no | no | no |\n| **OTLP logs export (OTel-native)** | **yes** | transport | no | no |\n| **Wide events / canonical log lines** | **yes** | no | no | no |\n| **Runtime log-level reconfig** | **yes** | external | no | no |\n| **Adaptive (anomaly) sampling** | **yes** | no | no | no |\n| Graceful shutdown / flush (no loss) | yes | partial | no | no |\n| Custom log levels | yes | yes | yes | yes |\n| Adaptive log level (NODE_ENV) | yes | no | no | no |\n| Plugin / extension API | yes | no | no | no |\n| Prometheus metrics extraction | yes | no | no | no |\n| Visual TUI log explorer | yes | no | no | no |\n| Actively maintained | yes | yes | yes | no |\n\n---\n\n## Performance\n\nlogixia 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 — no wasted pre-format), and per-call work (level check, namespace resolution, redaction decision) served off pre-built caches. The result: logixia **beats pino on 5 of 6 real-world scenarios**, beats winston and bunyan across the board, and keeps **p99 latency at 1–3µs** with no tail spikes.\n\nBenchmarked against **pino, winston, and bunyan** — all writing to `/dev/null` (pure serialization + framework overhead, no disk/terminal cost). Node 20, Apple M-series; numbers are ops/sec, higher is better. Reproduce with `npm run benchmark`.\n\n| Scenario | pino | **logixia** | winston | bunyan |\n| ------------------------------ | --------: | ------------: | --------: | ------: |\n| Simple string log | 3,220,000 | 2,769,000 | 1,577,000 | 707,000 |\n| **Structured log (5 fields)** | 1,319,000 | **1,536,000** | 699,000 | 536,000 |\n| **Error object logging** | 907,000 | **1,940,000** | 1,062,000 | 573,000 |\n| **Child / per-request logger** | 1,093,000 | **1,436,000** | 321,000 | 380,000 |\n| **Deep nested object** | 891,000 | **1,040,000** | 435,000 | 442,000 |\n| **High-cardinality (12 flds)** | 651,000 | **1,027,000** | 316,000 | 404,000 |\n\n**What this means:**\n\n- ✅ **logixia is faster than pino on 5 of 6 scenarios** — including **+114% on error logging**, **+58% on high-cardinality**, **+31% on child loggers**, and **+16% on structured logs** — the shapes that dominate real production traffic.\n- ✅ **logixia beats winston and bunyan in every scenario**, often by 2–3×, and avoids their tail-latency spikes (winston hit **3,038µs p99** on high-cardinality and **412µs** on deep objects; logixia stays **1–3µs p99** throughout).\n- ⚖️ **pino still wins the trivial simple-string case** (−14%) because it writes synchronously straight to `process.stdout` — fast in a microbenchmark, but it blocks the event loop under real I/O and is exactly the path behind pino's open [flush-on-exit log-loss bug](#graceful-shutdown). logixia stays non-blocking and guarantees delivery, and pulls ahead the moment you log anything structured.\n\n**Distinctive-feature throughput** (no cross-library equivalent — `npm run benchmark:features`):\n\n| Operation | ops/sec | p99 |\n| ---------------------------------------- | --------: | ----: |\n| Wide event (accumulate 6 fields + emit) | 742,000 | 3.7µs |\n| `safeStringify` (BigInt + circular) | 2,735,000 | 0.5µs |\n| `decycle` + `retrocycle` round-trip | 1,003,000 | 1.3µs |\n| Adaptive-sampling decision (hot path) | 1,950,000 | 0.9µs |\n| Namespace child logging (`db.*` → debug) | 1,966,000 | 0.8µs |\n\nSampling and namespace resolution add **negligible overhead** (~µs), so you can keep them on in production.\n\nTo reproduce: `npm run benchmark` (core) and `npm run benchmark:features` (distinctive APIs).\n\n---\n\n## Installation\n\n```bash\nnpm install logixia\npnpm add logixia\nyarn add logixia\nbun add logixia\n```\n\nFor database transports, install the relevant driver alongside logixia:\n\n```bash\nnpm install pg # PostgreSQL\nnpm install mysql2 # MySQL\nnpm install mongodb # MongoDB\nnpm install sqlite3 # SQLite\n```\n\n**Requirements:** TypeScript 5.0+, Node.js 18+\n\n---\n\n## Quick start\n\n```typescript\nimport { createLogger } from 'logixia';\n\nconst logger = createLogger({\n appName: 'api',\n environment: 'production',\n});\n\n// ✅ Structured data — machine-readable, searchable, alertable\nawait logger.info('Server started', { port: 3000 });\nawait logger.warn('High memory usage', { used: '87%', threshold: '80%' });\nawait logger.error('Request failed', { orderId: 'ord_123', retryable: true });\n\n// ✅ Pass an Error object directly — logixia serializes the full cause chain\nawait logger.error(new Error('Connection timeout'));\n\n// ❌ Avoid string interpolation — you lose structured fields\n// await logger.info(`Server started on port ${port}`);\n```\n\nNo `try/catch` needed — logixia swallows transport errors internally so a flaky DB or disk-full condition never crashes your app.\n\nWithout a `transports` key, logs go to stdout/stderr. Add a `transports` key to write to file, database, or anywhere else — all transports run concurrently.\n\nThere is also a pre-configured default instance you can import directly:\n\n```typescript\nimport { logger } from 'logixia';\n\nawait logger.info('Ready');\n```\n\n---\n\n## Core concepts\n\n### Log levels\n\nlogixia 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.\n\n```typescript\nawait logger.error('Something went wrong');\nawait logger.warn('Approaching rate limit', { remaining: 5 });\nawait logger.info('Order created', { orderId: 'ord_123' });\nawait logger.debug('Cache miss', { key: 'user:456' });\nawait logger.trace('Entering function', { fn: 'processPayment' });\nawait logger.verbose('Full request payload', { body: req.body });\n```\n\nThe `error` method also accepts an `Error` object directly — the full cause chain and standard Node.js fields (`code`, `statusCode`, `errno`, `syscall`) are serialized automatically:\n\n```typescript\nawait logger.error(new Error('Connection refused'));\n\n// With extra metadata alongside:\nawait logger.error(new Error('Payment declined'), { orderId: 'ord_123', retryable: true });\n\n// AggregateError is handled too:\nconst err = new AggregateError([new Error('A'), new Error('B')], 'Multiple failures');\nawait logger.error(err);\n```\n\nYou can also define **custom levels** for your domain:\n\n```typescript\nconst logger = createLogger({\n appName: 'payments',\n levelOptions: {\n level: 'payment', // show everything down to 'payment'\n levels: {\n error: 0,\n warn: 1,\n info: 2,\n debug: 3,\n // domain-specific levels — lower number = higher priority\n payment: 1, // same priority as warn\n audit: 2, // same priority as info\n kafka: 2,\n },\n colors: {\n error: 'red',\n warn: 'yellow',\n info: 'blue',\n debug: 'green',\n // IntelliSense now suggests 'payment' | 'audit' | 'kafka' as valid keys:\n payment: 'brightYellow',\n audit: 'magenta',\n // kafka omitted → auto-palette assigns a visible color (cyan in this case)\n },\n },\n});\n\n// Custom level methods are available immediately, fully typed\nawait logger.payment('Charge captured', { orderId: 'ord_123', amount: 99.99 });\nawait logger.audit('Refund approved', { orderId: 'ord_123', by: 'admin' });\nawait logger.kafka('Message published', { topic: 'order.created' });\n\n// logLevel() is the typed escape hatch — equivalent to the proxy methods above\nawait logger.logLevel('payment', 'Subscription renewed', { userId: 'usr_456' });\n```\n\n**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.\n\n**NestJS service IntelliSense** — `LogixiaLoggerService.create