@bymax-one/nest-telemetry 1.0.6 → 1.0.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -10,6 +10,30 @@ heading here.
10
10
 
11
11
  ## [Unreleased]
12
12
 
13
+ ## [1.0.7] - 2026-11-20
14
+
15
+ ### Fixed
16
+
17
+ - **An asynchronous `TELEMETRY_LOGGER` can no longer end the process.** The hook reports a failed flush, a
18
+ shutdown that hit its deadline and a failed span export through the application's logger and did not look
19
+ at what the logger returned, so a logger whose promise rejected (a network sink that is down) produced an
20
+ unhandled rejection, which ends a Node process by default. The returned promise is now absorbed, since the
21
+ report is best effort and nothing waits for it.
22
+
23
+ ### Documentation
24
+
25
+ - **The README says what a logger that throws or rejects does.** A synchronous throw, from a
26
+ `TELEMETRY_LOGGER` or from the logger installed with `Logger.overrideLogger`, is absorbed and the shutdown
27
+ still resolves, now pinned through a real Nest logger. A rejecting asynchronous `error` method installed
28
+ with `overrideLogger` is not caught by Nest or by this library and is an unhandled rejection.
29
+ - **The README no longer says the library never touches the sampler variables.** It reads `OTEL_TRACES_SAMPLER`
30
+ and `OTEL_TRACES_SAMPLER_ARG` to warn when the SDK will ignore a ratio argument or sample every trace, and the
31
+ variable table lists them. Two other sentences are clearer: where the Nest module reports a refused flush, and
32
+ why the Nest logger entry leaves out the error message and stack.
33
+
34
+ **Apply note.** No action is needed. If your `TELEMETRY_LOGGER` methods return promises, a rejection is now
35
+ dropped silently instead of surfacing as an unhandled rejection.
36
+
13
37
  ## [1.0.6] - 2026-11-18
14
38
 
15
39
  ### Added
@@ -314,6 +338,7 @@ First release.
314
338
  - Verification from the packed tarball: real `node --import` processes in a CommonJS and a native-ESM
315
339
  application, with planted secrets absent from the exported body and negative controls.
316
340
 
341
+ [1.0.7]: https://github.com/bymaxone/nest-telemetry/releases/tag/v1.0.7
317
342
  [1.0.6]: https://github.com/bymaxone/nest-telemetry/releases/tag/v1.0.6
318
343
  [1.0.5]: https://github.com/bymaxone/nest-telemetry/releases/tag/v1.0.5
319
344
  [1.0.4]: https://github.com/bymaxone/nest-telemetry/releases/tag/v1.0.4
package/README.md CHANGED
@@ -195,9 +195,10 @@ The library reads these in one source file, and a test fails if any other file n
195
195
  | `OTEL_SERVICE_NAME` | Service name; overrides the option, because the operator's standard variable wins over what the code chose. Blank values count as absent. |
196
196
  | `OTEL_METRICS_EXPORTER`, `OTEL_LOGS_EXPORTER` | Metrics and logs are exported only when these name an exporter. |
197
197
  | `OTEL_BSP_MAX_QUEUE_SIZE`, `OTEL_BSP_SCHEDULE_DELAY`, `OTEL_BSP_EXPORT_TIMEOUT`, `OTEL_BSP_MAX_EXPORT_BATCH_SIZE` | Mapped onto the batch span processor the library passes; the SDK applies them only to one it builds itself. A schedule delay or export timeout above 2147483647 ms is ignored with a warning, because a timer cannot hold it. |
198
+ | `OTEL_TRACES_SAMPLER`, `OTEL_TRACES_SAMPLER_ARG` | The SDK acts on them. The library only reads them to warn when the SDK will ignore a ratio argument or sample every trace; see the warning table. |
198
199
  | `OTEL_NODE_RESOURCE_DETECTORS` | Selects resource detectors, under the specification's names (`service`, `host`, `process`) and the SDK's older ones. |
