@bymax-one/nest-logger 1.2.0 → 1.2.2

package/CHANGELOG.md

@@ -11,6 +11,163 @@ heading here.
 
 ## [Unreleased]
 
+## [1.2.2] - 2026-08-13
+
+### Added
+
+- **`EmittedServiceResource` and `EmittedDeploymentResource` are exported.** `LogEntry['service']`
+  and `LogEntry['deployment']` have been typed by these interfaces since 1.2.1, but neither was
+  reexported from `@bymax-one/nest-logger/shared`, so a consumer could hold `entry.service` and had
+  no way to write its type — a function taking one had to inline the shape or reach for
+  `LogEntry['service']`. Reported by a consumer adopting 1.2.1.
+- **Every shared type is now reexported from the server subpath, not a subset.** `LogEntry` was
+  already there while the types of its own properties were not, which is the same defect one level
+  up. `ResolvedServiceMetadata` and `ReservedLogKey` join them for the same reason.
+- **`LogEntry` declares `'event.name'`.** The field has been emitted since 1.2.1 and documented as
+  part of the entry, but only the index signature covered it — so a consumer reading
+  `entry['event.name']` got `unknown` and needed a cast. A documented field that cannot be read
+  without a cast is not really published. The declaration describes the default key; a renamed
+  `eventNameField` still arrives through the index signature.
+
+Type-only change: `dist/*.mjs` and `dist/*.cjs` are byte-identical to 1.2.1, since `export type`
+erases at compile time. Only the `.d.ts` files differ.
+
+## [1.2.1] - 2026-08-13
+
+### Security
+
+- **A log message can no longer forge log lines in re-rendered output** (CodeQL
+  `js/log-injection`, alert #61). Every message argument handed to Pino can carry caller- or
+  user-provided text — a thrown value recorded off an HTTP request, a variadic NestJS line, a
+  structured message — and while the NDJSON transport neutralizes an embedded LF or CR through
+  JSON escaping (measured; it does NOT cover U+2028/U+2029 — see the entry below),
+  `pino-pretty` — shipped here as `PrettyDevDestination` — and
+  any destination that re-renders the parsed message print real newlines, where a break forges what
+  looks like a separate entry (also measured: the forged line is indistinguishable from a genuine
+  one). Line and paragraph separators (`\r`, `\n`, U+2028, U+2029) are now replaced with the
+  literal `\n` sequence on **every** message sink: `error()` for both the `Error` and the string
+  path, the structured `info`/`warn` calls, and the NestJS variadic bridge. Structured fields are
+  untouched — `err.message` keeps the verbatim text — so no information is lost, only the
+  human-readable `msg` is pinned to one line.
+- **Terminal control characters can no longer drive the renderer either.** Pinning the line
+  terminators is not enough on a terminal: `ESC E` is ANSI NEL (next line), `ESC [` opens a control
+  sequence, and vertical tab, form feed and C1 NEL (U+0085) all move the cursor. Measured on the
+  built bundle — the raw `ESC` byte reached the terminal through `pino-pretty` and forged a line
+  exactly like a newline did. Every C0 control except TAB, plus DEL and the C1 range, is now
+  rendered as its readable `\uXXXX` escape — one form for every character, four hex digits.
+  Escaping the ESC byte is what disarms every sequence built on it, rather than chasing sequences
+  one by one.
+- **This also protects the raw NDJSON line, not only re-rendering destinations.** JSON escaping
+  covers C0 and nothing more: `JSON.stringify` and Pino's serializer emit DEL, the C1 range
+  (U+0085 NEL among them), U+2028 and U+2029 **verbatim** — measured on the emitted bytes. A human
+  reading raw NDJSON in a terminal was therefore exposed to the same cursor movement as a
+  `pino-pretty` reader. Both paths are now covered. The boundary is unchanged: structured values
+  are data and are not rewritten, so a control character placed in a metadata field still reaches
+  the terminal — only `msg` and the stack carry the guarantee.
+- **The scrubbed stack is escaped too.** `pino-pretty` prints `err.stack` RAW rather than as a JSON
+  string, and a stack's first line repeats the error message — so escaping only `msg` left the
+  identical attack working through `err.stack` and `exception.stacktrace`. Control characters in
+  the stack are now escaped; its newlines are preserved, because a stack is legitimately
+  multi-line.
+
+P1 of the observability audit ([`docs/observability_audit.md`](./docs/observability_audit.md)):
+stable OpenTelemetry resource identity, robust trace correlation, semconv-aligned error fields and
+machine-readable event names. Every convention adopted here was verified **Stable** against
+Semantic Conventions **v1.44.0** on 2026-08-13; nothing Development or Experimental is emitted by
+default, and no runtime dependency was added.
+
+Design rationale is in [ADR 0001](./docs/adr/0001-resource-identity-and-otel-correlation.md); the
+complete field inventory is in
+[`docs/semantic-convention-mapping.md`](./docs/semantic-convention-mapping.md).
+
+### Fixed
+
+- **The HTTP terminal entry is emitted in the live async context when one exists.** The `'close'`
+  listener used `AsyncResource.bind` alone, which captures the context at REGISTRATION time — so
+  when instrumentation opened a span downstream of the middleware, the terminal entry was
+  attributed to the wrong span, silently, because a plausible trace id was still present. Measured
+  (and confirmed independently against a real OTel ContextManager): the live read covers the
+  normal path, the bound context covers the aborted path, and neither alone covers both. The
+  listener now reads live-first with the bound context as fallback; the ALS store doubles as the
+  liveness probe.
+- **A thrown non-object no longer spreads into the `err` object.** The serializer's own-property
+  copy ran on any value, and `Object.entries` on a thrown STRING spreads its characters as indexed
+  keys — a record carried `err: {"0":"t","1":"h",…}` beside the `UnknownError` envelope; a thrown
+  array spread its elements the same way. Own properties are now copied only off a plain
+  non-array object.
+- **Trace correlation no longer switches off because of the working directory.** `@opentelemetry/api`
+  was resolved from `process.cwd()` alone, so a Docker `WORKDIR` that is not the app root, a
+  pnpm/Yarn workspace with hoisted `node_modules`, a monorepo launched from the repository root or a
+  serverless bundle silently disabled ALL trace correlation. Measured with `cwd = /`: the old anchor
+  fails to resolve, the new one succeeds. Resolution is now anchored at the library's own module
+  path, falling back to the working directory.
+- **`err.type` is no longer `"Object"` for a typed exception.** `pino.stdSerializers.err` derives
+  the type from the value's CONSTRUCTOR, so an error already normalized into a plain object — which
+  is exactly what `HttpExceptionFilter` produces — was reported as `Object`. The fix is
+  architectural: nothing pre-serializes any more and the `err` serializer reads the real type. A
+  second layer of the same defect is fixed too — `sanitizeError` only accepted `instanceof Error`,
+  so the same plain object came out as `UnknownError`.
+- **`Error.cause` chains reach the log.** `sanitizeError` computed the chain and the service
+  discarded it, so modern JavaScript error chaining was invisible. `AggregateError` members are
+  carried as `err.errors`. Both are depth- and width-bounded, circular-safe, and redacted.
+
+### Added
+
+- **Stable resource identity.** `service.namespace`, `service.instanceId` and `service.environment`
+  options, emitted as `service.namespace`, `service.instance.id` and `deployment.environment.name`.
+  Resolution precedence is deterministic: explicit options → `OTEL_SERVICE_NAME` →
+  `OTEL_RESOURCE_ATTRIBUTES` → `NODE_ENV`. The order of the two OTel variables is required by the
+  specification, so the logger and the SDK reading the same environment agree by construction.
+  `service.instance.id` is **never generated** — a UUID minted here would be the logger's rather
+  than the OTel Resource's, and would change on every restart while looking authoritative.
+- **`resourceFormat: 'nested' | 'flat'`** (default `'nested'`). `'flat'` emits the dotted attribute
+  names verbatim, which a collector maps onto resource attributes directly.
+- **`errorFormat: 'pino' | 'semconv' | 'both'`** (default `'pino'`). Adds the Stable
+  `exception.type` / `exception.message` / `exception.stacktrace` and a low-cardinality
+  `error.type`. `'both'` is the migration path; `'semconv'` replaces the legacy `err` object and is
+  an explicit choice, never a default.
+- **`eventNameField`** (default `'event.name'`). Derives an OTel-conforming event name from
+  `logKey` — `PAYMENT_FAILED` → `payment.failed` — following the naming rules. `logKey` is never
+  renamed or removed. `false` disables it.
+- **`LOGGER_BOOTSTRAP_WARNING` for an unavailable OTel API.** When trace injection is enabled and
+  `@opentelemetry/api` cannot be resolved, one warning naming `OTEL_API_UNAVAILABLE` is emitted at
+  boot. A missing `traceId` used to be indistinguishable from "no active span".
+- **`ResolvedServiceMetadata`** exported from `@bymax-one/nest-logger/shared` — the identity after
+  precedence, and the contract a future `@bymax-one/nest-observability` consumes.
+
+### Changed
+
+- An error's own enumerable properties (`code`, `statusCode`, domain fields) are still carried onto
+  the serialized `err`, as Pino's standard serializer did — with the fields the serializer derives
+  itself excluded, so a plain error-like object no longer emits `name` beside the `type` derived
+  from it.
+- `deployment.environment.name` is emitted from `NODE_ENV` when nothing else supplies it, so most
+  applications gain the attribute without configuration. The **deprecated** `deployment.environment`
+  spelling is never emitted.
+
+### Performance
+
+Measured on the same machine as the 1.2.0 figures, shipped configuration:
+
+| Path                                        |           1.2.0 |             P1 | Delta |
+| ------------------------------------------- | --------------: | -------------: | ----: |
+| Shipped config throughput                   | ~278,000 logs/s | 263,768 logs/s |   −5% |
+| Retention vs. bare service (budget ≥ 0.20×) |          0.349× |         0.323× |   −7% |
+
+The cost is almost entirely `event.name` derivation: 949,560 vs 1,089,561 ops/sec on the info path
+(~13% there, ~7% of the full path). Resource identity costs ~2%, because it is resolved once and
+precomputed into Pino's `base`. `errorFormat: 'semconv'` is **faster** than the legacy shape
+(330,289 vs 245,463 ops/sec) since it emits flat strings instead of walking a cause chain. Set
+`eventNameField: false` to pay none of it.
+
+### Not adopted
+
+- **`@opentelemetry/api-logs`** — still `0.221.0`. A 0.x package will not become a dependency of a
+  library that ships `"dependencies": {}`.
+- **`event.name` as an OTLP attribute** — the attribute is Deprecated; the value belongs in the
+  LogRecord `EventName` field, and the emitted key is the JSON carrier for that mapping.
+- **`deployment.id` / `.name` / `.status`** — Development stability.
+
 ## [1.2.0] - 2026-08-13
 
 Remediation of the P0 findings from the observability audit
@@ -657,7 +814,9 @@ published `dist/` is identical — no runtime behaviour changes for consumers.
 - Professional CI suite: `ci.yml`, `bench.yml`, `codeql.yml`, `scorecard.yml`,
   `release.yml`, Dependabot, and issue templates
 
-[Unreleased]: https://github.com/bymaxone/nest-logger/compare/v1.2.0...HEAD
+[Unreleased]: https://github.com/bymaxone/nest-logger/compare/v1.2.2...HEAD
+[1.2.2]: https://github.com/bymaxone/nest-logger/compare/v1.2.1...v1.2.2
+[1.2.1]: https://github.com/bymaxone/nest-logger/compare/v1.2.0...v1.2.1
 [1.2.0]: https://github.com/bymaxone/nest-logger/compare/v1.1.0...v1.2.0
 [1.1.0]: https://github.com/bymaxone/nest-logger/compare/v1.0.8...v1.1.0
 [1.0.8]: https://github.com/bymaxone/nest-logger/compare/v1.0.7...v1.0.8

package/README.md

@@ -73,7 +73,10 @@ pnpm add @bymax-one/nest-logger
 
 ### 🔍 Observability & Context
 
-- ✅ **OpenTelemetry Correlation** — optional `@opentelemetry/api` peer; injects `traceId`/`spanId`/`traceFlags` into every log via a Pino mixin when an active span is detected
+- ✅ **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
+- ✅ **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
+- ✅ **Semconv Error Fields** — opt-in `exception.type`/`.message`/`.stacktrace` and low-cardinality `error.type`, additive beside the legacy `err.*`, with full `Error.cause` chains
+- ✅ **Machine-Readable Event Names** — `event.name` derived from `logKey` following OTel naming rules
 - ✅ **AsyncLocalStorage Context** — `requestId`, `tenantId`, `userId` flow automatically through the request lifecycle without prop drilling
 - ✅ **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
 - ✅ **Exception Filter** — captures NestJS `HttpException` and unexpected errors with structured output
@@ -98,10 +101,10 @@ pnpm add @bymax-one/nest-logger
 
 One package, two entry points — import only what your app needs:
 
-| Subpath    | Import                          | Purpose                                                                         |              Dependencies               |
-| ---------- | ------------------------------- | ------------------------------------------------------------------------------- | :-------------------------------------: |
-| **Server** | `@bymax-one/nest-logger`        | NestJS module, logger service, interceptor, filter, decorators, destinations    | NestJS 11, pino, rxjs, reflect-metadata |
-| **Shared** | `@bymax-one/nest-logger/shared` | Types, constants, the log-key regex — `LogLevel`, `LogEntry`, `ServiceMetadata` |                  None                   |
+| Subpath    | Import                          | Purpose                                                                                                                                                           |              Dependencies               |
+| ---------- | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------: |
+| **Server** | `@bymax-one/nest-logger`        | NestJS module, logger service, interceptor, filter, decorators, destinations                                                                                      | NestJS 11, pino, rxjs, reflect-metadata |
+| **Shared** | `@bymax-one/nest-logger/shared` | Types, constants, the log-key regex — `LogLevel`, `LogEntry`, `ServiceMetadata`, `ResolvedServiceMetadata`, `EmittedServiceResource`, `EmittedDeploymentResource` |                  None                   |
 
 ```
 shared (zero deps)
@@ -361,6 +364,153 @@ void bootstrap()
 
 Once active, every log entry automatically carries `traceId`, `spanId`, and `traceFlags`. Click the `traceId` in Grafana to jump directly to the correlated span in Tempo or Honeycomb.
 
+**Without OpenTelemetry installed, everything above simply does not happen** — no error, no warning
+on every log, no crash. The peer is optional and the logger is fully usable on its own. The one
+case that _is_ reported is a misconfiguration: if trace injection is enabled and
+`@opentelemetry/api` cannot be resolved, a single `LOGGER_BOOTSTRAP_WARNING` naming
+`OTEL_API_UNAVAILABLE` is emitted at startup. Absence of `traceId` would otherwise be
+indistinguishable from "no active span".
+
+The logger **observes** the trace context; it never creates spans, installs a context manager, or
+parses `traceparent` by hand. When the API is present but no span is active, no identifiers are
+emitted — none are invented.
+
+> [!NOTE]
+> Resolution of the optional peer is anchored at the **library's own module path**, falling back to
+> `process.cwd()`. Anchoring only at the working directory — as versions before this did — silently
+> disabled correlation whenever the process was launched from somewhere other than the application
+> root: a Docker `WORKDIR`, a pnpm/Yarn workspace with hoisted `node_modules`, a monorepo started at
+> the repository root, a serverless bundle.
+
+### 6b. Resource identity
+
+Every entry carries the service identity, using attributes that are **Stable** in Semantic
+Conventions v1.44.0:
+
+```typescript
+BymaxLoggerModule.forRoot({
+  service: {
+    name: 'checkout-api', // service.name
+    version: '2.14.3', // service.version
+    namespace: 'payments', // service.namespace
+    instanceId: process.env.POD_UID, // service.instance.id
+    environment: 'production' // deployment.environment.name
+  }
+})
+```
+
+```json
+{
+  "level": "info",
+  "time": "2026-08-13T10:00:00.000Z",
+  "service": {
+    "name": "checkout-api",
+    "version": "2.14.3",
+    "namespace": "payments",
+    "instance": { "id": "pod-7f3a" }
+  },
+  "deployment": { "environment": { "name": "production" } },
+  "logKey": "PAYMENT_FAILED",
+  "event.name": "payment.failed",
+  "msg": "Payment failed"
+}
+```
+
+Set `resourceFormat: 'flat'` to emit the dotted attribute names verbatim
+(`"service.instance.id": "pod-7f3a"`), which is what a collector mapping log fields onto resource
+attributes reads directly.
+
+#### Precedence
+
+Resolved once at startup, in this order:
+
+1. **explicit `service` options**
+2. **`OTEL_SERVICE_NAME`** (name only)
+3. **`OTEL_RESOURCE_ATTRIBUTES`** (`service.namespace=payments,service.version=2.14.3,…`)
+4. **`NODE_ENV`** (environment only)
+
+Explicit configuration wins because it is the most specific statement you can make. The order of
+the two OpenTelemetry variables is required by the specification, not chosen: _"If `service.name` is
+also provided in `OTEL_RESOURCE_ATTRIBUTES`, then `OTEL_SERVICE_NAME` takes precedence."_
+
+Reading the same variables the SDK reads is what makes **logs and traces agree** without the logger
+depending on the SDK. Configure the environment once and both signals describe the same service.
+
+> [!IMPORTANT]
+> **`service.instance.id` is never generated.** The specification requires the triplet
+> (`service.namespace`, `service.name`, `service.instance.id`) to be globally unique and recommends
+> a random UUID — but a UUID minted by the logger would be the _logger's_, not the OpenTelemetry
+> Resource's, so logs and traces would claim different instances of the same process. It would also
+> change on every restart while looking authoritative. Supply it from the platform (Kubernetes pod
+> UID, ECS task ARN, VM instance id) or through `OTEL_RESOURCE_ATTRIBUTES`. Omitted is honest;
+> plausible-but-wrong is not.
+>
+> There is **no `OTEL_SERVICE_VERSION`** variable in the specification. Version comes from
+> configuration or from `OTEL_RESOURCE_ATTRIBUTES`.
+
+The deprecated `deployment.environment` spelling is **never** emitted, in any mode.
+
+### 6c. Event names
+
+Structured entries carry a machine-readable event name derived from `logKey`, following OTel naming
+rules — lowercase, dot-namespaced:
+
+| `logKey`                     | `event.name`                 |
+| ---------------------------- | ---------------------------- |
+| `PAYMENT_FAILED`             | `payment.failed`             |
+| `USER_AUTHENTICATION_FAILED` | `user.authentication.failed` |
+
+`logKey` is **never renamed or removed** — this is additive. Calls through the NestJS variadic
+bridge (`logger.log`, `logger.warn`, …) carry no log key and correctly get no event name: an
+ordinary diagnostic line is not an Event.
+
+Keep event names **low cardinality**. `payment.failed` is an event; `payment.failed.918231781` is an
+identifier wearing an event's clothes and will multiply your series count. Identifiers belong in
+their own fields.
+
+> [!NOTE]
+> The value is meant to be mapped onto the **`EventName`** field of the OpenTelemetry LogRecord,
+> which is Stable in the Logs Data Model. The same-named `event.name` **attribute** is _Deprecated_
+> precisely because the value belongs in that top-level field instead. A JSON log line has no way to
+> express that distinction — every key is just a key — so the carrier key is configurable via
+> `eventNameField`, and your collector decides where it lands. What it must not do is carry it into
+> an OTLP _attributes_ map under the deprecated name.
+
+Set `eventNameField: false` to emit nothing.
+
+### 6d. Error fields
+
+`errorFormat` controls the shape:
+
+```json
+// errorFormat: 'pino'  (default — unchanged from 1.2.0)
+{ "err": { "type": "PaymentDeclined", "message": "card declined", "stack": "…",
+           "cause": { "name": "Error", "message": "gateway timeout" } } }
+
+// errorFormat: 'both'  (recommended while migrating)
+{ "err": { "type": "PaymentDeclined", … },
+  "exception.type": "PaymentDeclined",
+  "exception.message": "card declined",
+  "exception.stacktrace": "…",
+  "error.type": "PaymentDeclined" }
+
+// errorFormat: 'semconv'  (explicit migration — err is removed)
+{ "exception.type": "PaymentDeclined", "exception.message": "card declined",
+  "exception.stacktrace": "…", "error.type": "PaymentDeclined" }
+```
+
+All four attributes are **Stable**. `error.type` carries the **class name** and is low cardinality
+by construction — never a message, never an identifier — because the spec requires it to be
+aggregatable.
+
+**`Error.cause` chains are preserved**, depth- and width-bounded, circular-safe, and redacted like
+any other field. `AggregateError` members reach the entry as `err.errors`. There is no
+OpenTelemetry attribute for a cause chain, so these stay namespaced under `err` rather than
+inventing an `exception.cause` the spec does not define.
+
+An error's own enumerable properties (`code`, `statusCode`, domain fields) are carried through, as
+Pino's standard serializer did.
+
 ### 7. Context propagation with `LogContextService`
 
 ```typescript
@@ -396,18 +546,24 @@ Full options reference for `BymaxLoggerModule.forRoot(options)`:
 
 ### Top-level options
 
-| Option                       | Type                 | Default         | Description                                                                                                              |
-| ---------------------------- | -------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------ |
-| `service.name`               | `string`             | **Required**    | Service name emitted in every log entry                                                                                  |
-| `service.version`            | `string`             | **Required**    | Release version/SHA emitted in every log entry                                                                           |
-| `level`                      | `LogLevel`           | `'info'`        | Minimum log level. One of `fatal \| error \| warn \| info \| debug \| trace`                                             |
-| `isPretty`                   | `boolean`            | `!isProduction` | ⚠️ Reserved — not auto-wired. For pretty output add `new PrettyDevDestination()` to `destinations` (needs `pino-pretty`) |
-| `redactPaths`                | `string[]`           | `[]`            | Additional `fast-redact` paths, applied on top of the default coverage                                                   |
-| `redactStrategy`             | `'names' \| 'paths'` | `'names'`       | Engine behind the DEFAULT set. `'paths'` restores the pre-1.2 `fast-redact` expansion (four-level ceiling, ~100× slower) |
-| `shouldDisableDefaultRedact` | `boolean`            | `false`         | Skip the default PII coverage entirely. ⚠️ Emits `LOGGER_BOOTSTRAP_WARNING` at startup — document why                    |
-| `redactCensor`               | `string`             | `'[REDACTED]'`  | Replacement value written in place of every redacted field                                                               |
-| `maxEntrySizeBytes`          | `number`             | `65536`         | UTF-8 byte ceiling per serialized field (`err` + any custom serializer); over it the value becomes a truncation envelope |
-| `destinations`               | `ILogDestination[]`  | `[]`            | Additional sinks (Loki, Postgres, rolling file, …) alongside default stdout                                              |
+| Option                       | Type                            | Default         | Description                                                                                                                                |
+| ---------------------------- | ------------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| `service.name`               | `string`                        | **Required**    | Service name emitted in every log entry                                                                                                    |
+| `service.version`            | `string`                        | **Required**    | Release version/SHA emitted in every log entry                                                                                             |
+| `service.namespace`          | `string`                        | —               | OTel `service.namespace` (**Stable**) — the group the service belongs to                                                                   |
+| `service.instanceId`         | `string`                        | —               | OTel `service.instance.id` (**Stable**). **Never generated** — supply it from the platform. See [Resource identity](#6b-resource-identity) |
+| `service.environment`        | `string`                        | `NODE_ENV`      | OTel `deployment.environment.name` (**Stable**). The deprecated `deployment.environment` is never emitted                                  |
+| `resourceFormat`             | `'nested' \| 'flat'`            | `'nested'`      | Shape of the identity fields. `'flat'` emits the dotted attribute names verbatim                                                           |
+| `eventNameField`             | `string \| false`               | `'event.name'`  | Field carrying the derived event name (`PAYMENT_FAILED` → `payment.failed`). `false` disables it                                           |
+| `errorFormat`                | `'pino' \| 'semconv' \| 'both'` | `'pino'`        | `'both'` adds `exception.*` and `error.type` beside `err.*`; `'semconv'` replaces them                                                     |
+| `level`                      | `LogLevel`                      | `'info'`        | Minimum log level. One of `fatal \| error \| warn \| info \| debug \| trace`                                                               |
+| `isPretty`                   | `boolean`                       | `!isProduction` | ⚠️ Reserved — not auto-wired. For pretty output add `new PrettyDevDestination()` to `destinations` (needs `pino-pretty`)                   |
+| `redactPaths`                | `string[]`                      | `[]`            | Additional `fast-redact` paths, applied on top of the default coverage                                                                     |
+| `redactStrategy`             | `'names' \| 'paths'`            | `'names'`       | Engine behind the DEFAULT set. `'paths'` restores the pre-1.2 `fast-redact` expansion (four-level ceiling, ~100× slower)                   |
+| `shouldDisableDefaultRedact` | `boolean`                       | `false`         | Skip the default PII coverage entirely. ⚠️ Emits `LOGGER_BOOTSTRAP_WARNING` at startup — document why                                      |
+| `redactCensor`               | `string`                        | `'[REDACTED]'`  | Replacement value written in place of every redacted field                                                                                 |
+| `maxEntrySizeBytes`          | `number`                        | `65536`         | UTF-8 byte ceiling per serialized field (`err` + any custom serializer); over it the value becomes a truncation envelope                   |
+| `destinations`               | `ILogDestination[]`             | `[]`            | Additional sinks (Loki, Postgres, rolling file, …) alongside default stdout                                                                |
 
 ### `http` options
 
@@ -724,6 +880,8 @@ Before `1.2.0` the same names were expanded into 140 `fast-redact` paths at wild
 
 **Not covered, by design:** a secret interpolated into the message STRING (`logger.info(key, \`token=${t}\`)`) — redaction works on structured fields, and no field-based mechanism can scrub a substring. Keep secrets out of `msg`.
 
+**One entry, one line.** What the message string _cannot_ do is forge an entry. Every message argument passes through a line-separator normalization before it reaches Pino, so `\r`, `\n`, U+2028, U+2029 and C1 NEL (U+0085) become the literal two-character sequence `\n` — and every other control character that can drive a terminal (ESC, vertical tab, form feed, backspace, the rest of C0 except TAB, DEL and the C1 range) becomes its readable `\uXXXX` escape. This protects **two** sinks, not one. `pino-pretty` (shipped here as `PrettyDevDestination`) and any destination that re-renders the parsed message write those bytes straight to the terminal, where a raw newline **or** an `ESC E` produces something indistinguishable from a separate log entry. And the raw NDJSON line is exposed too when a human reads it in a terminal: JSON escaping covers only C0, so `JSON.stringify` and Pino's serializer emit DEL, the C1 range (U+0085 NEL included), U+2028 and U+2029 **verbatim** — measured on real bytes. Escaping at the sink neutralizes both paths. The scrubbed stack gets the same escaping (its newlines are kept, since a stack is multi-line by design), because `pino-pretty` prints it raw and its first line repeats the error message. Structured fields are untouched: `err.message` keeps the original text verbatim. That is the boundary — a control character placed in a **metadata value** still reaches a terminal, because escaping data would mean rewriting what you asked to be logged. Only `msg` and the stack carry this guarantee.
+
 ### Extending the defaults
 
 ```typescript
@@ -935,7 +1093,28 @@ PINO_LEVEL_NAMES[30] // 'info' — numeric code → label
 ```typescript
 type LogLevel = 'fatal' | 'error' | 'warn' | 'info' | 'debug' | 'trace'
 
-type ServiceMetadata = { name: string; version: string }
+// What you CONFIGURE.
+type ServiceMetadata = {
+  readonly name: string
+  readonly version: string
+  readonly namespace?: string
+  readonly instanceId?: string
+  readonly environment?: string
+}
+
+// What is EMITTED. Deliberately a different type: `instanceId` nests as
+// `service.instance.id`, and the environment is not under `service` at all.
+// Reusing the configuration type here would advertise `entry.service.instanceId`,
+// which no entry carries.
+type EmittedServiceResource = {
+  readonly name: string
+  readonly version: string
+  readonly namespace?: string
+  readonly instance?: { readonly id: string }
+  readonly [key: string]: unknown
+}
+
+type EmittedDeploymentResource = { readonly environment: { readonly name: string } }
 
 type LogEntry = {
   /** Pino string label — `'info'`, not `30`. Convert with `PINO_LEVEL_NUMBERS`. */
@@ -944,7 +1123,12 @@ type LogEntry = {
   time: string
   msg: string
   logKey?: string
-  service?: ServiceMetadata
+  /** Present under `resourceFormat: 'nested'` (the default). */
+  service?: EmittedServiceResource
+  /** Present when an environment resolved — `deployment.environment.name`. */
+  deployment?: EmittedDeploymentResource
+  /** Derived from `logKey` unless `eventNameField: false`. */
+  'event.name'?: string
   context?: string
   requestId?: string
   tenantId?: string
@@ -955,6 +1139,41 @@ type LogEntry = {
 }
 ```
 
+Under `resourceFormat: 'flat'` there is no `service` object at all — the values arrive as dotted
+top-level keys (`"service.instance.id"`), which the index signature already admits.
+
+The emitted types are exported, so a helper that receives one can be typed without inlining its
+shape:
+
+```typescript
+import type {
+  EmittedDeploymentResource,
+  EmittedServiceResource,
+  LogEntry
+} from '@bymax-one/nest-logger/shared'
+
+/** Build the identity triplet a backend joins on, from a parsed entry. */
+function identityOf(entry: LogEntry): string {
+  const service: EmittedServiceResource | undefined = entry.service
+  const deployment: EmittedDeploymentResource | undefined = entry.deployment
+  if (service === undefined) {
+    return 'unknown'
+  }
+  // `service.namespace` is part of the identity, not decoration: OTel allows two
+  // services to share a name when their namespaces differ, so a key built without
+  // it collapses them into one.
+  const namespace = service.namespace ?? 'no-namespace'
+  const instance = service.instance?.id ?? 'no-instance'
+  const environment = deployment?.environment.name ?? 'no-environment'
+  return `${namespace}/${service.name}@${service.version}/${instance}/${environment}`
+}
+
+/** `event.name` is declared, so it reads as a string without a cast. */
+function eventOf(entry: LogEntry): string | undefined {
+  return entry['event.name']
+}
+```
+
 ### `ILogDestination`
 
 ```typescript