@bymax-one/nest-logger 1.4.5 → 1.4.6

package/CHANGELOG.md

@@ -11,6 +11,63 @@ heading here.
 
 ## [Unreleased]
 
+## [1.4.6] - 2026-11-01
+
+### Fixed
+
+Five places swallowed a failed side effect with no trace. Each now leaves one.
+
+- **A destination failure whose cause cannot be read is no longer dropped.** When a sink's `onInit`,
+  `onRegistryReady` or `write` failed with a value that has no text form (a null-prototype object, a
+  throwing `toString`, an `Error` with throwing `name` or `message` getters), the `stderr` line was not
+  written at all and the sink stopped receiving entries unannounced. The line is now written with
+  `err: { type: 'UnknownError', message: 'unreadable value' }`.
+- **`PinoUnexpectedErrorSink` announces a report it had to drop.** When logging the report threw, or
+  the report could not be read, the `HTTP_UNEXPECTED_ERROR` entry, the only record of an unhandled
+  exception, vanished silently. One `HTTP_UNEXPECTED_ERROR_DROPPED` line now goes to `stderr`, outside
+  the sink set that may be what failed. The response is unaffected.
+- **`PrettyDevDestination` reports the real failure.** Every failure of `import('pino-pretty')` or of
+  `build()` was rethrown as "pino-pretty is not installed" with the original error discarded. Only a
+  failure to resolve `pino-pretty` itself keeps that message; anything else throws
+  `[PrettyDevDestination] pino-pretty failed to start: <message>`, and the original error is the
+  `cause` in both cases.
+- **An error node says when its own fields are missing.** When an error's own properties could not be
+  read (a Proxy whose `ownKeys` throws, a getter that throws), none was copied and nothing said so. The
+  node now carries `_errorFieldsIncomplete: true`.
+- **A broken `@opentelemetry/api` install is reported once.** Every failure to load it was folded into
+  "not installed", so correlation could be off with no sign. A missing module stays silent, as
+  designed; one that is installed but throws while loading, or exports no usable `trace` namespace, writes one
+  `LOGGER_OTEL_API_BROKEN` line to `stderr`.
+
+#### Apply to a derived backend
+
+Nothing to change in code. What can differ at run time:
+
+- `stderr` can carry two lines it never carried: `HTTP_UNEXPECTED_ERROR_DROPPED` and
+  `LOGGER_OTEL_API_BROKEN`, both NDJSON like the destination-failure lines. Add them to whatever
+  alerts on the library's `stderr` codes. `RESERVED_LOG_KEYS` gains these two keys, so an application
+  event must not reuse them.
+- A host that already logs an event under `HTTP_UNEXPECTED_ERROR_DROPPED` or `LOGGER_OTEL_API_BROKEN`
+  sees no change in that entry: nothing is renamed, rejected or dropped, and its `event.name` is
+  derived from the key as for any other (`http.unexpected.error.dropped`, `logger.otel.api.broken`).
+  What changes is that, where stdout and stderr reach the same place, an alert or filter on either
+  key now matches the library's `stderr` line and the host's own entries alike. Rename the host event.
+- `LOGGER_DESTINATION_INIT_FAILED`, `LOGGER_DESTINATION_WRITE_FAILED` and the hook-failure line now
+  appear for failures that were silent before. A deployment that saw none was either healthy or
+  losing entries without knowing.
+- Code that matches the text "pino-pretty is not installed" on a `PrettyDevDestination` init error now
+  matches only a genuine resolution failure; match `failed to start` for the rest, or read `cause`.
+- Log processing that reads error nodes can meet `_errorFieldsIncomplete: true`, on an error whose own
+  fields could not be read.
+
+### Tests
+
+- A failure whose cause cannot be read, a dropped unexpected-error report, a `pino-pretty` failure of
+  each kind, an error whose own fields cannot be enumerated and a broken `@opentelemetry/api` each have
+  a failing-first spec. The fixtures that simulated a missing `pino-pretty` or `@opentelemetry/api` now
+  carry the resolution code Node attaches to the real error, because the code is what tells an absent
+  module from a broken one.
+
 ## [1.4.5] - 2026-11-01
 
 ### Documentation
@@ -2219,7 +2276,8 @@ 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.4.5...HEAD
+[Unreleased]: https://github.com/bymaxone/nest-logger/compare/v1.4.6...HEAD
+[1.4.6]: https://github.com/bymaxone/nest-logger/compare/v1.4.5...v1.4.6
 [1.4.5]: https://github.com/bymaxone/nest-logger/compare/v1.4.4...v1.4.5
 [1.4.4]: https://github.com/bymaxone/nest-logger/compare/v1.4.3...v1.4.4
 [1.4.3]: https://github.com/bymaxone/nest-logger/compare/v1.4.2...v1.4.3

package/README.md

@@ -179,7 +179,7 @@ pnpm add @opentelemetry/api @opentelemetry/sdk-node
 > packaging.
 
 > [!NOTE]
-> `@opentelemetry/api` is resolved lazily when the Pino instance is built. When it is absent the trace mixin silently steps aside — the logger never fails to start, and never warns, over an optional peer.
+> `@opentelemetry/api` is resolved lazily when the Pino instance is built. When it is absent the trace mixin silently steps aside — the logger never fails to start, and never warns, over an optional peer. A copy that is installed but broken is different: it is reported once on `stderr` as `LOGGER_OTEL_API_BROKEN`, because correlation would otherwise be off with no sign.
 
 > [!NOTE]
 > The published declarations depend on no HTTP framework's types. The HTTP interceptor, the exception filter and the request-id middleware are typed by structural contracts (`LoggableRequest`, `LoggableResponse`, `NextHandler`) that an Express request and response satisfy as-is, so nothing extra is needed even when you compile with `skipLibCheck: false`. The emitted `.d.ts` imports only `@nestjs/common`, `pino` and `rxjs`.