199
200
 
200
- The OpenTelemetry SDK reads these itself, and the library never touches them: `OTEL_EXPORTER_OTLP_*`, `OTEL_TRACES_SAMPLER` and `OTEL_TRACES_SAMPLER_ARG`, `OTEL_RESOURCE_ATTRIBUTES`.
201
+ The OpenTelemetry SDK reads these itself, and the library never touches them: `OTEL_EXPORTER_OTLP_*` and `OTEL_RESOURCE_ATTRIBUTES`.
201
202
 
202
203
  ---
203
204
 
@@ -276,7 +277,7 @@ The standard asks `nest-queue` to carry the trace context from the request that
276
277
 
277
278
  ### Flushing
278
279
 
279
- Awaiting `shutdown()` or `shutdownTelemetry()` means the spans were exported, whoever started the flush, unless the deadline below passed first: overlapping callers wait for the same flush, and a shutdown that arrives while the SDK is still starting waits for the start and then stops what it built. A flush the collector refuses is reported, never thrown into your shutdown path, by the Nest module; the programmatic functions reject, so their caller decides.
280
+ Awaiting `shutdown()` or `shutdownTelemetry()` means the spans were exported, whoever started the flush, unless the deadline below passed first: overlapping callers wait for the same flush, and a shutdown that arrives while the SDK is still starting waits for the start and then stops what it built. The Nest module reports a flush the collector refuses and never throws it into your shutdown path; the programmatic functions reject, so their caller decides.
280
281
 
281
282
  The wait is bounded. A collector that accepts a connection and never answers would otherwise hold shutdown for the exporter's own timeout, ten seconds by default, so a flush that has not finished within `shutdownTimeoutMs` (5 seconds unless set, at most 120 seconds) stops holding the caller: shutdown emits `BYMAX_TELEMETRY_SHUTDOWN_TIMEOUT` and resolves. The flush keeps running in the background and a failure after the deadline is dropped. Spans still queued at that point may be lost.
282
283
 
@@ -451,15 +452,17 @@ No exports. `node --import @bymax-one/nest-telemetry/register` registers the loa
451
452
 
452
453
  ### Nest: `@bymax-one/nest-telemetry/nest`
453
454
 
