@bymax-one/nest-logger 1.2.1 → 1.2.3

package/CHANGELOG.md

@@ -11,6 +11,81 @@ heading here.
 
 ## [Unreleased]
 
+## [1.2.3] - 2026-08-14
+
+### Fixed
+
+- **A destination that fails to initialize no longer silences the entire application.** Reported
+  by a consumer while wiring pretty local output, and reproduced end to end: `destinations`
+  **replaces** the default stdout sink, so `destinations: [new PrettyDevDestination()]` without the
+  optional `pino-pretty` installed left the app booting, running, exiting `0` and writing **not one
+  byte to stdout or stderr** — including the `LOGGER_DESTINATION_INIT_FAILED` entry that exists to
+  explain exactly this, which was delivered into the dead sink. Not a crash and not a degraded
+  mode: silence that looks like a quiet service.
+
+  Four independently reasonable behaviours composed into it — `destinations` replacing rather than
+  adding, the failure being reported through `this.logger`, the multistream being built from the
+  full registered list (it is wired while NestJS builds the DI graph, before any `onInit` runs), and
+  a failed sink dropping its writes. Three changes break the chain:
+
+  - the init failure is written **directly to `process.stderr`**, matching what the shutdown path
+    and the write path already do, and for the same reason — reporting a broken sink through the
+    sink set is a feedback loop;
+  - a destination whose `onInit` rejected is **excluded from the write fan-out**;
+  - when **no** destination initializes, entries **fall back to raw NDJSON on stdout**, so a
+    misconfiguration degrades visibly instead of going quiet. The fallback is elected before the
+    bootstrap entries are announced, so `LOGGER_BOOTSTRAP_WARNING` — the signal that PII redaction
+    was disabled — survives the failure it would otherwise have been lost to.
+
+  The defect belonged to `destinations` as a general contract, not to `PrettyDevDestination`: any
+  consumer-written sink that failed `onInit` as the only registered destination did the same thing.
+  `pino-pretty` remains an optional peer and nothing was added to `dependencies`, which stays `{}`.
+
+### Breaking
+
+- **`isPretty` is removed from `BymaxLoggerModuleOptions`.** It has been `@deprecated` and **inert**
+  — a `true` value never changed any output on its own. An option that does nothing is worse than
+  an absent one, because it is a knob a consumer turns and then reasons from.
+
+  **Migration:** delete the option. Nothing about your output changes, because nothing about your
+  output depended on it. For pretty local logs, add `new PrettyDevDestination()` to `destinations`
+  and install the optional `pino-pretty` peer — which is what the option's own documentation had
+  been telling you to do.
+
+  Type-level only: `applyDefaults` no longer emits the field, and no runtime behaviour is affected.
+
+### Documentation
+
+- **`destinations` documents that it REPLACES the default stdout sink**, rather than claiming to add
+  "custom destinations beyond `DefaultStdoutDestination`". Replacement is the correct behaviour — a
+  file-only or socket-only deployment must be able to turn stdout off — but the doc described the
+  opposite, and it is the assumption that makes the failure above easy to arrive at.
+- **`PrettyDevDestination` no longer implies it follows Pino's recommended transport form.** It runs
+  `pino-pretty` as a main-thread transform, a documented pino-pretty API; Pino's own docs recommend
+  `transport: { target: 'pino-pretty' }` in a worker, which is unreachable here because this library
+  owns the Pino instance and fans out through `pino.multistream`.
+
+## [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
@@ -793,7 +868,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.1...HEAD
+[Unreleased]: https://github.com/bymaxone/nest-logger/compare/v1.2.3...HEAD
+[1.2.3]: https://github.com/bymaxone/nest-logger/compare/v1.2.2...v1.2.3
+[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

package/README.md

@@ -101,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)
@@ -546,24 +546,23 @@ 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                                                                                             |
-| `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                                                                |
+| 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`                                                               |
+| `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[]`             | `[new DefaultStdoutDestination()]` | The sinks entries are written to. ⚠️ A non-empty list **replaces** that default — see [Destinations](#destinations-replace-stdout)         |
 
 ### `http` options
 
@@ -713,6 +712,21 @@ BymaxLoggerModule.forRootAsync({
 })
 ```
 
+### Destinations replace stdout
+
+A non-empty `destinations` **replaces** `DefaultStdoutDestination` — it does not add to it. That is deliberate: a file-only or socket-only deployment has to be able to turn structured stdout off. To keep stdout alongside a custom sink, list it explicitly:
+
+```typescript
+destinations: [new DefaultStdoutDestination(), new LokiDestination({ ... })]
+```
+
+The consequence worth knowing: a sink you supply may be the **only** one the application has, so its failure is the application's silence. Two guarantees cover that, and neither requires anything from you:
+
+- **A destination that fails `onInit` is reported as `LOGGER_DESTINATION_INIT_FAILED` on `stderr`** — not through the logger, whose sinks are the ones that just failed — and receives no entries.
+- **If _every_ destination fails to initialize, entries fall back to raw NDJSON on `stdout`.** Degraded and ugly, but visible; nothing is lost, including the bootstrap entries.
+
+So the common accident — adding `new PrettyDevDestination()` without installing the optional `pino-pretty` — costs you colours and a line on stderr telling you why, never your logs.
+
 ### Postgres destination (Prisma)
 
 ```typescript
@@ -1093,7 +1107,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`. */
@@ -1102,7 +1137,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
@@ -1113,6 +1153,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

package/dist/server/index.cjs

@@ -76,7 +76,6 @@ function applyDefaults(options) {
     redactCensor: options.redactCensor ?? "[REDACTED]",
     shouldDisableDefaultRedact: options.shouldDisableDefaultRedact ?? false,
     destinations: Object.freeze([...options.destinations ?? []]),
-    isPretty: options.isPretty ?? !isProduction,
     http: Object.freeze({
       ...http,
       excludePaths: Object.freeze([...http.excludePaths])
@@ -1021,22 +1020,43 @@ function compileRedactPaths(extraPaths, shouldSkipDefaults) {
   const sources = shouldSkipDefaults ? [extraPaths] : [DEFAULT_REDACT_PATHS, extraPaths];
   return Array.from(new Set(sources.flat()));
 }
-function reportWriteFailure(name, cause) {
-  const err = cause instanceof Error ? { type: cause.name, message: cause.message } : { type: "UnknownError", message: String(cause) };
+
+// src/server/utils/report-destination-failure.util.ts
+function reportDestinationFailure(logKey, name, cause, msg) {
   try {
+    const err = cause instanceof Error ? {
+      type: toSingleLineMessage(String(cause.name)),
+      message: toSingleLineMessage(String(cause.message))
+    } : { type: "UnknownError", message: toSingleLineMessage(String(cause)) };
     process.stderr.write(
       JSON.stringify({
         level: "error",
-        logKey: RESERVED_LOG_KEYS.LOGGER_DESTINATION_WRITE_FAILED,
-        destination: name,
+        logKey,
+        destination: toSingleLineMessage(name),
         err,
-        msg: `Log destination "${name}" failed to write; the entry was dropped`
+        msg: toSingleLineMessage(msg)
       }) + "\n"
     );
   } catch {
   }
 }
-function destinationToStream(destination) {
+
+// src/server/utils/destination-to-stream.ts
+function reportWriteFailure(name, cause) {
+  reportDestinationFailure(
+    RESERVED_LOG_KEYS.LOGGER_DESTINATION_WRITE_FAILED,
+    name,
+    cause,
+    `Log destination "${name}" failed to write; the entry was dropped`
+  );
+}
+function rescueToStdout(payload) {
+  try {
+    process.stdout.write(payload);
+  } catch {
+  }
+}
+function destinationToStream(destination, health) {
   return new stream.Writable({
     // Keep string chunks as strings (Node's default re-encodes them to Buffers
     // before `_write`): the common Pino path emits NDJSON strings, so this skips
@@ -1050,6 +1070,13 @@ function destinationToStream(destination) {
       };
       try {
         const payload = typeof chunk === "string" ? chunk : chunk.toString("utf-8");
+        if (health.isFailed(destination)) {
+          if (health.shouldRescue(destination)) {
+            rescueToStdout(payload);
+          }
+          callback();
+          return;
+        }
         const result = destination.write(payload);
         if (result instanceof Promise) {
           result.then(() => callback(), onFailure);
@@ -1439,7 +1466,7 @@ function resolveRedactOption(options) {
   }
   return { paths, censor: options.redactCensor };
 }
-function buildPinoInstance(options, logContext, destinations) {
+function buildPinoInstance(options, logContext, destinations, health) {
   const maxBytes = options.maxEntrySizeBytes;
   const redact = resolveNameRedactor(options);
   const bound = (serializer) => createSizeBoundedSerializer((input) => redact(serializer(input)), maxBytes);
@@ -1511,55 +1538,162 @@ function buildPinoInstance(options, logContext, destinations) {
   };
   const streams = destinations.map((destination) => ({
     level: destination.minLevel ?? options.level,
-    stream: destinationToStream(destination)
+    stream: destinationToStream(destination, health)
   }));
   return pino__default.default(pinoOptions, pino__default.default.multistream(streams));
 }
+var DestinationHealth = class {
+  constructor() {
+    /** Destinations whose `onInit()` rejected. Identity-keyed, not name-keyed. */
+    this.failed = /* @__PURE__ */ new Set();
+    /**
+     * Whether ANY destination initialized successfully.
+     *
+     * A boolean rather than a count, deliberately: the only question ever asked of
+     * it is "is there somewhere to write?". Mutation testing made the point — a
+     * counter incremented with `+=` survived being flipped to `-=`, because
+     * `count === 0` means the same thing either way. A value whose arithmetic
+     * cannot be observed was not a counter, it was a flag wearing a number.
+     */
+    this.hasHealthy = false;
+    /**
+     * The rescuer's severity index within {@link LOG_LEVEL_PRIORITY}. Starts above
+     * every real level so the first `markFailed` always wins the comparison.
+     */
+    this.rescuerLevel = Number.POSITIVE_INFINITY;
+  }
+  /** Record that a destination initialized successfully. */
+  markHealthy() {
+    this.hasHealthy = true;
+  }
+  /**
+   * Record that a destination failed to initialize, and re-elect the rescuer.
+   *
+   * The rescuer is the failed destination with the LOWEST effective level, ties
+   * broken by registration order (the comparison is strict). Registration order
+   * alone is deterministic but arbitrary: a `warn` sink registered before an
+   * `info` one would rescue at `warn` and silently drop the `info` entries the
+   * second was configured to receive, and swapping the array would change the
+   * output for the same configuration. Electing by level rescues the UNION of
+   * what the consumer asked to see.
+   *
+   * Inheriting a level filter at all is deliberate — `minLevel` is the consumer's
+   * own instruction, so the rescue delivers what a working sink would have, never
+   * more. The one entry that must never be filtered, the init failure itself, goes
+   * straight to stderr, outside the multistream.
+   *
+   * @param destination - The destination whose `onInit()` rejected.
+   * @param effectiveLevel - Its multistream level: `minLevel` when set, otherwise
+   *   the module-wide `level`.
+   */
+  markFailed(destination, effectiveLevel) {
+    this.failed.add(destination);
+    const level = LOG_LEVEL_PRIORITY.indexOf(effectiveLevel);
+    if (level < this.rescuerLevel) {
+      this.rescuer = destination;
+      this.rescuerLevel = level;
+    }
+  }
+  /**
+   * Whether a destination failed to initialize and must not receive writes.
+   *
+   * @param destination - The destination backing a fan-out stream.
+   * @returns `true` when its `onInit()` rejected.
+   */
+  isFailed(destination) {
+    return this.failed.has(destination);
+  }
+  /**
+   * Whether this destination is the one that must write the entry as raw NDJSON
+   * to stdout because NOTHING initialized.
+   *
+   * Exactly one failed destination can satisfy this, so N failed sinks rescue an
+   * entry once rather than N times.
+   *
+   * @param destination - The destination backing a fan-out stream.
+   * @returns `true` when no destination initialized and this one is the elected
+   *   rescuer.
+   */
+  shouldRescue(destination) {
+    return !this.hasHealthy && this.rescuer === destination;
+  }
+};
+DestinationHealth = __decorateClass([
+  common.Injectable()
+], DestinationHealth);
 var DestinationRegistry = class {
   /**
    * @param registered - Every destination declared under
    *   `LOGGER_DESTINATIONS_TOKEN`. Injected by token explicitly because the
    *   package is bundled without `emitDecoratorMetadata`.
-   * @param logger - Structured logger used to report init failures. Injected by
-   *   token explicitly for the same bundling reason.
+   * @param logger - Structured logger used for the bootstrap entries. Injected by
+   *   token explicitly for the same bundling reason. Deliberately NOT used to
+   *   report init failures — see the file-level note.
+   * @param options - Resolved module options, read for the bootstrap warnings and
+   *   for each destination's effective level.
+   * @param health - Init-health record shared with the write fan-out.
    */
-  constructor(registered, logger, options) {
+  constructor(registered, logger, options, health) {
     this.registered = registered;
     this.logger = logger;
     this.options = options;
+    this.health = health;
     /**
      * Destinations that initialized successfully, in registration order.
      *
-     * Note: the Pino multistream is built from the full registered list, and the
-     * write path is independently fail-soft (see `destinationToStream`). This set
-     * is the authoritative record of init success — it drives reverse-order
-     * shutdown — but is not currently used to remove a failed-init sink from the
-     * write fan-out; a sink that failed `onInit` still receives writes, contained
-     * fail-soft by the wrapper.
+     * Authoritative for BOTH shutdown (reverse order) and — via the shared
+     * `DestinationHealth` record written alongside it — the write fan-out. The two
+     * are kept in step here because the multistream itself is wired before any
+     * `onInit` runs and cannot be rebuilt afterwards; see `DestinationHealth`.
      */
     this.active = [];
   }
   /**
    * Initialize every registered destination. A destination whose `onInit`
-   * rejects is skipped (not added to the active set) and reported — it must not
-   * block application bootstrap.
+   * rejects is skipped (not added to the active set), marked failed so the
+   * fan-out stops writing to it, and reported to stderr — it must not block
+   * application bootstrap.
+   *
+   * The loop completes BEFORE {@link announceBootstrap}, and that ordering is
+   * load-bearing rather than incidental: the health record is what lets a
+   * last-resort sink carry the bootstrap entries when every destination failed.
+   * Announcing first would emit them into a fan-out that has not yet been told
+   * anything is wrong, and `LOGGER_BOOTSTRAP_WARNING` — the signal that exists so
+   * a security review can see PII redaction was disabled — would be lost exactly
+   * when the configuration is already known to be broken.
    */
   async onModuleInit() {
     for (const destination of this.registered) {
       try {
         await destination.onInit?.();
         this.active.push(destination);
+        this.health.markHealthy();
       } catch (cause) {
-        this.logger.errorStructured(
-          RESERVED_LOG_KEYS.LOGGER_DESTINATION_INIT_FAILED,
-          cause instanceof Error ? cause : new Error(String(cause)),
-          void 0,
-          { destination: destination.name }
-        );
+        this.health.markFailed(destination, destination.minLevel ?? this.options.level);
+        this.reportInitFailure(destination.name, cause);
       }
     }
     this.announceBootstrap();
   }
+  /**
+   * Report one destination init failure as a structured
+   * `LOGGER_DESTINATION_INIT_FAILED` line on `process.stderr`.
+   *
+   * Shares {@link reportDestinationFailure} with the write-failure path rather
+   * than restating the shape, so an operator greps one `logKey` regardless of
+   * which stage failed — and the two cannot drift apart.
+   *
+   * @param name - The failing destination's name.
+   * @param cause - The thrown or rejected value.
+   */
+  reportInitFailure(name, cause) {
+    reportDestinationFailure(
+      RESERVED_LOG_KEYS.LOGGER_DESTINATION_INIT_FAILED,
+      name,
+      cause,
+      `Log destination "${name}" failed to initialize and will receive no entries. If no destination initializes, entries fall back to raw NDJSON on stdout.`
+    );
+  }
   /**
    * Emit the one-shot bootstrap entries, AFTER every destination has been
    * initialized.
@@ -1637,7 +1771,8 @@ DestinationRegistry = __decorateClass([
   common.Injectable(),
   __decorateParam(0, common.Inject(LOGGER_DESTINATIONS_TOKEN)),
   __decorateParam(1, common.Inject(exports.PinoLoggerService)),
-  __decorateParam(2, common.Inject(LOGGER_OPTIONS_TOKEN))
+  __decorateParam(2, common.Inject(LOGGER_OPTIONS_TOKEN)),
+  __decorateParam(3, common.Inject(DestinationHealth))
 ], DestinationRegistry);
 var FORBIDDEN_CONTEXT_KEYS = PROTOTYPE_POLLUTING_KEYS;
 exports.LogContextService = class LogContextService {
@@ -1732,6 +1867,10 @@ function buildCommonProviders() {
   return [
     exports.LogContextService,
     { provide: LOG_CONTEXT_TOKEN, useExisting: exports.LogContextService },
+    // Shared by the Pino factory (which closes over it in every fan-out stream)
+    // and by DestinationRegistry (which writes to it during onModuleInit). Both
+    // depend on this provider and it depends on nothing, so there is no cycle.
+    DestinationHealth,
     {
       // The DEFAULT-coverage redactor, shared by the Pino factory's hooks and by
       // `PinoLoggerService.child()`. The latter needs it as a provider because
@@ -1742,8 +1881,13 @@ function buildCommonProviders() {
     },
     {
       provide: LOGGER_PINO_INSTANCE_TOKEN,
-      useFactory: (options, logContext, destinations) => buildPinoInstance(options, logContext, destinations),
-      inject: [LOGGER_OPTIONS_TOKEN, exports.LogContextService, LOGGER_DESTINATIONS_TOKEN]
+      useFactory: (options, logContext, destinations, health) => buildPinoInstance(options, logContext, destinations, health),
+      inject: [
+        LOGGER_OPTIONS_TOKEN,
+        exports.LogContextService,
+        LOGGER_DESTINATIONS_TOKEN,
+        DestinationHealth
+      ]
     },
     {
       provide: LOGGER_DESTINATIONS_TOKEN,
@@ -1934,8 +2078,10 @@ var PrettyDevDestination = class {
    *
    * Three states:
    *   - initialized → forward to the pino-pretty transform;
-   *   - init failed → DROP (the destination was removed from the active set, so
-   *     it must not duplicate raw NDJSON to stdout);
+   *   - init failed → DROP, so a co-registered stdout sink is not duplicated. The
+   *     fan-out already skips a failed destination before reaching this method
+   *     (and rescues the entry when nothing else initialized); this branch is the
+   *     belt to that, for any caller holding the destination directly;
    *   - pre-init (transient window before {@link onInit}, e.g. a bootstrap log)
    *     → fall back to raw stdout so the entry is not lost.
    *

package/dist/server/index.d.cts

@@ -125,6 +125,26 @@ interface ServiceMetadata {
      */
     readonly environment?: string;
 }
+/**
+ * Service identity after precedence has been applied.
+ *
+ * Distinct from {@link ServiceMetadata} because the optional fields here mean
+ * "resolved to nothing" rather than "not configured": every source — options,
+ * `OTEL_SERVICE_NAME`, `OTEL_RESOURCE_ATTRIBUTES`, `NODE_ENV` — has already been
+ * consulted, and a field still absent will not appear on any entry.
+ */
+interface ResolvedServiceMetadata {
+    /** `service.name`, always present. */
+    name: string;
+    /** `service.version`, always present. */
+    version: string;
+    /** `service.namespace`, when any source supplied one. */
+    namespace?: string;
+    /** `service.instance.id`, when any source supplied one. */
+    instanceId?: string;
+    /** `deployment.environment.name`, when any source supplied one. */
+    environment?: string;
+}
 /**
  * The `service` block as it appears in an EMITTED record, under the default
  * `resourceFormat: 'nested'`.
@@ -314,15 +334,22 @@ interface BymaxLoggerModuleOptions {
     redactCensor?: string;
     /** Disable default redact paths (use with caution). Default: false. */
     shouldDisableDefaultRedact?: boolean;
-    /** Custom destinations beyond `DefaultStdoutDestination`. */
-    destinations?: readonly ILogDestination[];
     /**
-     * @deprecated Currently inert — a `true` value does not change output on its
-     *   own. For pretty local logs add `new PrettyDevDestination()` to
-     *   `destinations` (and install the optional `pino-pretty` peer dep).
-     *   Default: `NODE_ENV !== 'production'`.
+     * The sinks every entry is written to.
+     *
+     * A non-empty list **REPLACES** `DefaultStdoutDestination` — it does not add to
+     * it. That is deliberate: a file-only or socket-only deployment has to be able
+     * to turn stdout off. It also means a sink supplied here may be the only one
+     * the application has, so a destination that fails `onInit` is reported on
+     * stderr and, if nothing else initialized, entries fall back to raw NDJSON on
+     * stdout rather than disappearing.
+     *
+     * Include `new DefaultStdoutDestination()` explicitly to keep structured stdout
+     * alongside a custom sink.
+     *
+     * Default: `[new DefaultStdoutDestination()]`.
      */
-    isPretty?: boolean;
+    destinations?: readonly ILogDestination[];
     /** HTTP module configuration. */
     http?: HttpOptions;
     /** OpenTelemetry integration tuning. */
@@ -512,6 +539,11 @@ declare const RESERVED_LOG_KEYS_NOT_EMITTED: Readonly<{
      */
     readonly HTTP_REQUEST_COMPLETED: "reserved: superseded by the four status-specific terminal keys";
 }>;
+/**
+ * Strongly-typed union of every reserved log key value, derived from
+ * {@link RESERVED_LOG_KEYS}. Use this type to constrain log-key arguments.
+ */
+type ReservedLogKey = (typeof RESERVED_LOG_KEYS)[keyof typeof RESERVED_LOG_KEYS];
 
 /**
  * Name-based recursive redaction.
@@ -885,8 +917,10 @@ declare class PrettyDevDestination implements ILogDestination {
      *
      * Three states:
      *   - initialized → forward to the pino-pretty transform;
-     *   - init failed → DROP (the destination was removed from the active set, so
-     *     it must not duplicate raw NDJSON to stdout);
+     *   - init failed → DROP, so a co-registered stdout sink is not duplicated. The
+     *     fan-out already skips a failed destination before reaching this method
+     *     (and rescues the entry when nothing else initialized); this branch is the
+     *     belt to that, for any caller holding the destination directly;
      *   - pre-init (transient window before {@link onInit}, e.g. a bootstrap log)
      *     → fall back to raw stdout so the entry is not lost.
      *
@@ -1287,6 +1321,17 @@ interface LogEntry {
     msg: string;
     /** Convention key — `MODULE_ACTION_RESULT` format. */
     logKey?: string;
+    /**
+     * OTel event name derived from {@link logKey} (`PAYMENT_FAILED` →
+     * `payment.failed`), emitted on structured calls unless `eventNameField` is
+     * `false`. Declared explicitly because the index signature below would type
+     * it `unknown`: a documented field a consumer cannot read without a cast is
+     * not really published.
+     *
+     * The key is configurable, so a renamed field arrives through the index
+     * signature instead — this declaration describes the default only.
+     */
+    'event.name'?: string;
     /**
      * Service identity as EMITTED — see {@link EmittedServiceResource}. Not the
      * configuration shape: `service.instance.id` nests, and the environment lives
@@ -1337,4 +1382,4 @@ interface LogEntry {
  */
 declare const LOG_KEYS_CONVENTION_REGEX: RegExp;
 
-export { BymaxLoggerModule, type BymaxLoggerModuleAsyncOptions, type BymaxLoggerModuleOptions, type BymaxLoggerModuleOptionsFactory, DEFAULT_REDACT_PATHS, DefaultStdoutDestination, HttpExceptionFilter, HttpLoggingInterceptor, type HttpOptions, type ILogDestination, type IncomingHeaders, InjectLogger, LOGGER_DESTINATIONS_TOKEN, LOGGER_OPTIONS_TOKEN, LOGGER_PINO_INSTANCE_TOKEN, LOG_CONTEXT_METADATA_KEY, LOG_CONTEXT_TOKEN, LOG_KEYS_CONVENTION_REGEX, LogContext, type LogContext$1 as LogContextBag, LogContextService, type LogEntry, type LogLevel, LogPerformance, type LoggableRequest, type LoggableResponse, type NextHandler, type OtelOptions, PINO_LEVEL_NAMES, PINO_LEVEL_NUMBERS, PinoLoggerService, PrettyDevDestination, RESERVED_LOG_KEYS, RESERVED_LOG_KEYS_NOT_EMITTED, RequestIdMiddleware, type ResolvedBymaxLoggerModuleOptions, type ServiceMetadata, applyRequestIdMiddleware };
+export { BymaxLoggerModule, type BymaxLoggerModuleAsyncOptions, type BymaxLoggerModuleOptions, type BymaxLoggerModuleOptionsFactory, DEFAULT_REDACT_PATHS, DefaultStdoutDestination, type EmittedDeploymentResource, type EmittedServiceResource, HttpExceptionFilter, HttpLoggingInterceptor, type HttpOptions, type ILogDestination, type IncomingHeaders, InjectLogger, LOGGER_DESTINATIONS_TOKEN, LOGGER_OPTIONS_TOKEN, LOGGER_PINO_INSTANCE_TOKEN, LOG_CONTEXT_METADATA_KEY, LOG_CONTEXT_TOKEN, LOG_KEYS_CONVENTION_REGEX, LogContext, type LogContext$1 as LogContextBag, LogContextService, type LogEntry, type LogLevel, LogPerformance, type LoggableRequest, type LoggableResponse, type NextHandler, type OtelOptions, PINO_LEVEL_NAMES, PINO_LEVEL_NUMBERS, PinoLoggerService, PrettyDevDestination, RESERVED_LOG_KEYS, RESERVED_LOG_KEYS_NOT_EMITTED, RequestIdMiddleware, type ReservedLogKey, type ResolvedBymaxLoggerModuleOptions, type ResolvedServiceMetadata, type ServiceMetadata, applyRequestIdMiddleware };

package/dist/server/index.d.ts

@@ -125,6 +125,26 @@ interface ServiceMetadata {
      */
     readonly environment?: string;
 }
+/**
+ * Service identity after precedence has been applied.
+ *
+ * Distinct from {@link ServiceMetadata} because the optional fields here mean
+ * "resolved to nothing" rather than "not configured": every source — options,
+ * `OTEL_SERVICE_NAME`, `OTEL_RESOURCE_ATTRIBUTES`, `NODE_ENV` — has already been
+ * consulted, and a field still absent will not appear on any entry.
+ */
+interface ResolvedServiceMetadata {
+    /** `service.name`, always present. */
+    name: string;
+    /** `service.version`, always present. */
+    version: string;
+    /** `service.namespace`, when any source supplied one. */
+    namespace?: string;
+    /** `service.instance.id`, when any source supplied one. */
+    instanceId?: string;
+    /** `deployment.environment.name`, when any source supplied one. */
+    environment?: string;
+}
 /**
  * The `service` block as it appears in an EMITTED record, under the default
  * `resourceFormat: 'nested'`.
@@ -314,15 +334,22 @@ interface BymaxLoggerModuleOptions {
     redactCensor?: string;
     /** Disable default redact paths (use with caution). Default: false. */
     shouldDisableDefaultRedact?: boolean;
-    /** Custom destinations beyond `DefaultStdoutDestination`. */
-    destinations?: readonly ILogDestination[];
     /**
-     * @deprecated Currently inert — a `true` value does not change output on its
-     *   own. For pretty local logs add `new PrettyDevDestination()` to
-     *   `destinations` (and install the optional `pino-pretty` peer dep).
-     *   Default: `NODE_ENV !== 'production'`.
+     * The sinks every entry is written to.
+     *
+     * A non-empty list **REPLACES** `DefaultStdoutDestination` — it does not add to
+     * it. That is deliberate: a file-only or socket-only deployment has to be able
+     * to turn stdout off. It also means a sink supplied here may be the only one
+     * the application has, so a destination that fails `onInit` is reported on
+     * stderr and, if nothing else initialized, entries fall back to raw NDJSON on
+     * stdout rather than disappearing.
+     *
+     * Include `new DefaultStdoutDestination()` explicitly to keep structured stdout
+     * alongside a custom sink.
+     *
+     * Default: `[new DefaultStdoutDestination()]`.
      */
-    isPretty?: boolean;
+    destinations?: readonly ILogDestination[];
     /** HTTP module configuration. */
     http?: HttpOptions;
     /** OpenTelemetry integration tuning. */
@@ -512,6 +539,11 @@ declare const RESERVED_LOG_KEYS_NOT_EMITTED: Readonly<{
      */
     readonly HTTP_REQUEST_COMPLETED: "reserved: superseded by the four status-specific terminal keys";
 }>;
+/**
+ * Strongly-typed union of every reserved log key value, derived from
+ * {@link RESERVED_LOG_KEYS}. Use this type to constrain log-key arguments.
+ */
+type ReservedLogKey = (typeof RESERVED_LOG_KEYS)[keyof typeof RESERVED_LOG_KEYS];
 
 /**
  * Name-based recursive redaction.
@@ -885,8 +917,10 @@ declare class PrettyDevDestination implements ILogDestination {
      *
      * Three states:
      *   - initialized → forward to the pino-pretty transform;
-     *   - init failed → DROP (the destination was removed from the active set, so
-     *     it must not duplicate raw NDJSON to stdout);
+     *   - init failed → DROP, so a co-registered stdout sink is not duplicated. The
+     *     fan-out already skips a failed destination before reaching this method
+     *     (and rescues the entry when nothing else initialized); this branch is the
+     *     belt to that, for any caller holding the destination directly;
      *   - pre-init (transient window before {@link onInit}, e.g. a bootstrap log)
      *     → fall back to raw stdout so the entry is not lost.
      *
@@ -1287,6 +1321,17 @@ interface LogEntry {
     msg: string;
     /** Convention key — `MODULE_ACTION_RESULT` format. */
     logKey?: string;
+    /**
+     * OTel event name derived from {@link logKey} (`PAYMENT_FAILED` →
+     * `payment.failed`), emitted on structured calls unless `eventNameField` is
+     * `false`. Declared explicitly because the index signature below would type
+     * it `unknown`: a documented field a consumer cannot read without a cast is
+     * not really published.
+     *
+     * The key is configurable, so a renamed field arrives through the index
+     * signature instead — this declaration describes the default only.
+     */
+    'event.name'?: string;
     /**
      * Service identity as EMITTED — see {@link EmittedServiceResource}. Not the
      * configuration shape: `service.instance.id` nests, and the environment lives
@@ -1337,4 +1382,4 @@ interface LogEntry {
  */
 declare const LOG_KEYS_CONVENTION_REGEX: RegExp;
 
-export { BymaxLoggerModule, type BymaxLoggerModuleAsyncOptions, type BymaxLoggerModuleOptions, type BymaxLoggerModuleOptionsFactory, DEFAULT_REDACT_PATHS, DefaultStdoutDestination, HttpExceptionFilter, HttpLoggingInterceptor, type HttpOptions, type ILogDestination, type IncomingHeaders, InjectLogger, LOGGER_DESTINATIONS_TOKEN, LOGGER_OPTIONS_TOKEN, LOGGER_PINO_INSTANCE_TOKEN, LOG_CONTEXT_METADATA_KEY, LOG_CONTEXT_TOKEN, LOG_KEYS_CONVENTION_REGEX, LogContext, type LogContext$1 as LogContextBag, LogContextService, type LogEntry, type LogLevel, LogPerformance, type LoggableRequest, type LoggableResponse, type NextHandler, type OtelOptions, PINO_LEVEL_NAMES, PINO_LEVEL_NUMBERS, PinoLoggerService, PrettyDevDestination, RESERVED_LOG_KEYS, RESERVED_LOG_KEYS_NOT_EMITTED, RequestIdMiddleware, type ResolvedBymaxLoggerModuleOptions, type ServiceMetadata, applyRequestIdMiddleware };
+export { BymaxLoggerModule, type BymaxLoggerModuleAsyncOptions, type BymaxLoggerModuleOptions, type BymaxLoggerModuleOptionsFactory, DEFAULT_REDACT_PATHS, DefaultStdoutDestination, type EmittedDeploymentResource, type EmittedServiceResource, HttpExceptionFilter, HttpLoggingInterceptor, type HttpOptions, type ILogDestination, type IncomingHeaders, InjectLogger, LOGGER_DESTINATIONS_TOKEN, LOGGER_OPTIONS_TOKEN, LOGGER_PINO_INSTANCE_TOKEN, LOG_CONTEXT_METADATA_KEY, LOG_CONTEXT_TOKEN, LOG_KEYS_CONVENTION_REGEX, LogContext, type LogContext$1 as LogContextBag, LogContextService, type LogEntry, type LogLevel, LogPerformance, type LoggableRequest, type LoggableResponse, type NextHandler, type OtelOptions, PINO_LEVEL_NAMES, PINO_LEVEL_NUMBERS, PinoLoggerService, PrettyDevDestination, RESERVED_LOG_KEYS, RESERVED_LOG_KEYS_NOT_EMITTED, RequestIdMiddleware, type ReservedLogKey, type ResolvedBymaxLoggerModuleOptions, type ResolvedServiceMetadata, type ServiceMetadata, applyRequestIdMiddleware };

package/dist/server/index.mjs

@@ -73,7 +73,6 @@ function applyDefaults(options) {
     redactCensor: options.redactCensor ?? "[REDACTED]",
     shouldDisableDefaultRedact: options.shouldDisableDefaultRedact ?? false,
     destinations: Object.freeze([...options.destinations ?? []]),
-    isPretty: options.isPretty ?? !isProduction,
     http: Object.freeze({
       ...http,
       excludePaths: Object.freeze([...http.excludePaths])
@@ -1018,22 +1017,43 @@ function compileRedactPaths(extraPaths, shouldSkipDefaults) {
   const sources = shouldSkipDefaults ? [extraPaths] : [DEFAULT_REDACT_PATHS, extraPaths];
   return Array.from(new Set(sources.flat()));
 }
-function reportWriteFailure(name, cause) {
-  const err = cause instanceof Error ? { type: cause.name, message: cause.message } : { type: "UnknownError", message: String(cause) };
+
+// src/server/utils/report-destination-failure.util.ts
+function reportDestinationFailure(logKey, name, cause, msg) {
   try {
+    const err = cause instanceof Error ? {
+      type: toSingleLineMessage(String(cause.name)),
+      message: toSingleLineMessage(String(cause.message))
+    } : { type: "UnknownError", message: toSingleLineMessage(String(cause)) };
     process.stderr.write(
       JSON.stringify({
         level: "error",
-        logKey: RESERVED_LOG_KEYS.LOGGER_DESTINATION_WRITE_FAILED,
-        destination: name,
+        logKey,
+        destination: toSingleLineMessage(name),
         err,
-        msg: `Log destination "${name}" failed to write; the entry was dropped`
+        msg: toSingleLineMessage(msg)
       }) + "\n"
     );
   } catch {
   }
 }
-function destinationToStream(destination) {
+
+// src/server/utils/destination-to-stream.ts
+function reportWriteFailure(name, cause) {
+  reportDestinationFailure(
+    RESERVED_LOG_KEYS.LOGGER_DESTINATION_WRITE_FAILED,
+    name,
+    cause,
+    `Log destination "${name}" failed to write; the entry was dropped`
+  );
+}
+function rescueToStdout(payload) {
+  try {
+    process.stdout.write(payload);
+  } catch {
+  }
+}
+function destinationToStream(destination, health) {
   return new Writable({
     // Keep string chunks as strings (Node's default re-encodes them to Buffers
     // before `_write`): the common Pino path emits NDJSON strings, so this skips
@@ -1047,6 +1067,13 @@ function destinationToStream(destination) {
       };
       try {
         const payload = typeof chunk === "string" ? chunk : chunk.toString("utf-8");
+        if (health.isFailed(destination)) {
+          if (health.shouldRescue(destination)) {
+            rescueToStdout(payload);
+          }
+          callback();
+          return;
+        }
         const result = destination.write(payload);
         if (result instanceof Promise) {
           result.then(() => callback(), onFailure);
@@ -1436,7 +1463,7 @@ function resolveRedactOption(options) {
   }
   return { paths, censor: options.redactCensor };
 }
-function buildPinoInstance(options, logContext, destinations) {
+function buildPinoInstance(options, logContext, destinations, health) {
   const maxBytes = options.maxEntrySizeBytes;
   const redact = resolveNameRedactor(options);
   const bound = (serializer) => createSizeBoundedSerializer((input) => redact(serializer(input)), maxBytes);
@@ -1508,55 +1535,162 @@ function buildPinoInstance(options, logContext, destinations) {
   };
   const streams = destinations.map((destination) => ({
     level: destination.minLevel ?? options.level,
-    stream: destinationToStream(destination)
+    stream: destinationToStream(destination, health)
   }));
   return pino(pinoOptions, pino.multistream(streams));
 }
+var DestinationHealth = class {
+  constructor() {
+    /** Destinations whose `onInit()` rejected. Identity-keyed, not name-keyed. */
+    this.failed = /* @__PURE__ */ new Set();
+    /**
+     * Whether ANY destination initialized successfully.
+     *
+     * A boolean rather than a count, deliberately: the only question ever asked of
+     * it is "is there somewhere to write?". Mutation testing made the point — a
+     * counter incremented with `+=` survived being flipped to `-=`, because
+     * `count === 0` means the same thing either way. A value whose arithmetic
+     * cannot be observed was not a counter, it was a flag wearing a number.
+     */
+    this.hasHealthy = false;
+    /**
+     * The rescuer's severity index within {@link LOG_LEVEL_PRIORITY}. Starts above
+     * every real level so the first `markFailed` always wins the comparison.
+     */
+    this.rescuerLevel = Number.POSITIVE_INFINITY;
+  }
+  /** Record that a destination initialized successfully. */
+  markHealthy() {
+    this.hasHealthy = true;
+  }
+  /**
+   * Record that a destination failed to initialize, and re-elect the rescuer.
+   *
+   * The rescuer is the failed destination with the LOWEST effective level, ties
+   * broken by registration order (the comparison is strict). Registration order
+   * alone is deterministic but arbitrary: a `warn` sink registered before an
+   * `info` one would rescue at `warn` and silently drop the `info` entries the
+   * second was configured to receive, and swapping the array would change the
+   * output for the same configuration. Electing by level rescues the UNION of
+   * what the consumer asked to see.
+   *
+   * Inheriting a level filter at all is deliberate — `minLevel` is the consumer's
+   * own instruction, so the rescue delivers what a working sink would have, never
+   * more. The one entry that must never be filtered, the init failure itself, goes
+   * straight to stderr, outside the multistream.
+   *
+   * @param destination - The destination whose `onInit()` rejected.
+   * @param effectiveLevel - Its multistream level: `minLevel` when set, otherwise
+   *   the module-wide `level`.
+   */
+  markFailed(destination, effectiveLevel) {
+    this.failed.add(destination);
+    const level = LOG_LEVEL_PRIORITY.indexOf(effectiveLevel);
+    if (level < this.rescuerLevel) {
+      this.rescuer = destination;
+      this.rescuerLevel = level;
+    }
+  }
+  /**
+   * Whether a destination failed to initialize and must not receive writes.
+   *
+   * @param destination - The destination backing a fan-out stream.
+   * @returns `true` when its `onInit()` rejected.
+   */
+  isFailed(destination) {
+    return this.failed.has(destination);
+  }
+  /**
+   * Whether this destination is the one that must write the entry as raw NDJSON
+   * to stdout because NOTHING initialized.
+   *
+   * Exactly one failed destination can satisfy this, so N failed sinks rescue an
+   * entry once rather than N times.
+   *
+   * @param destination - The destination backing a fan-out stream.
+   * @returns `true` when no destination initialized and this one is the elected
+   *   rescuer.
+   */
+  shouldRescue(destination) {
+    return !this.hasHealthy && this.rescuer === destination;
+  }
+};
+DestinationHealth = __decorateClass([
+  Injectable()
+], DestinationHealth);
 var DestinationRegistry = class {
   /**
    * @param registered - Every destination declared under
    *   `LOGGER_DESTINATIONS_TOKEN`. Injected by token explicitly because the
    *   package is bundled without `emitDecoratorMetadata`.
-   * @param logger - Structured logger used to report init failures. Injected by
-   *   token explicitly for the same bundling reason.
+   * @param logger - Structured logger used for the bootstrap entries. Injected by
+   *   token explicitly for the same bundling reason. Deliberately NOT used to
+   *   report init failures — see the file-level note.
+   * @param options - Resolved module options, read for the bootstrap warnings and
+   *   for each destination's effective level.
+   * @param health - Init-health record shared with the write fan-out.
    */
-  constructor(registered, logger, options) {
+  constructor(registered, logger, options, health) {
     this.registered = registered;
     this.logger = logger;
     this.options = options;
+    this.health = health;
     /**
      * Destinations that initialized successfully, in registration order.
      *
-     * Note: the Pino multistream is built from the full registered list, and the
-     * write path is independently fail-soft (see `destinationToStream`). This set
-     * is the authoritative record of init success — it drives reverse-order
-     * shutdown — but is not currently used to remove a failed-init sink from the
-     * write fan-out; a sink that failed `onInit` still receives writes, contained
-     * fail-soft by the wrapper.
+     * Authoritative for BOTH shutdown (reverse order) and — via the shared
+     * `DestinationHealth` record written alongside it — the write fan-out. The two
+     * are kept in step here because the multistream itself is wired before any
+     * `onInit` runs and cannot be rebuilt afterwards; see `DestinationHealth`.
      */
     this.active = [];
   }
   /**
    * Initialize every registered destination. A destination whose `onInit`
-   * rejects is skipped (not added to the active set) and reported — it must not
-   * block application bootstrap.
+   * rejects is skipped (not added to the active set), marked failed so the
+   * fan-out stops writing to it, and reported to stderr — it must not block
+   * application bootstrap.
+   *
+   * The loop completes BEFORE {@link announceBootstrap}, and that ordering is
+   * load-bearing rather than incidental: the health record is what lets a
+   * last-resort sink carry the bootstrap entries when every destination failed.
+   * Announcing first would emit them into a fan-out that has not yet been told
+   * anything is wrong, and `LOGGER_BOOTSTRAP_WARNING` — the signal that exists so
+   * a security review can see PII redaction was disabled — would be lost exactly
+   * when the configuration is already known to be broken.
    */
   async onModuleInit() {
     for (const destination of this.registered) {
       try {
         await destination.onInit?.();
         this.active.push(destination);
+        this.health.markHealthy();
       } catch (cause) {
-        this.logger.errorStructured(
-          RESERVED_LOG_KEYS.LOGGER_DESTINATION_INIT_FAILED,
-          cause instanceof Error ? cause : new Error(String(cause)),
-          void 0,
-          { destination: destination.name }
-        );
+        this.health.markFailed(destination, destination.minLevel ?? this.options.level);
+        this.reportInitFailure(destination.name, cause);
       }
     }
     this.announceBootstrap();
   }
+  /**
+   * Report one destination init failure as a structured
+   * `LOGGER_DESTINATION_INIT_FAILED` line on `process.stderr`.
+   *
+   * Shares {@link reportDestinationFailure} with the write-failure path rather
+   * than restating the shape, so an operator greps one `logKey` regardless of
+   * which stage failed — and the two cannot drift apart.
+   *
+   * @param name - The failing destination's name.
+   * @param cause - The thrown or rejected value.
+   */
+  reportInitFailure(name, cause) {
+    reportDestinationFailure(
+      RESERVED_LOG_KEYS.LOGGER_DESTINATION_INIT_FAILED,
+      name,
+      cause,
+      `Log destination "${name}" failed to initialize and will receive no entries. If no destination initializes, entries fall back to raw NDJSON on stdout.`
+    );
+  }
   /**
    * Emit the one-shot bootstrap entries, AFTER every destination has been
    * initialized.
@@ -1634,7 +1768,8 @@ DestinationRegistry = __decorateClass([
   Injectable(),
   __decorateParam(0, Inject(LOGGER_DESTINATIONS_TOKEN)),
   __decorateParam(1, Inject(PinoLoggerService)),
-  __decorateParam(2, Inject(LOGGER_OPTIONS_TOKEN))
+  __decorateParam(2, Inject(LOGGER_OPTIONS_TOKEN)),
+  __decorateParam(3, Inject(DestinationHealth))
 ], DestinationRegistry);
 var FORBIDDEN_CONTEXT_KEYS = PROTOTYPE_POLLUTING_KEYS;
 var LogContextService = class {
@@ -1729,6 +1864,10 @@ function buildCommonProviders() {
   return [
     LogContextService,
     { provide: LOG_CONTEXT_TOKEN, useExisting: LogContextService },
+    // Shared by the Pino factory (which closes over it in every fan-out stream)
+    // and by DestinationRegistry (which writes to it during onModuleInit). Both
+    // depend on this provider and it depends on nothing, so there is no cycle.
+    DestinationHealth,
     {
       // The DEFAULT-coverage redactor, shared by the Pino factory's hooks and by
       // `PinoLoggerService.child()`. The latter needs it as a provider because
@@ -1739,8 +1878,13 @@ function buildCommonProviders() {
     },
     {
       provide: LOGGER_PINO_INSTANCE_TOKEN,
-      useFactory: (options, logContext, destinations) => buildPinoInstance(options, logContext, destinations),
-      inject: [LOGGER_OPTIONS_TOKEN, LogContextService, LOGGER_DESTINATIONS_TOKEN]
+      useFactory: (options, logContext, destinations, health) => buildPinoInstance(options, logContext, destinations, health),
+      inject: [
+        LOGGER_OPTIONS_TOKEN,
+        LogContextService,
+        LOGGER_DESTINATIONS_TOKEN,
+        DestinationHealth
+      ]
     },
     {
       provide: LOGGER_DESTINATIONS_TOKEN,
@@ -1931,8 +2075,10 @@ var PrettyDevDestination = class {
    *
    * Three states:
    *   - initialized → forward to the pino-pretty transform;
-   *   - init failed → DROP (the destination was removed from the active set, so
-   *     it must not duplicate raw NDJSON to stdout);
+   *   - init failed → DROP, so a co-registered stdout sink is not duplicated. The
+   *     fan-out already skips a failed destination before reaching this method
+   *     (and rescues the entry when nothing else initialized); this branch is the
+   *     belt to that, for any caller holding the destination directly;
    *   - pre-init (transient window before {@link onInit}, e.g. a bootstrap log)
    *     → fall back to raw stdout so the entry is not lost.
    *

package/dist/shared/index.d.cts

@@ -152,6 +152,17 @@ interface LogEntry {
     msg: string;
     /** Convention key — `MODULE_ACTION_RESULT` format. */
     logKey?: string;
+    /**
+     * OTel event name derived from {@link logKey} (`PAYMENT_FAILED` →
+     * `payment.failed`), emitted on structured calls unless `eventNameField` is
+     * `false`. Declared explicitly because the index signature below would type
+     * it `unknown`: a documented field a consumer cannot read without a cast is
+     * not really published.
+     *
+     * The key is configurable, so a renamed field arrives through the index
+     * signature instead — this declaration describes the default only.
+     */
+    'event.name'?: string;
     /**
      * Service identity as EMITTED — see {@link EmittedServiceResource}. Not the
      * configuration shape: `service.instance.id` nests, and the environment lives
@@ -258,4 +269,4 @@ declare const RESERVED_LOG_KEYS_NOT_EMITTED: Readonly<{
  */
 type ReservedLogKey = (typeof RESERVED_LOG_KEYS)[keyof typeof RESERVED_LOG_KEYS];
 
-export { LOG_KEYS_CONVENTION_REGEX, type LogEntry, type LogLevel, RESERVED_LOG_KEYS, RESERVED_LOG_KEYS_NOT_EMITTED, type ReservedLogKey, type ResolvedServiceMetadata, type ServiceMetadata };
+export { type EmittedDeploymentResource, type EmittedServiceResource, LOG_KEYS_CONVENTION_REGEX, type LogEntry, type LogLevel, RESERVED_LOG_KEYS, RESERVED_LOG_KEYS_NOT_EMITTED, type ReservedLogKey, type ResolvedServiceMetadata, type ServiceMetadata };

package/dist/shared/index.d.ts

@@ -152,6 +152,17 @@ interface LogEntry {
     msg: string;
     /** Convention key — `MODULE_ACTION_RESULT` format. */
     logKey?: string;
+    /**
+     * OTel event name derived from {@link logKey} (`PAYMENT_FAILED` →
+     * `payment.failed`), emitted on structured calls unless `eventNameField` is
+     * `false`. Declared explicitly because the index signature below would type
+     * it `unknown`: a documented field a consumer cannot read without a cast is
+     * not really published.
+     *
+     * The key is configurable, so a renamed field arrives through the index
+     * signature instead — this declaration describes the default only.
+     */
+    'event.name'?: string;
     /**
      * Service identity as EMITTED — see {@link EmittedServiceResource}. Not the
      * configuration shape: `service.instance.id` nests, and the environment lives
@@ -258,4 +269,4 @@ declare const RESERVED_LOG_KEYS_NOT_EMITTED: Readonly<{
  */
 type ReservedLogKey = (typeof RESERVED_LOG_KEYS)[keyof typeof RESERVED_LOG_KEYS];
 
-export { LOG_KEYS_CONVENTION_REGEX, type LogEntry, type LogLevel, RESERVED_LOG_KEYS, RESERVED_LOG_KEYS_NOT_EMITTED, type ReservedLogKey, type ResolvedServiceMetadata, type ServiceMetadata };
+export { type EmittedDeploymentResource, type EmittedServiceResource, LOG_KEYS_CONVENTION_REGEX, type LogEntry, type LogLevel, RESERVED_LOG_KEYS, RESERVED_LOG_KEYS_NOT_EMITTED, type ReservedLogKey, type ResolvedServiceMetadata, type ServiceMetadata };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bymax-one/nest-logger",
-  "version": "1.2.1",
+  "version": "1.2.3",
   "description": "Structured JSON logging for NestJS based on Pino 10, with optional OpenTelemetry correlation.",
   "author": "Bymax One <support@bymax.one>",
   "license": "MIT",
@@ -75,7 +75,7 @@
     "test:cov:all": "jest --config jest.coverage.config.ts --coverage",
     "test:e2e": "jest --config jest.e2e.config.ts",
     "test:watch": "jest --watch",
-    "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.server.json"
+    "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.server.json && tsc --noEmit -p tsconfig.bench.json"
   },
   "lint-staged": {
     "*.{ts,tsx,js,mjs,cjs}": [
@@ -86,7 +86,6 @@
       "prettier --write"
     ]
   },
-  "dependencies": {},
   "peerDependencies": {
     "@nestjs/common": "^11.0.16",
     "@nestjs/core": "^11.1.18",