![\"@bymax-one/nest-logger\"](\"https://img.shields.io/badge/%40bymax--one-nest--logger-000000?style=for-the-badge&logo=nestjs&logoColor=E0234E\"){kind=icon}
\n\n
\n Structured JSON logging for NestJS
\n Pino 10 · OpenTelemetry · PII Redaction · Multi-Destination · Multi-Tenant · Zero Runtime Dependencies\n
\n ![\"npm](\"https://img.shields.io/npm/v/@bymax-one/nest-logger?style=flat-square&colorA=000000&colorB=000000\")
![\"npm](\"https://img.shields.io/npm/dm/@bymax-one/nest-logger?style=flat-square&colorA=000000&colorB=000000\")
![\"CI](\"https://img.shields.io/github/actions/workflow/status/bymaxone/nest-logger/ci.yml?branch=main&style=flat-square&colorA=000000&label=CI\")
![\"coverage\"](\"https://img.shields.io/badge/coverage-100%25-brightgreen?style=flat-square&colorA=000000\"){kind=icon}
![\"mutation](\"https://img.shields.io/badge/mutation-100%25-brightgreen?style=flat-square&colorA=000000\"){kind=icon}
\n
![\"license\"](\"https://img.shields.io/github/license/bymaxone/nest-logger?style=flat-square&colorA=000000&colorB=000000\")
![\"TypeScript\"](\"https://img.shields.io/badge/TypeScript-strict-3178C6?style=flat-square&logo=typescript&logoColor=white\"){kind=icon}
![\"Node.js\"](\"https://img.shields.io/badge/Node.js-24%2B-339933?style=flat-square&logo=node.js&logoColor=white\"){kind=icon}
\n GitHub ·\n Issues ·\n Quick Start ·\n API Reference ·\n Example App\n
\n\n---\n\n## ✨ Overview\n\n`@bymax-one/nest-logger` replaces ad-hoc `console.log` and legacy Winston setups with a production-grade structured logging pipeline. Every log entry is a JSON object carrying a `logKey` (`MODULE_ACTION_RESULT` convention), `requestId`, `tenantId`, and — when OpenTelemetry is active — the correlated `traceId`/`spanId`.\n\n**Why Pino?** At ~750,000 logs/sec (vs Winston's ~110,000), Pino consumes 3× less CPU and half the RSS under load. The difference is measurable in production billing/payments backends where the logger is on the hot path for every request.\n\nThe library has **zero direct dependencies** — all packages arrive as peer dependencies, so you control exact versions and the supply chain surface stays minimal.\n\n### Why nest-logger?\n\n- **🎯 One module, the whole pipeline** — Logger service, HTTP interceptor, exception filter, context propagation, redaction, and destinations arrive in a single `forRoot()`. No gluing together `pino-http`, a redaction layer, and a transport by hand.\n- **🔌 Your sinks, your rules** — The library defines `ILogDestination`. You implement it for Loki, Postgres, a rolling file, or anything else. No vendor lock-in, no hidden transport dependencies.\n- **🔒 Redacted by default** — 32 sensitive field names are censored **down to 100 levels of nesting**, covering passwords, tokens, PCI DSS card data, MFA secrets, LGPD documents and credential-bearing HTTP headers. One recursive walk per entry, not a path list. Domain-specific names are yours to add via `redactPaths`.\n- **⚡ On the hot path, so it stays cheap** — Singleton providers, one composed Pino mixin, and a single-pass redactor. No `Scope.REQUEST`, no path matching.\n- **🔭 Correlated when you need it** — When an OpenTelemetry span is active, `traceId`/`spanId`/`traceFlags` land in every entry. When the peer is absent, the mixin steps aside at zero cost.\n\n```\npnpm add @bymax-one/nest-logger\n```\n\n---\n\n## 🔥 Features\n\n### 📝 Core Logging\n\n- ✅ **Structured JSON** — every entry has `level`, `time`, `service`, `logKey`, `msg`, and arbitrary metadata fields\n- ✅ **`MODULE_ACTION_RESULT` Log Keys** — a naming convention enforced by an exported regex for CI validation\n- ✅ **NestJS `LoggerService` Bridge** — drop-in replacement; all NestJS internal logs flow through Pino\n- ✅ **Pretty-Print in Dev** — opt-in `PrettyDevDestination` with a configurable `view` (single-line, hidden fields, message-only) for readable local output (requires optional `pino-pretty`)\n- ✅ **Field Size Guard** — a serialized field over the ceiling (default 64 KB) is replaced by a compact truncation envelope instead of flooding the sink\n\n### 🛡️ Security & Privacy\n\n- ✅ **PII Redaction by Default** — 32 field names censored wherever they appear, to a 100-level nesting ceiling past which nested objects are dropped, in a single snapshotting walk\n- ✅ **PCI DSS & MFA Coverage** — card data and MFA secrets redacted out of the box, with common HTTP auth headers\n- ✅ **LGPD-Aware Paths** — CPF, CNPJ, and RG redacted by default for Brazilian workloads\n- ✅ **Append-Only Redact List** — `DEFAULT_REDACT_PATHS` never shrinks without a major version; extend it via `redactPaths`\n- ✅ **Validated Trace IDs** — OTel identifiers pass `isValidTraceId` before injection, never raw user input\n\n### 🔍 Observability & Context\n\n- ✅ **OpenTelemetry Correlation** — optional `@opentelemetry/api` peer; injects `traceId`/`spanId`/`traceFlags` into every log via a Pino mixin when an active span is detected. Resolution is anchored at the library's own module path, so a Docker `WORKDIR`, a pnpm workspace or a monorepo launched from the repo root cannot silently switch correlation off\n- ✅ **Stable Resource Identity** — `service.name`/`.namespace`/`.version`/`.instance.id` and `deployment.environment.name`, all **Stable** in Semantic Conventions v1.44.0, resolved from one deterministic precedence shared with the OTel SDK\n- ✅ **Semconv Error Fields** — opt-in `exception.type`/`.message`/`.stacktrace` and low-cardinality `error.type`, additive beside the legacy `err.*`, with full `Error.cause` chains\n- ✅ **Machine-Readable Event Names** — `event.name` derived from `logKey` following OTel naming rules\n- ✅ **AsyncLocalStorage Context** — `requestId`, `tenantId`, `userId` flow automatically through the request lifecycle without prop drilling\n- ✅ **HTTP Access Log, before guards** — logs every request including the ones an interceptor cannot see (401/403/429 guard rejections, 404 unmatched routes), with URL normalization (UUIDs and numeric IDs replaced by `:id`) and the query string stripped\n- ✅ **Exception Filter** — captures NestJS `HttpException` and unexpected errors with structured output\n\n### 🔌 Destinations\n\n- ✅ **Pluggable Destinations** — implement `ILogDestination` to ship logs to Loki, Postgres, rolling files, or any sink\n- ✅ **Managed Lifecycle** — `onInit()` / `onShutdown()` hooks; a destination that fails `onInit()` is reported and excluded from shutdown, and boot is never aborted\n- ✅ **Crash-Proof Writes** — every `write()` is wrapped in a try/catch; a failure is reported on `stderr` and swallowed, never propagated to the app\n\n### 🧩 Developer Experience\n\n- ✅ **Zero Runtime Dependencies** — everything arrives as a peer dependency, so you control versions and supply-chain surface\n- ✅ **2 Subpath Exports** — `.` for the NestJS server API, `./shared` for zero-dependency types and constants\n- ✅ **Dynamic Module** — configure via `forRoot()` or `forRootAsync()`, sensible defaults included\n- ✅ **Strict TypeScript** — `strict: true`, no `any` in production code, JSDoc on every public export\n- ✅ **100% Coverage + Mutation Tested** — statements, branches, functions, and lines gated at 100%, with Stryker as the deeper gate\n\n---\n\n## 📦 Subpath Exports\n\nOne package, two entry points — import only what your app needs:\n\n| Subpath | Import | Purpose | Dependencies |\n| ---------- | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------: |\n| **Server** | `@bymax-one/nest-logger` | NestJS module, logger service, interceptor, filter, decorators, destinations | NestJS 11, pino, rxjs, reflect-metadata |\n| **Shared** | `@bymax-one/nest-logger/shared` | Types, constants, the log-key regex — `LogLevel`, `LogEntry`, `ServiceMetadata`, `ResolvedServiceMetadata`, `EmittedServiceResource`, `EmittedDeploymentResource` | None |\n\n```\nshared (zero deps)\n ↑\n server\n```\n\nThe `/shared` subpath is safe to import in isomorphic code, test helpers, CLI scripts, or shared packages that must not pull in NestJS.\n\n---\n\n> [!TIP]\n> Prefer to learn from a working app? See the [nest-logger-example](https://github.com/bymaxone/nest-logger-example) — a full NestJS project wired with this library.\n\n## 🚀 Quick Start\n\n### 1. Install\n\n```bash\n# Using pnpm (recommended)\npnpm add @bymax-one/nest-logger\n\n# Using npm\nnpm install @bymax-one/nest-logger\n\n# Using yarn\nyarn add @bymax-one/nest-logger\n```\n\n> [!IMPORTANT]\n> You must also install the required **peer dependencies**. The library ships `\"dependencies\": {}`, so nothing arrives implicitly:\n\n```bash\n# Server subpath (required)\npnpm add @nestjs/common @nestjs/core pino reflect-metadata rxjs\n\n# Optional — pretty local output via PrettyDevDestination\npnpm add -D pino-pretty\n\n# Optional — OpenTelemetry trace correlation\npnpm add @opentelemetry/api @opentelemetry/sdk-node\n\n```\n\n> ⚠️ **Under pnpm, `-D` may not make it absent in production — measure, do not assume.** Two\n> consumers who had assumed otherwise measured the peer **present** in their real production images,\n> by two different build routes: `pnpm prune --prod` keeps the store entry, and a clean\n> `pnpm install --prod --frozen-lockfile` in a fresh stage installs it too. In both, the peer was\n> recorded in the lockfile. `PrettyDevDestination` imports it lazily, relative to the library's own\n> directory under `.pnpm/`, where it is a sibling — so it resolves.\n>\n> That is two measurements, not a law of pnpm: whether a production install always carries an optional\n> peer, however the lockfile was produced, has not been tested here. The advice below does not depend\n> on it.\n>\n> The clean-install case is worth stating separately, because \"we do a fresh prod install, not a\n> prune\" reads like an exemption and is not one. It is what one of those consumers concluded before\n> measuring their own image.\n>\n> **On other package managers this is different**, and the difference cuts the other way: under npm's\n> or yarn's flat `node_modules`, a pruned devDependency really is gone. If you install with those,\n> do not read this warning as universal.\n>\n> Either way, the rule that survives both layouts: **\"it is a devDependency, therefore this path\n> cannot run in production\" is not a safe premise, because the premise is about someone else's\n> install command.** A `PrettyDevDestination` left registered in production will not crash and will\n> not warn — it renders ANSI colour into a log pipeline that has silently failed to parse every line\n> since the deploy, which is indistinguishable from a service that went quiet. Gate it on an explicit\n> configuration value you can see, not on the packaging.\n\n> [!NOTE]\n> `@opentelemetry/api` is resolved lazily when the Pino instance is built. When it is absent the trace mixin silently steps aside — the logger never fails to start, and never warns, over an optional peer.\n\n> [!NOTE]\n> The published declarations depend on no HTTP framework's types. The HTTP interceptor, the exception filter and the request-id middleware are typed by structural contracts (`LoggableRequest`, `LoggableResponse`, `NextHandler`) that an Express request and response satisfy as-is, so nothing extra is needed even when you compile with `skipLibCheck: false`. The emitted `.d.ts` imports only `@nestjs/common`, `pino` and `rxjs`.\n\n### 2. Register the module\n\n```typescript\n// app.module.ts\nimport { Module } from '@nestjs/common'\nimport { BymaxLoggerModule } from '@bymax-one/nest-logger'\n\n@Module({\n imports: [\n BymaxLoggerModule.forRoot({\n service: { name: 'my-app', version: '1.0.0' },\n level: 'info',\n http: { isEnabled: true }\n })\n ]\n})\nexport class AppModule {}\n```\n\nStdout is wired automatically — `DefaultStdoutDestination` is always active, so this is all you need to be logging structured JSON.\n\n### 3. Async configuration with `ConfigService`\n\n```typescript\n// app.module.ts\nimport { Module } from '@nestjs/common'\nimport { ConfigModule, ConfigService } from '@nestjs/config'\nimport { BymaxLoggerModule } from '@bymax-one/nest-logger'\n\n@Module({\n imports: [\n ConfigModule.forRoot({ isGlobal: true }),\n BymaxLoggerModule.forRootAsync({\n imports: [ConfigModule],\n inject: [ConfigService],\n useFactory: (cfg: ConfigService) => ({\n service: {\n name: cfg.getOrThrow