@@ -727,6 +727,8 @@ any other serializer output.
 An error's own enumerable properties (`code`, `statusCode`, domain fields) are carried through, as
 Pino's standard serializer did.
 
+When those properties cannot be read (a Proxy whose `ownKeys` throws, or a getter that throws), none of them is copied and the error node carries `_errorFieldsIncomplete: true`, so an entry without its `code` is never mistaken for a complete one.
+
 ### 7. Context propagation with `LogContextService`
 
 ```typescript
@@ -843,7 +845,7 @@ function assertValidLogKey(key: string) {
 
 The following keys are used internally by the library — do not reuse them in application code:
 
-`LOGGER_BOOTSTRAP_OK` · `LOGGER_BOOTSTRAP_WARNING` · `LOGGER_SHUTDOWN_OK` · `HTTP_REQUEST_START` · `HTTP_REQUEST_SUCCESS` · `HTTP_REQUEST_REDIRECT` · `HTTP_REQUEST_CLIENT_ERROR` · `HTTP_REQUEST_SERVER_ERROR` · `HTTP_REQUEST_ABORTED` · `HTTP_REQUEST_COMPLETED` · `HTTP_EXCEPTION_HANDLED` · `HTTP_EXCEPTION_UNHANDLED` · `HTTP_UNEXPECTED_ERROR` · `METHOD_EXECUTION` · `METHOD_SLOW_EXECUTION` · `LOGGER_DESTINATION_INIT_FAILED` · `LOGGER_DESTINATION_WRITE_FAILED` · `LOGGER_ENTRY_TRUNCATED` · `LOGGER_REDACTION_FAILED`
+`LOGGER_BOOTSTRAP_OK` · `LOGGER_BOOTSTRAP_WARNING` · `LOGGER_SHUTDOWN_OK` · `HTTP_REQUEST_START` · `HTTP_REQUEST_SUCCESS` · `HTTP_REQUEST_REDIRECT` · `HTTP_REQUEST_CLIENT_ERROR` · `HTTP_REQUEST_SERVER_ERROR` · `HTTP_REQUEST_ABORTED` · `HTTP_REQUEST_COMPLETED` · `HTTP_EXCEPTION_HANDLED` · `HTTP_EXCEPTION_UNHANDLED` · `HTTP_UNEXPECTED_ERROR` · `HTTP_UNEXPECTED_ERROR_DROPPED` · `METHOD_EXECUTION` · `METHOD_SLOW_EXECUTION` · `LOGGER_DESTINATION_INIT_FAILED` · `LOGGER_DESTINATION_WRITE_FAILED` · `LOGGER_ENTRY_TRUNCATED` · `LOGGER_REDACTION_FAILED` · `LOGGER_OTEL_API_BROKEN`
 
 All reserved keys are exported as the `RESERVED_LOG_KEYS` constant from `@bymax-one/nest-logger/shared`.
 
@@ -1579,22 +1581,25 @@ Two kinds of failure, and they surface differently. A **thrown `Error`** carries
 | `[BymaxLoggerModule] options.`                           | `forRoot` / `forRootAsync`, at module setup | any option fails validation: a missing `service`, a `level` outside the set, a bad type | Fix the option the message names; it prints the path and what it received |
 | `[BymaxLoggerModule] useNestLogger(app) called but`      | `BymaxLoggerModule.useNestLogger`           | the module was never imported into the application                                      | Import `BymaxLoggerModule` before calling it                              |
 | `[BymaxLoggerModule] applyAccessLog(app) called but`     | `applyAccessLog`                            | the module was never imported into the application                                      | Import `BymaxLoggerModule` before calling it                              |
-| `[PrettyDevDestination] pino-pretty is not installed`    | `PrettyDevDestination.onInit`               | the destination is registered and the optional peer is missing                          | Install `pino-pretty` or drop the destination                             |
+| `[PrettyDevDestination] pino-pretty is not installed`    | `PrettyDevDestination.onInit`               | the destination is registered and resolving `pino-pretty` itself fails                  | Install `pino-pretty` or drop the destination                             |
+| `[PrettyDevDestination] pino-pretty failed to start`     | `PrettyDevDestination.onInit`               | `pino-pretty` is found but importing it or building the transform throws                | Read the message and the error's `cause`: it is the real failure          |
 | `[PrettyDevDestination] refused in production`           | `PrettyDevDestination.onInit`               | `NODE_ENV` is exactly `production`                                                      | Use `DefaultStdoutDestination` in production                              |
 | `[LogContextService] set() called outside run() scope`   | `LogContextService.set`                     | called with no active `run()`                                                           | Wrap the work in `logContext.run({ ... }, () => ...)`                     |
 | `[LogContextService] Refusing to set unsafe context key` | `LogContextService.set`                     | the key is `__proto__`, `constructor` or `prototype`                                    | Use an ordinary key                                                       |
 
-The two `PrettyDevDestination` errors are thrown inside `onInit`, which the registry contains: the boot continues and the failure is reported as `LOGGER_DESTINATION_INIT_FAILED` below.
+The `PrettyDevDestination` errors are thrown inside `onInit`, which the registry contains: the boot continues and the failure is reported as `LOGGER_DESTINATION_INIT_FAILED` below.
 
 ### Log keys
 
-| Code                              | Surfaces as                                              | When                                                                                  | Action                                                                                                                      |
-| --------------------------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
-| `LOGGER_DESTINATION_INIT_FAILED`  | NDJSON line on `stderr`                                  | `destination.onInit()` throws or rejects                                              | Sink is removed from the write fan-out and shutdown; boot continues                                                         |
-| `LOGGER_DESTINATION_WRITE_FAILED` | NDJSON line on `stderr`                                  | `destination.write()` throws or rejects                                               | Entry dropped for that destination; others continue                                                                         |
-| `LOGGER_BOOTSTRAP_WARNING`        | log entry with `reason: 'OTEL_API_UNAVAILABLE'`          | `otel.shouldAutoInjectTraceContext` is on and `@opentelemetry/api` cannot be resolved | Install `@opentelemetry/api`, or turn the option off; until then `traceId` and `spanId` are absent                          |
-| `LOGGER_ENTRY_TRUNCATED`          | `_logKey` in the envelope                                | a serialized field exceeds `maxEntrySizeBytes`                                        | Reduce the payload or raise the ceiling                                                                                     |
-| `LOGGER_REDACTION_FAILED`         | `_logKey` in the envelope, with `_redactionFailed: true` | a record cannot be walked by the redactor (a throwing getter, a hostile proxy)        | The record is dropped whole, never partly emitted; the message and ambient context stay. Find the value that broke the walk |
+| Code                              | Surfaces as                                              | When                                                                                                 | Action                                                                                                                      |
+| --------------------------------- | -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| `LOGGER_DESTINATION_INIT_FAILED`  | NDJSON line on `stderr`                                  | `destination.onInit()` throws or rejects                                                             | Sink is removed from the write fan-out and shutdown; boot continues                                                         |
+| `LOGGER_DESTINATION_WRITE_FAILED` | NDJSON line on `stderr`                                  | `destination.write()` throws or rejects                                                              | Entry dropped for that destination; others continue                                                                         |
+| `HTTP_UNEXPECTED_ERROR_DROPPED`   | NDJSON line on `stderr`                                  | `PinoUnexpectedErrorSink` could not log a report (the logger threw, or the report could not be read) | The report is dropped; the line names why. The response is unaffected                                                       |
+| `LOGGER_OTEL_API_BROKEN`          | NDJSON line on `stderr`, once                            | `@opentelemetry/api` is installed but throws while loading, or exports no usable `trace` namespace   | Reinstall it, or turn `otel.shouldAutoInjectTraceContext` off; until then `traceId` and `spanId` are absent                 |
+| `LOGGER_BOOTSTRAP_WARNING`        | log entry with `reason: 'OTEL_API_UNAVAILABLE'`          | `otel.shouldAutoInjectTraceContext` is on and `@opentelemetry/api` cannot be resolved                | Install `@opentelemetry/api`, or turn the option off; until then `traceId` and `spanId` are absent                          |
+| `LOGGER_ENTRY_TRUNCATED`          | `_logKey` in the envelope                                | a serialized field exceeds `maxEntrySizeBytes`                                                       | Reduce the payload or raise the ceiling                                                                                     |
+| `LOGGER_REDACTION_FAILED`         | `_logKey` in the envelope, with `_redactionFailed: true` | a record cannot be walked by the redactor (a throwing getter, a hostile proxy)                       | The record is dropped whole, never partly emitted; the message and ambient context stay. Find the value that broke the walk |
 
 ---
 

package/dist/server/index.cjs

@@ -325,12 +325,14 @@ var RESERVED_LOG_KEYS = Object.freeze({
   HTTP_EXCEPTION_HANDLED: "HTTP_EXCEPTION_HANDLED",
   HTTP_EXCEPTION_UNHANDLED: "HTTP_EXCEPTION_UNHANDLED",
   HTTP_UNEXPECTED_ERROR: "HTTP_UNEXPECTED_ERROR",
+  HTTP_UNEXPECTED_ERROR_DROPPED: "HTTP_UNEXPECTED_ERROR_DROPPED",
   METHOD_EXECUTION: "METHOD_EXECUTION",
   METHOD_SLOW_EXECUTION: "METHOD_SLOW_EXECUTION",
   LOGGER_DESTINATION_INIT_FAILED: "LOGGER_DESTINATION_INIT_FAILED",
   LOGGER_DESTINATION_WRITE_FAILED: "LOGGER_DESTINATION_WRITE_FAILED",
   LOGGER_ENTRY_TRUNCATED: "LOGGER_ENTRY_TRUNCATED",
-  LOGGER_REDACTION_FAILED: "LOGGER_REDACTION_FAILED"
+  LOGGER_REDACTION_FAILED: "LOGGER_REDACTION_FAILED",
+  LOGGER_OTEL_API_BROKEN: "LOGGER_OTEL_API_BROKEN"
 });
 var RESERVED_LOG_KEYS_NOT_EMITTED = Object.freeze({
   /**
@@ -429,6 +431,7 @@ function assignOwnErrorFields(target, source) {
       }
     }
   } catch {
+    Reflect.defineProperty(target, "_errorFieldsIncomplete", { value: true, enumerable: true });
   }
 }
 function toSanitizedChild(value, seen, depth2, maxDepth) {
@@ -1210,17 +1213,114 @@ var DEFAULT_REDACT_PATHS = [
   ...REDACT_COMMON_FIELDS.flatMap((field) => depth(field)),
   ...REDACT_ABSOLUTE_PATHS
 ];
+
+// src/server/utils/report-destination-failure.util.ts
+function reportDestinationFailure(logKey, name, cause, msg) {
+  writeStderrSafely(
+    JSON.stringify({
+      level: "error",
+      logKey,
+      destination: toSingleLineMessage(name),
+      err: describeCause(cause),
+      msg: toSingleLineMessage(msg)
+    }) + "\n"
+  );
+}
+var UNREADABLE_CAUSE = { type: "UnknownError", message: "unreadable value" };
+function describeCause(cause) {
+  try {
+    return cause instanceof Error ? {
+      type: toSingleLineMessage(String(cause.name)),
+      message: toSingleLineMessage(String(cause.message))
+    } : { type: "UnknownError", message: toSingleLineMessage(String(cause)) };
+  } catch {
+    return UNREADABLE_CAUSE;
+  }
+}
+function safeDestinationName(destination) {
+  try {
+    return String(destination.name);
+  } catch {
+    return "unknown";
+  }
+}
+function isLogLevel(value) {
+  return LOG_LEVEL_PRIORITY.includes(value);
+}
+var resolvedMinLevels = /* @__PURE__ */ new WeakMap();
+function safeMinLevel(destination) {
+  if (resolvedMinLevels.has(destination)) {
+    return resolvedMinLevels.get(destination);
+  }
+  let resolved;
+  try {
+    const read = destination.minLevel;
+    resolved = isLogLevel(read) ? read : void 0;
+  } catch {
+  }
+  resolvedMinLevels.set(destination, resolved);
+  return resolved;
+}
+
+// src/server/utils/otel-detector.ts
+var brokenInstallWarned = false;
+function isOtelApiMissing(cause) {
+  try {
+    const { code, message } = cause;
+    return code === "MODULE_NOT_FOUND" && /^Cannot find module '@opentelemetry\/api'/.test(String(message));
+  } catch {
+    return false;
+  }
+}
 function loadTraceApiFrom(anchor) {
+  let from;
   try {
-    const requireFrom = module$1.createRequire(anchor());
-    const mod = requireFrom("@opentelemetry/api");
-    return mod.trace;
+    from = anchor();
   } catch {
-    return void 0;
+    return { api: void 0 };
+  }
+  try {
+    const mod = module$1.createRequire(from)("@opentelemetry/api");
+    const trace = typeof mod === "object" && mod !== null || typeof mod === "function" ? mod.trace : void 0;
+    if (typeof trace?.getActiveSpan !== "function") {
+      throw new TypeError("@opentelemetry/api resolved but exports no usable `trace` namespace");
+    }
+    return { api: trace };
+  } catch (cause) {
+    return isOtelApiMissing(cause) ? { api: void 0 } : { api: void 0, broken: { cause } };
   }
 }
-function detectOtelTraceApi() {
-  return loadTraceApiFrom(() => __filename) ?? loadTraceApiFrom(() => path.join(process.cwd(), "noop.cjs"));
+function warnBrokenInstallOnce(cause) {
+  if (brokenInstallWarned) {
+    return;
+  }
+  brokenInstallWarned = true;
+  writeStderrSafely(
+    JSON.stringify({
+      level: "warn",
+      logKey: RESERVED_LOG_KEYS.LOGGER_OTEL_API_BROKEN,
+      msg: "@opentelemetry/api is installed but could not be loaded, so traceId and spanId are absent from every entry. Reinstall it, or set otel.shouldAutoInjectTraceContext to false.",
+      err: describeCause(cause)
+    }) + "\n"
+  );
+}
+var DEFAULT_ANCHORS = [
+  () => __filename,
+  () => path.join(process.cwd(), "noop.cjs")
+];
+function detectOtelTraceApi(anchors = DEFAULT_ANCHORS) {
+  let broken;
+  for (const anchor of anchors) {
+    const attempt = loadTraceApiFrom(anchor);
+    if (attempt.api !== void 0) {
+      return attempt.api;
+    }
+    broken ??= attempt.broken;
+  }
+  if (broken !== void 0) {
+    warnBrokenInstallOnce(broken.cause);
+  }
+  return void 0;
 }
 function isValidTraceId(traceId) {
   return /^[0-9a-f]{32}$/.test(traceId) && !/^0+$/.test(traceId);
@@ -1239,17 +1339,21 @@ function createTraceContextMixin(logContext, opts) {
       Object.assign(merged, store);
     }
     if (traceApi) {
-      const span = traceApi.getActiveSpan();
-      if (span) {
-        const ctx = span.spanContext();
-        if (isValidTraceId(ctx.traceId) && isValidSpanId(ctx.spanId)) {
-          Reflect.set(merged, opts.traceIdField, ctx.traceId);
-          Reflect.set(merged, opts.spanIdField, ctx.spanId);
-          if (typeof ctx.traceFlags === "number") {
-            const flagsByte = ctx.traceFlags & 255;
-            Reflect.set(merged, opts.traceFlagsField, flagsByte.toString(16).padStart(2, "0"));
+      try {
+        const span = traceApi.getActiveSpan();
+        if (span) {
+          const { traceId, spanId, traceFlags } = span.spanContext();
+          if (isValidTraceId(traceId) && isValidSpanId(spanId)) {
+            const flags = typeof traceFlags === "number" ? (traceFlags & 255).toString(16).padStart(2, "0") : void 0;
+            Reflect.set(merged, opts.traceIdField, traceId);
+            Reflect.set(merged, opts.spanIdField, spanId);
+            if (flags !== void 0) {
+              Reflect.set(merged, opts.traceFlagsField, flags);
+            }
           }
         }
+      } catch (cause) {
+        warnBrokenInstallOnce(cause);
       }
     }
     return merged;
@@ -1261,52 +1365,6 @@ function compileRedactPaths(extraPaths, shouldSkipDefaults) {
   const sources = shouldSkipDefaults ? [extraPaths] : [DEFAULT_REDACT_PATHS, extraPaths];
   return Array.from(new Set(sources.flat()));
 }
-
-// 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)) };
-    writeStderrSafely(
-      JSON.stringify({
-        level: "error",
-        logKey,
-        destination: toSingleLineMessage(name),
-        err,
-        msg: toSingleLineMessage(msg)
-      }) + "\n"
-    );
-  } catch {
-  }
-}
-function safeDestinationName(destination) {
-  try {
-    return String(destination.name);
-  } catch {
-    return "unknown";
-  }
-}
-function isLogLevel(value) {
-  return LOG_LEVEL_PRIORITY.includes(value);
-}
-var resolvedMinLevels = /* @__PURE__ */ new WeakMap();
-function safeMinLevel(destination) {
-  if (resolvedMinLevels.has(destination)) {
-    return resolvedMinLevels.get(destination);
-  }
-  let resolved;
-  try {
-    const read = destination.minLevel;
-    resolved = isLogLevel(read) ? read : void 0;
-  } catch {
-  }
-  resolvedMinLevels.set(destination, resolved);
-  return resolved;
-}
-
-// src/server/utils/destination-to-stream.ts
 function reportWriteFailure(destination, cause) {
   const name = safeDestinationName(destination);
   reportDestinationFailure(
@@ -2562,6 +2620,22 @@ var MAX_BUFFERED_BYTES = 4 * 1024 * 1024;
 function writeRawToStdout(payload) {
   writeStdoutSafely(payload);
 }
+var RESOLUTION_FAILURE_CODES = ["MODULE_NOT_FOUND", "ERR_MODULE_NOT_FOUND"];
+function isPinoPrettyMissing(cause) {
+  try {
+    const { code, message } = cause;
+    return RESOLUTION_FAILURE_CODES.includes(code) && /^Cannot find (?:module|package) 'pino-pretty'/.test(String(message));
+  } catch {
+    return false;
+  }
+}
+function describeFailure(cause) {
+  try {
+    return toSingleLineMessage(cause instanceof Error ? cause.message : String(cause));
+  } catch {
+    return "unreadable value";
+  }
+}
 var PrettyDevDestination = class {
   /**
    * @param opts.minLevel — Optional minimum level filter applied by the
@@ -2634,10 +2708,11 @@ var PrettyDevDestination = class {
         // and the last-resort rescue.
         destination: process.stdout
       });
-    } catch {
+    } catch (cause) {
       this.initFailed = true;
       throw new Error(
-        "[PrettyDevDestination] pino-pretty is not installed. Install it as a peer dependency (`pnpm add -D pino-pretty`) or remove PrettyDevDestination from `destinations`."
+        isPinoPrettyMissing(cause) ? "[PrettyDevDestination] pino-pretty is not installed. Install it as a peer dependency (`pnpm add -D pino-pretty`) or remove PrettyDevDestination from `destinations`." : `[PrettyDevDestination] pino-pretty failed to start: ${describeFailure(cause)}`,
+        { cause }
       );
     }
     this.flushBuffer((payload) => {
@@ -3102,7 +3177,13 @@ exports.PinoUnexpectedErrorSink = class PinoUnexpectedErrorSink {
         void 0,
         metadata
       );
-    } catch {
+    } catch (cause) {
+      reportDestinationFailure(
+        RESERVED_LOG_KEYS.HTTP_UNEXPECTED_ERROR_DROPPED,
+        "PinoUnexpectedErrorSink",
+        cause,
+        "An unexpected-error report could not be logged and was dropped."
+      );
     }
   }
 };

package/dist/server/index.d.cts

@@ -585,12 +585,14 @@ declare const RESERVED_LOG_KEYS: Readonly<{
     readonly HTTP_EXCEPTION_HANDLED: "HTTP_EXCEPTION_HANDLED";
     readonly HTTP_EXCEPTION_UNHANDLED: "HTTP_EXCEPTION_UNHANDLED";
     readonly HTTP_UNEXPECTED_ERROR: "HTTP_UNEXPECTED_ERROR";
+    readonly HTTP_UNEXPECTED_ERROR_DROPPED: "HTTP_UNEXPECTED_ERROR_DROPPED";
     readonly METHOD_EXECUTION: "METHOD_EXECUTION";
     readonly METHOD_SLOW_EXECUTION: "METHOD_SLOW_EXECUTION";
     readonly LOGGER_DESTINATION_INIT_FAILED: "LOGGER_DESTINATION_INIT_FAILED";
     readonly LOGGER_DESTINATION_WRITE_FAILED: "LOGGER_DESTINATION_WRITE_FAILED";
     readonly LOGGER_ENTRY_TRUNCATED: "LOGGER_ENTRY_TRUNCATED";
     readonly LOGGER_REDACTION_FAILED: "LOGGER_REDACTION_FAILED";
+    readonly LOGGER_OTEL_API_BROKEN: "LOGGER_OTEL_API_BROKEN";
 }>;
 /**
  * Keys that are reserved but intentionally never emitted, each with the reason.

package/dist/server/index.d.ts

@@ -585,12 +585,14 @@ declare const RESERVED_LOG_KEYS: Readonly<{
     readonly HTTP_EXCEPTION_HANDLED: "HTTP_EXCEPTION_HANDLED";
     readonly HTTP_EXCEPTION_UNHANDLED: "HTTP_EXCEPTION_UNHANDLED";
     readonly HTTP_UNEXPECTED_ERROR: "HTTP_UNEXPECTED_ERROR";
+    readonly HTTP_UNEXPECTED_ERROR_DROPPED: "HTTP_UNEXPECTED_ERROR_DROPPED";
     readonly METHOD_EXECUTION: "METHOD_EXECUTION";
     readonly METHOD_SLOW_EXECUTION: "METHOD_SLOW_EXECUTION";
     readonly LOGGER_DESTINATION_INIT_FAILED: "LOGGER_DESTINATION_INIT_FAILED";
     readonly LOGGER_DESTINATION_WRITE_FAILED: "LOGGER_DESTINATION_WRITE_FAILED";
     readonly LOGGER_ENTRY_TRUNCATED: "LOGGER_ENTRY_TRUNCATED";
     readonly LOGGER_REDACTION_FAILED: "LOGGER_REDACTION_FAILED";
+    readonly LOGGER_OTEL_API_BROKEN: "LOGGER_OTEL_API_BROKEN";
 }>;
 /**
  * Keys that are reserved but intentionally never emitted, each with the reason.

package/dist/server/index.mjs

@@ -322,12 +322,14 @@ var RESERVED_LOG_KEYS = Object.freeze({
   HTTP_EXCEPTION_HANDLED: "HTTP_EXCEPTION_HANDLED",
   HTTP_EXCEPTION_UNHANDLED: "HTTP_EXCEPTION_UNHANDLED",
   HTTP_UNEXPECTED_ERROR: "HTTP_UNEXPECTED_ERROR",
+  HTTP_UNEXPECTED_ERROR_DROPPED: "HTTP_UNEXPECTED_ERROR_DROPPED",
   METHOD_EXECUTION: "METHOD_EXECUTION",
   METHOD_SLOW_EXECUTION: "METHOD_SLOW_EXECUTION",
   LOGGER_DESTINATION_INIT_FAILED: "LOGGER_DESTINATION_INIT_FAILED",
   LOGGER_DESTINATION_WRITE_FAILED: "LOGGER_DESTINATION_WRITE_FAILED",
   LOGGER_ENTRY_TRUNCATED: "LOGGER_ENTRY_TRUNCATED",
-  LOGGER_REDACTION_FAILED: "LOGGER_REDACTION_FAILED"
+  LOGGER_REDACTION_FAILED: "LOGGER_REDACTION_FAILED",
+  LOGGER_OTEL_API_BROKEN: "LOGGER_OTEL_API_BROKEN"
 });
 var RESERVED_LOG_KEYS_NOT_EMITTED = Object.freeze({
   /**
@@ -426,6 +428,7 @@ function assignOwnErrorFields(target, source) {
       }
     }
   } catch {
+    Reflect.defineProperty(target, "_errorFieldsIncomplete", { value: true, enumerable: true });
   }
 }
 function toSanitizedChild(value, seen, depth2, maxDepth) {
@@ -1207,17 +1210,114 @@ var DEFAULT_REDACT_PATHS = [
   ...REDACT_COMMON_FIELDS.flatMap((field) => depth(field)),
   ...REDACT_ABSOLUTE_PATHS
 ];
+
+// src/server/utils/report-destination-failure.util.ts
+function reportDestinationFailure(logKey, name, cause, msg) {
+  writeStderrSafely(
+    JSON.stringify({
+      level: "error",
+      logKey,
+      destination: toSingleLineMessage(name),
+      err: describeCause(cause),
+      msg: toSingleLineMessage(msg)
+    }) + "\n"
+  );
+}
+var UNREADABLE_CAUSE = { type: "UnknownError", message: "unreadable value" };
+function describeCause(cause) {
+  try {
+    return cause instanceof Error ? {
+      type: toSingleLineMessage(String(cause.name)),
+      message: toSingleLineMessage(String(cause.message))
+    } : { type: "UnknownError", message: toSingleLineMessage(String(cause)) };
+  } catch {
+    return UNREADABLE_CAUSE;
+  }
+}
+function safeDestinationName(destination) {
+  try {
+    return String(destination.name);
+  } catch {
+    return "unknown";
+  }
+}
+function isLogLevel(value) {
+  return LOG_LEVEL_PRIORITY.includes(value);
+}
+var resolvedMinLevels = /* @__PURE__ */ new WeakMap();
+function safeMinLevel(destination) {
+  if (resolvedMinLevels.has(destination)) {
+    return resolvedMinLevels.get(destination);
+  }
+  let resolved;
+  try {
+    const read = destination.minLevel;
+    resolved = isLogLevel(read) ? read : void 0;
+  } catch {
+  }
+  resolvedMinLevels.set(destination, resolved);
+  return resolved;
+}
+
+// src/server/utils/otel-detector.ts
+var brokenInstallWarned = false;
+function isOtelApiMissing(cause) {
+  try {
+    const { code, message } = cause;
+    return code === "MODULE_NOT_FOUND" && /^Cannot find module '@opentelemetry\/api'/.test(String(message));
+  } catch {
+    return false;
+  }
+}
 function loadTraceApiFrom(anchor) {
+  let from;
   try {
-    const requireFrom = createRequire(anchor());
-    const mod = requireFrom("@opentelemetry/api");
-    return mod.trace;
+    from = anchor();
   } catch {
-    return void 0;
+    return { api: void 0 };
+  }
+  try {
+    const mod = createRequire(from)("@opentelemetry/api");
+    const trace = typeof mod === "object" && mod !== null || typeof mod === "function" ? mod.trace : void 0;
+    if (typeof trace?.getActiveSpan !== "function") {
+      throw new TypeError("@opentelemetry/api resolved but exports no usable `trace` namespace");
+    }
+    return { api: trace };
+  } catch (cause) {
+    return isOtelApiMissing(cause) ? { api: void 0 } : { api: void 0, broken: { cause } };
   }
 }
-function detectOtelTraceApi() {
-  return loadTraceApiFrom(() => __filename$1) ?? loadTraceApiFrom(() => join(process.cwd(), "noop.cjs"));
+function warnBrokenInstallOnce(cause) {
+  if (brokenInstallWarned) {
+    return;
+  }
+  brokenInstallWarned = true;
+  writeStderrSafely(
+    JSON.stringify({
+      level: "warn",
+      logKey: RESERVED_LOG_KEYS.LOGGER_OTEL_API_BROKEN,
+      msg: "@opentelemetry/api is installed but could not be loaded, so traceId and spanId are absent from every entry. Reinstall it, or set otel.shouldAutoInjectTraceContext to false.",
+      err: describeCause(cause)
+    }) + "\n"
+  );
+}
+var DEFAULT_ANCHORS = [
+  () => __filename$1,
+  () => join(process.cwd(), "noop.cjs")
+];
+function detectOtelTraceApi(anchors = DEFAULT_ANCHORS) {
+  let broken;
+  for (const anchor of anchors) {
+    const attempt = loadTraceApiFrom(anchor);
+    if (attempt.api !== void 0) {
+      return attempt.api;
+    }
+    broken ??= attempt.broken;
+  }
+  if (broken !== void 0) {
+    warnBrokenInstallOnce(broken.cause);
+  }
+  return void 0;
 }
 function isValidTraceId(traceId) {
   return /^[0-9a-f]{32}$/.test(traceId) && !/^0+$/.test(traceId);
@@ -1236,17 +1336,21 @@ function createTraceContextMixin(logContext, opts) {
       Object.assign(merged, store);
     }
     if (traceApi) {
-      const span = traceApi.getActiveSpan();
-      if (span) {
-        const ctx = span.spanContext();
-        if (isValidTraceId(ctx.traceId) && isValidSpanId(ctx.spanId)) {
-          Reflect.set(merged, opts.traceIdField, ctx.traceId);
-          Reflect.set(merged, opts.spanIdField, ctx.spanId);
-          if (typeof ctx.traceFlags === "number") {
-            const flagsByte = ctx.traceFlags & 255;
-            Reflect.set(merged, opts.traceFlagsField, flagsByte.toString(16).padStart(2, "0"));
+      try {
+        const span = traceApi.getActiveSpan();
+        if (span) {
+          const { traceId, spanId, traceFlags } = span.spanContext();
+          if (isValidTraceId(traceId) && isValidSpanId(spanId)) {
+            const flags = typeof traceFlags === "number" ? (traceFlags & 255).toString(16).padStart(2, "0") : void 0;
+            Reflect.set(merged, opts.traceIdField, traceId);
+            Reflect.set(merged, opts.spanIdField, spanId);
+            if (flags !== void 0) {
+              Reflect.set(merged, opts.traceFlagsField, flags);
+            }
           }
         }
+      } catch (cause) {
+        warnBrokenInstallOnce(cause);
       }
     }
     return merged;
@@ -1258,52 +1362,6 @@ function compileRedactPaths(extraPaths, shouldSkipDefaults) {
   const sources = shouldSkipDefaults ? [extraPaths] : [DEFAULT_REDACT_PATHS, extraPaths];
   return Array.from(new Set(sources.flat()));
 }
-
-// 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)) };
-    writeStderrSafely(
-      JSON.stringify({
-        level: "error",
-        logKey,
-        destination: toSingleLineMessage(name),
-        err,
-        msg: toSingleLineMessage(msg)
-      }) + "\n"
-    );
-  } catch {
-  }
-}
-function safeDestinationName(destination) {
-  try {
-    return String(destination.name);
-  } catch {
-    return "unknown";
-  }
-}
-function isLogLevel(value) {
-  return LOG_LEVEL_PRIORITY.includes(value);
-}
-var resolvedMinLevels = /* @__PURE__ */ new WeakMap();
-function safeMinLevel(destination) {
-  if (resolvedMinLevels.has(destination)) {
-    return resolvedMinLevels.get(destination);
-  }
-  let resolved;
-  try {
-    const read = destination.minLevel;
-    resolved = isLogLevel(read) ? read : void 0;
-  } catch {
-  }
-  resolvedMinLevels.set(destination, resolved);
-  return resolved;
-}
-
-// src/server/utils/destination-to-stream.ts
 function reportWriteFailure(destination, cause) {
   const name = safeDestinationName(destination);
   reportDestinationFailure(
@@ -2559,6 +2617,22 @@ var MAX_BUFFERED_BYTES = 4 * 1024 * 1024;
 function writeRawToStdout(payload) {
   writeStdoutSafely(payload);
 }
+var RESOLUTION_FAILURE_CODES = ["MODULE_NOT_FOUND", "ERR_MODULE_NOT_FOUND"];
+function isPinoPrettyMissing(cause) {
+  try {
+    const { code, message } = cause;
+    return RESOLUTION_FAILURE_CODES.includes(code) && /^Cannot find (?:module|package) 'pino-pretty'/.test(String(message));
+  } catch {
+    return false;
+  }
+}
+function describeFailure(cause) {
+  try {
+    return toSingleLineMessage(cause instanceof Error ? cause.message : String(cause));
+  } catch {
+    return "unreadable value";
+  }
+}
 var PrettyDevDestination = class {
   /**
    * @param opts.minLevel — Optional minimum level filter applied by the
@@ -2631,10 +2705,11 @@ var PrettyDevDestination = class {
         // and the last-resort rescue.
         destination: process.stdout
       });
-    } catch {
+    } catch (cause) {
       this.initFailed = true;
       throw new Error(
-        "[PrettyDevDestination] pino-pretty is not installed. Install it as a peer dependency (`pnpm add -D pino-pretty`) or remove PrettyDevDestination from `destinations`."
+        isPinoPrettyMissing(cause) ? "[PrettyDevDestination] pino-pretty is not installed. Install it as a peer dependency (`pnpm add -D pino-pretty`) or remove PrettyDevDestination from `destinations`." : `[PrettyDevDestination] pino-pretty failed to start: ${describeFailure(cause)}`,
+        { cause }
       );
     }
     this.flushBuffer((payload) => {
@@ -3099,7 +3174,13 @@ var PinoUnexpectedErrorSink = class {
         void 0,
         metadata
       );
-    } catch {
+    } catch (cause) {
+      reportDestinationFailure(
+        RESERVED_LOG_KEYS.HTTP_UNEXPECTED_ERROR_DROPPED,
+        "PinoUnexpectedErrorSink",
+        cause,
+        "An unexpected-error report could not be logged and was dropped."
+      );
     }
   }
 };

package/dist/shared/index.cjs

@@ -18,12 +18,14 @@ var RESERVED_LOG_KEYS = Object.freeze({
   HTTP_EXCEPTION_HANDLED: "HTTP_EXCEPTION_HANDLED",
   HTTP_EXCEPTION_UNHANDLED: "HTTP_EXCEPTION_UNHANDLED",
   HTTP_UNEXPECTED_ERROR: "HTTP_UNEXPECTED_ERROR",
+  HTTP_UNEXPECTED_ERROR_DROPPED: "HTTP_UNEXPECTED_ERROR_DROPPED",
   METHOD_EXECUTION: "METHOD_EXECUTION",
   METHOD_SLOW_EXECUTION: "METHOD_SLOW_EXECUTION",
   LOGGER_DESTINATION_INIT_FAILED: "LOGGER_DESTINATION_INIT_FAILED",
   LOGGER_DESTINATION_WRITE_FAILED: "LOGGER_DESTINATION_WRITE_FAILED",
   LOGGER_ENTRY_TRUNCATED: "LOGGER_ENTRY_TRUNCATED",
-  LOGGER_REDACTION_FAILED: "LOGGER_REDACTION_FAILED"
+  LOGGER_REDACTION_FAILED: "LOGGER_REDACTION_FAILED",
+  LOGGER_OTEL_API_BROKEN: "LOGGER_OTEL_API_BROKEN"
 });
 var RESERVED_LOG_KEYS_NOT_EMITTED = Object.freeze({
   /**

package/dist/shared/index.d.cts

@@ -239,12 +239,14 @@ declare const RESERVED_LOG_KEYS: Readonly<{
     readonly HTTP_EXCEPTION_HANDLED: "HTTP_EXCEPTION_HANDLED";
     readonly HTTP_EXCEPTION_UNHANDLED: "HTTP_EXCEPTION_UNHANDLED";
     readonly HTTP_UNEXPECTED_ERROR: "HTTP_UNEXPECTED_ERROR";
+    readonly HTTP_UNEXPECTED_ERROR_DROPPED: "HTTP_UNEXPECTED_ERROR_DROPPED";
     readonly METHOD_EXECUTION: "METHOD_EXECUTION";
     readonly METHOD_SLOW_EXECUTION: "METHOD_SLOW_EXECUTION";
     readonly LOGGER_DESTINATION_INIT_FAILED: "LOGGER_DESTINATION_INIT_FAILED";
     readonly LOGGER_DESTINATION_WRITE_FAILED: "LOGGER_DESTINATION_WRITE_FAILED";
     readonly LOGGER_ENTRY_TRUNCATED: "LOGGER_ENTRY_TRUNCATED";
     readonly LOGGER_REDACTION_FAILED: "LOGGER_REDACTION_FAILED";
+    readonly LOGGER_OTEL_API_BROKEN: "LOGGER_OTEL_API_BROKEN";
 }>;
 /**
  * Keys that are reserved but intentionally never emitted, each with the reason.

package/dist/shared/index.d.ts

@@ -239,12 +239,14 @@ declare const RESERVED_LOG_KEYS: Readonly<{
     readonly HTTP_EXCEPTION_HANDLED: "HTTP_EXCEPTION_HANDLED";
     readonly HTTP_EXCEPTION_UNHANDLED: "HTTP_EXCEPTION_UNHANDLED";
     readonly HTTP_UNEXPECTED_ERROR: "HTTP_UNEXPECTED_ERROR";
+    readonly HTTP_UNEXPECTED_ERROR_DROPPED: "HTTP_UNEXPECTED_ERROR_DROPPED";
     readonly METHOD_EXECUTION: "METHOD_EXECUTION";
     readonly METHOD_SLOW_EXECUTION: "METHOD_SLOW_EXECUTION";
     readonly LOGGER_DESTINATION_INIT_FAILED: "LOGGER_DESTINATION_INIT_FAILED";
     readonly LOGGER_DESTINATION_WRITE_FAILED: "LOGGER_DESTINATION_WRITE_FAILED";
     readonly LOGGER_ENTRY_TRUNCATED: "LOGGER_ENTRY_TRUNCATED";
     readonly LOGGER_REDACTION_FAILED: "LOGGER_REDACTION_FAILED";
+    readonly LOGGER_OTEL_API_BROKEN: "LOGGER_OTEL_API_BROKEN";
 }>;
 /**
  * Keys that are reserved but intentionally never emitted, each with the reason.

package/dist/shared/index.mjs

@@ -16,12 +16,14 @@ var RESERVED_LOG_KEYS = Object.freeze({
   HTTP_EXCEPTION_HANDLED: "HTTP_EXCEPTION_HANDLED",
   HTTP_EXCEPTION_UNHANDLED: "HTTP_EXCEPTION_UNHANDLED",
   HTTP_UNEXPECTED_ERROR: "HTTP_UNEXPECTED_ERROR",
+  HTTP_UNEXPECTED_ERROR_DROPPED: "HTTP_UNEXPECTED_ERROR_DROPPED",
   METHOD_EXECUTION: "METHOD_EXECUTION",
   METHOD_SLOW_EXECUTION: "METHOD_SLOW_EXECUTION",
   LOGGER_DESTINATION_INIT_FAILED: "LOGGER_DESTINATION_INIT_FAILED",
   LOGGER_DESTINATION_WRITE_FAILED: "LOGGER_DESTINATION_WRITE_FAILED",
   LOGGER_ENTRY_TRUNCATED: "LOGGER_ENTRY_TRUNCATED",
-  LOGGER_REDACTION_FAILED: "LOGGER_REDACTION_FAILED"
+  LOGGER_REDACTION_FAILED: "LOGGER_REDACTION_FAILED",
+  LOGGER_OTEL_API_BROKEN: "LOGGER_OTEL_API_BROKEN"
 });
 var RESERVED_LOG_KEYS_NOT_EMITTED = Object.freeze({
   /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bymax-one/nest-logger",
-  "version": "1.4.5",
+  "version": "1.4.6",
   "description": "Structured JSON logging for NestJS based on Pino 10, with optional OpenTelemetry correlation.",
   "author": "Bymax One <support@bymax.one>",
   "license": "MIT",
@@ -57,6 +57,7 @@
     "bench": "node --expose-gc --import tsx bench/throughput.bench.ts",
     "build": "pnpm clean && tsup",
     "check:exports": "attw --pack .",
+    "check:api": "node scripts/check-api-surface.mjs",
     "check:docs": "node scripts/check-doc-snippets.mjs",
     "check:mutants": "node scripts/check-mutation-directives.mjs",
     "check:published": "node scripts/check-published-surface.mjs",