454
- | Export | Kind | Purpose |
455
- | -------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
456
- | `TelemetryModule` | module | Global; registers `TelemetryShutdownHook`. List it first in the application module's imports |
457
- | `TelemetryShutdownHook` | provider | `OnApplicationShutdown`: awaits `shutdownTelemetry()`; a refused flush is reported and never rejects |
458
- | `TELEMETRY_LOGGER` | token | Optional provider with an `errorStructured(logKey, error)` method for a failed flush and a shutdown that hit its deadline, and an optional `warnStructured(logKey, message, userId, metadata)` for a failed export. Without it, a failed flush goes to the Nest logger under `TRACING_FLUSH_FAILED` with a short error code and no message or stack, which can carry the collector's endpoint |
459
- | `TELEMETRY_FLUSH_FAILED_KEY` | constant | The stable key, `TRACING_FLUSH_FAILED`, under which a failed flush is reported |
460
- | `TELEMETRY_SHUTDOWN_TIMEOUT_KEY` | constant | The stable key, `TRACING_SHUTDOWN_TIMEOUT`, under which a shutdown that hit `shutdownTimeoutMs` is reported |
461
- | `TELEMETRY_EXPORT_FAILED_KEY` | constant | The stable key, `TRACING_EXPORT_FAILED`, under which a failed span export is reported, with the exporter kind and the error code as metadata |
462
- | `ITelemetryErrorLogger` | type | The shape `TELEMETRY_LOGGER` provides: `errorStructured(logKey, error)` and an optional `warnStructured` |
455
+ | Export | Kind | Purpose |
456
+ | -------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
457
+ | `TelemetryModule` | module | Global; registers `TelemetryShutdownHook`. List it first in the application module's imports |
458
+ | `TelemetryShutdownHook` | provider | `OnApplicationShutdown`: awaits `shutdownTelemetry()`; a refused flush is reported and never rejects |
459
+ | `TELEMETRY_LOGGER` | token | Optional provider with an `errorStructured(logKey, error)` method for a failed flush and a shutdown that hit its deadline, and an optional `warnStructured(logKey, message, userId, metadata)` for a failed export. Without it, a failed flush goes to the Nest logger under `TRACING_FLUSH_FAILED` with a short error code. The message and the stack are left out, because they can carry the collector's endpoint |
460
+ | `TELEMETRY_FLUSH_FAILED_KEY` | constant | The stable key, `TRACING_FLUSH_FAILED`, under which a failed flush is reported |
461
+ | `TELEMETRY_SHUTDOWN_TIMEOUT_KEY` | constant | The stable key, `TRACING_SHUTDOWN_TIMEOUT`, under which a shutdown that hit `shutdownTimeoutMs` is reported |
462
+ | `TELEMETRY_EXPORT_FAILED_KEY` | constant | The stable key, `TRACING_EXPORT_FAILED`, under which a failed span export is reported, with the exporter kind and the error code as metadata |
463
+ | `ITelemetryErrorLogger` | type | The shape `TELEMETRY_LOGGER` provides: `errorStructured(logKey, error)` and an optional `warnStructured` |
464
+
465
+ **A logger that throws or rejects.** The hook's job is to keep shutdown from failing, so every way it reports is guarded. A logger that throws synchronously, whether it is a `TELEMETRY_LOGGER` or the logger the application installed with `Logger.overrideLogger` or `app.useLogger()`, is absorbed, and the shutdown still resolves. A promise that a `TELEMETRY_LOGGER` method returns is not awaited, and its rejection is absorbed. Nest does not do the same for the logger it routes through: an asynchronous `error` method installed with `overrideLogger` that rejects is not caught by Nest or by this library, and Node reports it as an unhandled rejection, which ends the process by default. Write a logger for Nest so that `error` never rejects.
463
466
 
464
467
  ### Observability: `@bymax-one/nest-telemetry/observability`
465
468
 
@@ -57,6 +57,9 @@ var TELEMETRY_FLUSH_FAILED_KEY = "TRACING_FLUSH_FAILED";
57
57
  var TELEMETRY_SHUTDOWN_TIMEOUT_KEY = "TRACING_SHUTDOWN_TIMEOUT";
58
58
  var TELEMETRY_EXPORT_FAILED_KEY = "TRACING_EXPORT_FAILED";
59
59
  var TELEMETRY_LOGGER = /* @__PURE__ */ Symbol("TELEMETRY_LOGGER");
