@bymax-one/nest-telemetry 1.0.1 → 1.0.3

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.
@@ -85,6 +85,13 @@ interface TelemetryOptions {
85
85
  readonly extraRedactedQueryParams?: readonly string[];
86
86
  /** Explicit opt-outs from redaction. */
87
87
  readonly unsafe?: UnsafeOptions;
88
+ /**
89
+ * The longest `shutdown` waits for the final flush, in milliseconds. A collector that accepts a
90
+ * connection and never answers cannot hold the process past it: shutdown warns with
91
+ * `BYMAX_TELEMETRY_SHUTDOWN_TIMEOUT` and resolves, and spans still queued may be lost. Defaults
92
+ * to 5000; a value that is not a finite number above zero, or is above 120000, means the default.
93
+ */
94
+ readonly shutdownTimeoutMs?: number;
88
95
  /**
89
96
  * The environment the library reads, which defaults to the process environment. The OTel SDK
90
97
  * reads `OTEL_EXPORTER_OTLP_*` and the sampler variables from the process environment itself.
@@ -110,8 +117,12 @@ interface TelemetryHandle {
110
117
  * Only the path is compared: the query string is cut first, so an exclusion cannot be switched off
111
118
  * by appending a parameter, and a probe path hidden in a query cannot trigger one. A request with no
112
119
  * target is not matched: failing open costs a span nobody wanted, where the opposite silently drops
113
- * the traffic least likely to be well formed. Anchor the patterns at both ends; an unanchored one
114
- * also matches routes that merely contain the word.
120
+ * the traffic least likely to be well formed. A path longer than 2,048 characters is never ignored
121
+ * and the patterns are not run against it, which bounds the work a long path can cause. Anchor
122
+ * the patterns at both ends and give them no nested quantifiers such as `(a+)+`: an unanchored
123
+ * pattern also matches routes that merely contain the word, and the cap does not bound a nested
124
+ * quantifier on a short path: `/^\/(a+)+$/` took 2.5 s and 5.5 s in two runs on 28 characters,
125
+ * and the time grows exponentially with the length.
115
126
  *
116
127
  * @param patterns - Patterns tested against the path alone.
117
128
  * @returns A predicate for `TelemetryOptions.ignoreIncomingRequest`.
@@ -54,6 +54,7 @@ function serializeRedisCommandName(commandName) {
54
54
  }
55
55
 
56
56
  // src/sdk/ignore-paths.ts
57
+ var MAX_PATH_LENGTH = 2048;
57
58
  function ignorePaths(patterns) {
58
59
  const stateless = patterns.map(
59
60
  (pattern) => new RegExp(pattern.source, pattern.flags.replace(/[gy]/g, ""))
@@ -64,13 +65,27 @@ function ignorePaths(patterns) {
64
65
  }
65
66
  const cut = request.url.indexOf("?");
66
67
  const path = cut === -1 ? request.url : request.url.slice(0, cut);
67
- return stateless.some((pattern) => pattern.test(path));
68
+ return path.length <= MAX_PATH_LENGTH && stateless.some((pattern) => pattern.test(path));
68
69
  };
69
70
  }
70
71
 
72
+ // src/sdk/warning-sink.ts
73
+ var SINK_KEY = /* @__PURE__ */ Symbol.for("@bymax-one/nest-telemetry/warning-sink");
74
+ function reportWarning(warning) {
75
+ try {
76
+ const sink = Reflect.get(globalThis, SINK_KEY);
77
+ if (sink?.(warning) === true) {
78
+ return;
79
+ }
80
+ } catch {
81
+ }
82
+ process.emitWarning(warning.text, { type: "Warning", code: warning.code });
83
+ }
84
+
71
85
  // src/sdk/handle.ts
72
86
  var HANDLE_KEY = /* @__PURE__ */ Symbol.for("@bymax-one/nest-telemetry/handle");
73
87
  var PENDING_KEY = /* @__PURE__ */ Symbol.for("@bymax-one/nest-telemetry/pending-start");
88
+ var STOPPED_KEY = /* @__PURE__ */ Symbol.for("@bymax-one/nest-telemetry/stopped");
74
89
  var store = globalThis;
75
90
  function registerHandle(handle) {
76
91
  store[HANDLE_KEY] = handle;
@@ -78,8 +93,8 @@ function registerHandle(handle) {
78
93
  function currentHandle() {
79
94
  return store[HANDLE_KEY];
80
95
  }
81
- function clearHandle() {
82
- delete store[HANDLE_KEY];
96
+ function hasStopped() {
97
+ return Reflect.get(globalThis, STOPPED_KEY) === true;
83
98
  }
84
99
  function pendingStart() {
85
100
  return store[PENDING_KEY];
@@ -90,7 +105,12 @@ function setPendingStart(start) {
90
105
  function clearPendingStart() {
91
106
  delete store[PENDING_KEY];
92
107
  }
93
- function createHandle(stopSdk) {
108
+ var DEFAULT_SHUTDOWN_TIMEOUT_MS = 5e3;
109
+ var MAX_SHUTDOWN_TIMEOUT_MS = 12e4;
110
+ function shutdownDeadline(requested) {
111
+ return requested !== void 0 && Number.isFinite(requested) && requested > 0 && requested <= MAX_SHUTDOWN_TIMEOUT_MS ? requested : DEFAULT_SHUTDOWN_TIMEOUT_MS;
112
+ }
113
+ function createHandle(stopSdk, shutdownTimeoutMs) {
94
114
  let flush;
95
115
  let finished = false;
96
116
  const handle = {
@@ -102,11 +122,31 @@ function createHandle(stopSdk) {
102
122
  if (finished) {
103
123
  return Promise.resolve();
104
124
  }
105
- flush ??= stopSdk().finally(() => {
106
- finished = true;
107
- if (currentHandle() === handle) {
108
- clearHandle();
109
- }
125
+ flush ??= new Promise((resolve, reject) => {
126
+ const deadline = shutdownDeadline(shutdownTimeoutMs);
127
+ const finish = () => {
128
+ finished = true;
129
+ Reflect.set(globalThis, STOPPED_KEY, true);
130
+ if (currentHandle() === handle) {
131
+ Reflect.deleteProperty(globalThis, HANDLE_KEY);
132
+ }
133
+ };
134
+ const timer = setTimeout(() => {
135
+ reportWarning({
136
+ code: "BYMAX_TELEMETRY_SHUTDOWN_TIMEOUT",
137
+ text: `The telemetry flush did not finish within ${deadline} ms, so shutdown stopped waiting for it. Spans still queued may be lost. Raise shutdownTimeoutMs or check that the collector answers.`,
138
+ fields: { timeoutMs: deadline }
139
+ });
140
+ finish();
141
+ resolve();
142
+ }, deadline);
143
+ timer.unref();
144
+ new Promise((started) => {
145
+ started(stopSdk());
146
+ }).finally(() => {
147
+ clearTimeout(timer);
148
+ finish();
149
+ }).then(resolve, reject);
110
150
  });
111
151
  return flush;
112
152
  }
@@ -122,6 +162,7 @@ async function shutdownTelemetry() {
122
162
  var FS_INSTRUMENTATION = "@opentelemetry/instrumentation-fs";
123
163
  var HTTP_INSTRUMENTATION = "@opentelemetry/instrumentation-http";
124
164
  var IOREDIS_INSTRUMENTATION = "@opentelemetry/instrumentation-ioredis";
165
+ var REDIS_INSTRUMENTATION = "@opentelemetry/instrumentation-redis";
125
166
  var PINO_INSTRUMENTATION = "@opentelemetry/instrumentation-pino";
126
167
  var LOG_EXPORTERS = /* @__PURE__ */ new Set(["otlp", "console"]);
127
168
  var UNKNOWN_SERVICE_NAME = "unknown_service:node";
@@ -129,6 +170,7 @@ var WARNING_OPTIONS = {
129
170
  type: "SecurityWarning",
130
171
  code: "BYMAX_TELEMETRY_UNSAFE_REDACTION_DISABLED"
131
172
  };
173
+ var IGNORED_WARNING = { type: "Warning", code: "BYMAX_TELEMETRY_OPTIONS_IGNORED" };
132
174
  function planSignals(env) {
133
175
  const overrides = {};
134
176
  if (env.metricsExporters.length === 0) overrides.metricReaders = [];
@@ -178,10 +220,9 @@ function buildInstrumentationConfig(options, signals) {
178
220
  merged[HTTP_INSTRUMENTATION]["ignoreIncomingRequestHook"] = options.ignoreIncomingRequest;
179
221
  }
180
222
  if (redactRedis) {
181
- merged[IOREDIS_INSTRUMENTATION] = {
182
- ...merged[IOREDIS_INSTRUMENTATION],
183
- dbStatementSerializer: serializeRedisCommandName
184
- };
223
+ for (const name of [IOREDIS_INSTRUMENTATION, REDIS_INSTRUMENTATION]) {
224
+ merged[name] = { ...merged[name], dbStatementSerializer: serializeRedisCommandName };
225
+ }
185
226
  }
186
227
  return merged;
187
228
  }
@@ -213,6 +254,15 @@ function warnAboutUnsafeOptions(options) {
213
254
  );
214
255
  }
215
256
  }
257
+ function warnAboutIgnoredOptions(options) {
258
+ const stop = options.enabled === false;
259
+ if (stop || Object.values(options).some((v) => v !== void 0)) {
260
+ process.emitWarning(
261
+ stop ? "startTelemetry({ enabled: false }) was called while telemetry is already running. It does not stop the running SDK: call shutdownTelemetry() for that." : "startTelemetry was called while telemetry is already running, so the options of this call were ignored. Pass them to the first call.",
262
+ IGNORED_WARNING
263
+ );
264
+ }
265
+ }
216
266
 
217
267
  // src/sdk/environment.ts
218
268
  function readExporterList(raw) {
@@ -235,7 +285,7 @@ function readTelemetryEnvironment(source = process.env) {
235
285
  const serviceName = source["OTEL_SERVICE_NAME"]?.trim();
236
286
  const detectors = source["OTEL_NODE_RESOURCE_DETECTORS"];
237
287
  return {
238
- sdkDisabled: source["OTEL_SDK_DISABLED"]?.toLowerCase() === "true",
288
+ sdkDisabled: source["OTEL_SDK_DISABLED"]?.trim().toLowerCase() === "true",
239
289
  serviceName: serviceName === "" ? void 0 : serviceName,
240
290
  metricsExporters: readExporterList(source["OTEL_METRICS_EXPORTER"]),
241
291
  logsExporters: readExporterList(source["OTEL_LOGS_EXPORTER"]),
@@ -244,6 +294,37 @@ function readTelemetryEnvironment(source = process.env) {
244
294
  };
245
295
  }
246
296
 
297
+ // src/sdk/export-failure.ts
298
+ var WINDOW_MS = 6e4;
299
+ var SUCCESS = 0;
300
+ var CODE_TOKEN = /^[A-Z0-9_]{1,40}$/;
301
+ function codeOf(error) {
302
+ const code = String(Reflect.get(Object(error), "code"));
303
+ return CODE_TOKEN.test(code) ? code : "UNKNOWN";
304
+ }
305
+ function warnOnExportFailure(exporter, kind, clock = () => performance.now()) {
306
+ const original = exporter.export.bind(exporter);
307
+ let lastWarning = Number.NEGATIVE_INFINITY;
308
+ exporter.export = (spans, done) => {
309
+ original(spans, (result) => {
310
+ if (result.code !== SUCCESS && clock() - lastWarning >= WINDOW_MS) {
311
+ lastWarning = clock();
312
+ try {
313
+ const code = codeOf(result.error);
314
+ reportWarning({
315
+ code: "BYMAX_TELEMETRY_EXPORT_FAILED",
316
+ text: `Exporting spans failed (${kind}, code ${code}), so the batch was dropped. This warning repeats at most once a minute. Check that the collector is reachable.`,
317
+ fields: { kind, code }
318
+ });
319
+ } catch {
320
+ }
321
+ }
322
+ done(result);
323
+ });
324
+ };
325
+ return exporter;
326
+ }
327
+
247
328
  // src/sdk/resource-detectors.ts
248
329
  var COMMAND_LINE_ATTRIBUTES = ["process.command_args", "process.command_line"];
249
330
  var NAMED = /* @__PURE__ */ new Map([
@@ -292,6 +373,7 @@ function selectResourceDetectors(selection, detectors, keepCommandLine) {
292
373
  }
293
374
 
294
375
  // src/sdk/start.ts
376
+ var RESTART_MESSAGE = "Telemetry cannot start again after it was shut down in the same process: the modules the first start instrumented stay patched against its tracer provider, so a second SDK would export nothing for them. Start telemetry once per process; in a test suite, start it once in a global setup.";
295
377
  var DISABLED_HANDLE = {
296
378
  enabled: false,
297
379
  shutdown: () => Promise.resolve()
@@ -299,6 +381,7 @@ var DISABLED_HANDLE = {
299
381
  async function startTelemetry(options = {}) {
300
382
  const env = readTelemetryEnvironment(options.env);
301
383
  if (options.enabled === false || env.sdkDisabled) {
384
+ if (currentHandle()?.stopping === false || pendingStart()) warnAboutIgnoredOptions(options);
302
385
  return DISABLED_HANDLE;
303
386
  }
304
387
  let running = currentHandle();
@@ -307,12 +390,21 @@ async function startTelemetry(options = {}) {
307
390
  running = currentHandle();
308
391
  }
309
392
  if (running !== void 0) {
393
+ warnAboutIgnoredOptions(options);
310
394
  return running;
311
395
  }
312
396
  const joined = pendingStart();
313
397
  if (joined !== void 0) {
398
+ warnAboutIgnoredOptions(options);
314
399
  return joined;
315
400
  }
401
+ if (hasStopped()) {
402
+ process.emitWarning(RESTART_MESSAGE, {
403
+ type: "Warning",
404
+ code: "BYMAX_TELEMETRY_RESTART_UNSUPPORTED"
405
+ });
406
+ throw new Error(RESTART_MESSAGE);
407
+ }
316
408
  const start = boot(options, env).finally(clearPendingStart);
317
409
  setPendingStart(start);
318
410
  return start;
@@ -348,7 +440,7 @@ function buildSdk(packages, options, env) {
348
440
  // Ordered before the batch processor, so each span is redacted in place before it is exported.
349
441
  ...options.unsafe?.disableUrlRedaction === true ? [] : [createUrlQueryRedactor()],
350
442
  new sdkTrace.BatchSpanProcessor({
351
- exporter: new exporter.OTLPTraceExporter(),
443
+ exporter: warnOnExportFailure(new exporter.OTLPTraceExporter(), "otlp-http traces"),
352
444
  ...env.batchSpanProcessor
353
445
  })
354
446
  ],
@@ -362,7 +454,7 @@ async function boot(options, env) {
362
454
  warnAboutMissingServiceName(options, env);
363
455
  const sdk = buildSdk(await loadPackages(), options, env);
364
456
  sdk.start();
365
- const handle = createHandle(() => sdk.shutdown());
457
+ const handle = createHandle(() => sdk.shutdown(), options.shutdownTimeoutMs);
366
458
  registerHandle(handle);
367
459
  return handle;
368
460
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@bymax-one/nest-telemetry",
3
- "version": "1.0.1",
3
+ "version": "1.0.3",
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",
@@ -189,7 +189,10 @@
189
189
  "ioredis": "^6.0.0",
190
190
  "jest": "^30.4.2",
191
191
  "lint-staged": "^17.0.7",
192
+ "mysql2": "3.24.6",
193
+ "pino": "10.4.0",
192
194
  "prettier": "^3.8.3",
195
+ "redis": "^5.12.2",
193
196
  "reflect-metadata": "^0.2.2",
194
197
  "rxjs": "^7.8.0",
195
198
  "supertest": "^7.2.2",