60
+ function absorbRejection(result) {
61
+ Promise.resolve(result).catch(() => void 0);
62
+ }
60
63
  exports.TelemetryShutdownHook = class TelemetryShutdownHook {
61
64
  /**
62
65
  * @param moduleRef - Resolves the optional structured logger when a flush fails.
@@ -103,13 +106,17 @@ exports.TelemetryShutdownHook = class TelemetryShutdownHook {
103
106
  route(warning) {
104
107
  const logger = this.structuredLogger();
105
108
  if (warning.code === "BYMAX_TELEMETRY_SHUTDOWN_TIMEOUT" && typeof logger?.errorStructured === "function") {
106
- logger.errorStructured(TELEMETRY_SHUTDOWN_TIMEOUT_KEY, new Error(warning.text));
109
+ absorbRejection(
110
+ logger.errorStructured(TELEMETRY_SHUTDOWN_TIMEOUT_KEY, new Error(warning.text))
111
+ );
107
112
  return true;
108
113
  }
109
114
  if (warning.code === "BYMAX_TELEMETRY_EXPORT_FAILED" && typeof logger?.warnStructured === "function") {
110
- logger.warnStructured(TELEMETRY_EXPORT_FAILED_KEY, warning.text, void 0, {
111
- ...warning.fields
112
- });
115
+ absorbRejection(
116
+ logger.warnStructured(TELEMETRY_EXPORT_FAILED_KEY, warning.text, void 0, {
117
+ ...warning.fields
118
+ })
119
+ );
113
120
  return true;
114
121
  }
115
122
  return false;
@@ -129,7 +136,7 @@ exports.TelemetryShutdownHook = class TelemetryShutdownHook {
129
136
  try {
130
137
  const logger = this.structuredLogger();
131
138
  if (typeof logger?.errorStructured === "function") {
132
- logger.errorStructured(TELEMETRY_FLUSH_FAILED_KEY, failure);
139
+ absorbRejection(logger.errorStructured(TELEMETRY_FLUSH_FAILED_KEY, failure));
133
140
  return;
134
141
  }
135
142
  } catch {
@@ -55,6 +55,9 @@ var TELEMETRY_FLUSH_FAILED_KEY = "TRACING_FLUSH_FAILED";
55
55
  var TELEMETRY_SHUTDOWN_TIMEOUT_KEY = "TRACING_SHUTDOWN_TIMEOUT";
56
56
  var TELEMETRY_EXPORT_FAILED_KEY = "TRACING_EXPORT_FAILED";
57
57
  var TELEMETRY_LOGGER = /* @__PURE__ */ Symbol("TELEMETRY_LOGGER");
58
+ function absorbRejection(result) {
59
+ Promise.resolve(result).catch(() => void 0);
60
+ }
58
61
  var TelemetryShutdownHook = class {
59
62
  /**
60
63
  * @param moduleRef - Resolves the optional structured logger when a flush fails.
@@ -101,13 +104,17 @@ var TelemetryShutdownHook = class {
101
104
  route(warning) {
102
105
  const logger = this.structuredLogger();
103
106
  if (warning.code === "BYMAX_TELEMETRY_SHUTDOWN_TIMEOUT" && typeof logger?.errorStructured === "function") {
104
- logger.errorStructured(TELEMETRY_SHUTDOWN_TIMEOUT_KEY, new Error(warning.text));
107
+ absorbRejection(
108
+ logger.errorStructured(TELEMETRY_SHUTDOWN_TIMEOUT_KEY, new Error(warning.text))
109
+ );
105
110
  return true;
106
111
  }
107
112
  if (warning.code === "BYMAX_TELEMETRY_EXPORT_FAILED" && typeof logger?.warnStructured === "function") {
108
- logger.warnStructured(TELEMETRY_EXPORT_FAILED_KEY, warning.text, void 0, {
109
- ...warning.fields
110
- });
113
+ absorbRejection(
114
+ logger.warnStructured(TELEMETRY_EXPORT_FAILED_KEY, warning.text, void 0, {
115
+ ...warning.fields
116
+ })
117
+ );
111
118
  return true;
112
119
  }
113
120
  return false;
@@ -127,7 +134,7 @@ var TelemetryShutdownHook = class {
127
134
  try {
128
135
  const logger = this.structuredLogger();
129
136
  if (typeof logger?.errorStructured === "function") {
130
- logger.errorStructured(TELEMETRY_FLUSH_FAILED_KEY, failure);
137
+ absorbRejection(logger.errorStructured(TELEMETRY_FLUSH_FAILED_KEY, failure));
131
138
  return;
132
139
  }
133
140
  } catch {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@bymax-one/nest-telemetry",
3
- "version": "1.0.6",
3
+ "version": "1.0.7",
4
4
  "description": "OpenTelemetry tracing for NestJS 11 and plain Node: starts the SDK before your app loads, redacts secrets from spans by default, and flushes on shutdown. Optional peers, zero cost when disabled.",
5
5
  "author": "Bymax One <support@bymax.one>",
6
6
  "license": "MIT",