@bymax-one/nest-telemetry 1.0.2 → 1.0.4

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.
@@ -41,18 +41,25 @@ interface UnsafeOptions {
41
41
  /** Keeps Redis command arguments in `db.query.text`, including `EVAL` and `EVALSHA` payloads. */
42
42
  readonly disableRedisArgumentRedaction?: true;
43
43
  /**
44
- * Keeps `process.command_args` and `process.command_line` in the exported resource. They are
45
- * removed by default, because command-line arguments are a common carrier of secrets.
44
+ * Keeps `process.command_args`, `process.command_line` and `process.command` in the exported
45
+ * resource. They are removed by default, because command-line arguments are a common carrier of
46
+ * secrets, and `process.command` is the first argument for `node -e code ARG`.
46
47
  */
47
48
  readonly exportProcessCommandArgs?: true;
49
+ /**
50
+ * Keeps `host.id` in the exported resource. It is removed by default: it is the machine
51
+ * identifier (the platform UUID, or `/etc/machine-id`), a stable hardware id that every collector
52
+ * and backend would see. `host.name` stays.
53
+ */
54
+ readonly exportHostId?: true;
48
55
  }
49
56
  /** Instrumentation choices that are the host's policy, with their safe defaults. */
50
57
  interface InstrumentationOptions {
51
58
  /** File-system instrumentation. Off by default: it floods traces with context-free disk activity. */
52
59
  readonly fs?: boolean;
53
60
  /**
54
- * Whether pino's records are forwarded to the OpenTelemetry logs pipeline. Defaults to whether
55
- * `OTEL_LOGS_EXPORTER` names an exporter that exports logs.
61
+ * Whether the records of pino, winston and bunyan are forwarded to the OpenTelemetry logs
62
+ * pipeline. Defaults to whether `OTEL_LOGS_EXPORTER` names an exporter that exports logs.
56
63
  */
57
64
  readonly sendLogs?: boolean;
58
65
  /**
@@ -85,6 +92,13 @@ interface TelemetryOptions {
85
92
  readonly extraRedactedQueryParams?: readonly string[];
86
93
  /** Explicit opt-outs from redaction. */
87
94
  readonly unsafe?: UnsafeOptions;
95
+ /**
96
+ * The longest `shutdown` waits for the final flush, in milliseconds. A collector that accepts a
97
+ * connection and never answers cannot hold the process past it: shutdown warns with
98
+ * `BYMAX_TELEMETRY_SHUTDOWN_TIMEOUT` and resolves, and spans still queued may be lost. Defaults
99
+ * to 5000; a value that is not a finite number above zero, or is above 120000, means the default.
100
+ */
101
+ readonly shutdownTimeoutMs?: number;
88
102
  /**
89
103
  * The environment the library reads, which defaults to the process environment. The OTel SDK
90
104
  * reads `OTEL_EXPORTER_OTLP_*` and the sampler variables from the process environment itself.
@@ -110,8 +124,12 @@ interface TelemetryHandle {
110
124
  * Only the path is compared: the query string is cut first, so an exclusion cannot be switched off
111
125
  * by appending a parameter, and a probe path hidden in a query cannot trigger one. A request with no
112
126
  * 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.
127
+ * the traffic least likely to be well formed. A path longer than 2,048 characters is never ignored
128
+ * and the patterns are not run against it, which bounds the work a long path can cause. Anchor
129
+ * the patterns at both ends and give them no nested quantifiers such as `(a+)+`: an unanchored
130
+ * pattern also matches routes that merely contain the word, and the cap does not bound a nested
131
+ * quantifier on a short path: `/^\/(a+)+$/` took 2.5 s and 5.5 s in two runs on 28 characters,
132
+ * and the time grows exponentially with the length.
115
133
  *
116
134
  * @param patterns - Patterns tested against the path alone.
117
135
  * @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,10 +65,23 @@ 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");
@@ -91,7 +105,12 @@ function setPendingStart(start) {
91
105
  function clearPendingStart() {
92
106
  delete store[PENDING_KEY];
93
107
  }
94
- 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) {
95
114
  let flush;
96
115
  let finished = false;
97
116
  const handle = {
@@ -103,12 +122,31 @@ function createHandle(stopSdk) {
103
122
  if (finished) {
104
123
  return Promise.resolve();
105
124
  }
106
- flush ??= stopSdk().finally(() => {
107
- finished = true;
108
- Reflect.set(globalThis, STOPPED_KEY, true);
109
- if (currentHandle() === handle) {
110
- Reflect.deleteProperty(globalThis, HANDLE_KEY);
111
- }
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);
112
150
  });
113
151
  return flush;
114
152
  }
@@ -126,6 +164,8 @@ var HTTP_INSTRUMENTATION = "@opentelemetry/instrumentation-http";
126
164
  var IOREDIS_INSTRUMENTATION = "@opentelemetry/instrumentation-ioredis";
127
165
  var REDIS_INSTRUMENTATION = "@opentelemetry/instrumentation-redis";
128
166
  var PINO_INSTRUMENTATION = "@opentelemetry/instrumentation-pino";
167
+ var WINSTON_INSTRUMENTATION = "@opentelemetry/instrumentation-winston";
168
+ var BUNYAN_INSTRUMENTATION = "@opentelemetry/instrumentation-bunyan";
129
169
  var LOG_EXPORTERS = /* @__PURE__ */ new Set(["otlp", "console"]);
130
170
  var UNKNOWN_SERVICE_NAME = "unknown_service:node";
131
171
  var WARNING_OPTIONS = {
@@ -161,10 +201,13 @@ function buildInstrumentationConfig(options, signals) {
161
201
  if (config !== void 0) overrides[name] = { ...config };
162
202
  }
163
203
  const redactRedis = options.unsafe?.disableRedisArgumentRedaction !== true;
204
+ const disableLogSending = !(instrumentations.sendLogs ?? signals.sendLogs);
164
205
  const library = {
165
206
  [FS_INSTRUMENTATION]: { enabled: instrumentations.fs === true },
166
207
  [HTTP_INSTRUMENTATION]: {},
167
- [PINO_INSTRUMENTATION]: { disableLogSending: !(instrumentations.sendLogs ?? signals.sendLogs) }
208
+ [PINO_INSTRUMENTATION]: { disableLogSending },
209
+ [WINSTON_INSTRUMENTATION]: { disableLogSending },
210
+ [BUNYAN_INSTRUMENTATION]: { disableLogSending }
168
211
  };
169
212
  const merged = {};
170
213
  for (const name of /* @__PURE__ */ new Set([...Object.keys(library), ...Object.keys(overrides)])) {
@@ -205,7 +248,13 @@ function warnAboutUnsafeOptions(options) {
205
248
  }
206
249
  if (options.unsafe?.exportProcessCommandArgs === true) {
207
250
  process.emitWarning(
208
- "Process command-line redaction is disabled: process.command_args and process.command_line are exported in the resource, and command-line arguments can carry secrets.",
251
+ "Process command-line redaction is disabled: process.command_args, process.command_line and process.command are exported in the resource, and command-line arguments can carry secrets.",
252
+ WARNING_OPTIONS
253
+ );
254
+ }
255
+ if (options.unsafe?.exportHostId === true) {
256
+ process.emitWarning(
257
+ "Host id redaction is disabled: host.id, the machine identifier, is exported in the resource, and it identifies the machine to every collector and backend.",
209
258
  WARNING_OPTIONS
210
259
  );
211
260
  }
@@ -216,6 +265,14 @@ function warnAboutUnsafeOptions(options) {
216
265
  );
217
266
  }
218
267
  }
268
+ function warnAboutOversizedTimers(env) {
269
+ for (const name of env.oversizedTimers) {
270
+ process.emitWarning(
271
+ `${name} is above 2147483647 ms, which a timer cannot hold, so the default applies. Set a value up to 2147483647.`,
272
+ { type: "Warning", code: "BYMAX_TELEMETRY_BSP_VALUE_IGNORED" }
273
+ );
274
+ }
275
+ }
219
276
  function warnAboutIgnoredOptions(options) {
220
277
  const stop = options.enabled === false;
221
278
  if (stop || Object.values(options).some((v) => v !== void 0)) {
@@ -227,6 +284,7 @@ function warnAboutIgnoredOptions(options) {
227
284
  }
228
285
 
229
286
  // src/sdk/environment.ts
287
+ var MAX_TIMER_MS = 2147483647;
230
288
  function readExporterList(raw) {
231
289
  return (raw ?? "").split(",").map((name) => name.trim()).filter((name) => name !== "");
232
290
  }
@@ -234,13 +292,30 @@ function readPositiveNumber(raw) {
234
292
  const value = Number(raw);
235
293
  return Number.isFinite(value) && value > 0 ? value : void 0;
236
294
  }
295
+ function readTimerMillis(name, raw, oversized) {
296
+ const value = readPositiveNumber(raw);
297
+ if (value !== void 0 && value > MAX_TIMER_MS) {
298
+ oversized.push(name);
299
+ return void 0;
300
+ }
301
+ return value;
302
+ }
237
303
  function readTelemetryEnvironment(source = process.env) {
238
304
  const tuning = {};
239
305
  const maxQueueSize = readPositiveNumber(source["OTEL_BSP_MAX_QUEUE_SIZE"]);
240
306
  if (maxQueueSize !== void 0) tuning.maxQueueSize = maxQueueSize;
241
- const scheduledDelayMillis = readPositiveNumber(source["OTEL_BSP_SCHEDULE_DELAY"]);
307
+ const oversizedTimers = [];
308
+ const scheduledDelayMillis = readTimerMillis(
309
+ "OTEL_BSP_SCHEDULE_DELAY",
310
+ source["OTEL_BSP_SCHEDULE_DELAY"],
311
+ oversizedTimers
312
+ );
242
313
  if (scheduledDelayMillis !== void 0) tuning.scheduledDelayMillis = scheduledDelayMillis;
243
- const exportTimeoutMillis = readPositiveNumber(source["OTEL_BSP_EXPORT_TIMEOUT"]);
314
+ const exportTimeoutMillis = readTimerMillis(
315
+ "OTEL_BSP_EXPORT_TIMEOUT",
316
+ source["OTEL_BSP_EXPORT_TIMEOUT"],
317
+ oversizedTimers
318
+ );
244
319
  if (exportTimeoutMillis !== void 0) tuning.exportTimeoutMillis = exportTimeoutMillis;
245
320
  const maxExportBatchSize = readPositiveNumber(source["OTEL_BSP_MAX_EXPORT_BATCH_SIZE"]);
246
321
  if (maxExportBatchSize !== void 0) tuning.maxExportBatchSize = maxExportBatchSize;
@@ -252,12 +327,49 @@ function readTelemetryEnvironment(source = process.env) {
252
327
  metricsExporters: readExporterList(source["OTEL_METRICS_EXPORTER"]),
253
328
  logsExporters: readExporterList(source["OTEL_LOGS_EXPORTER"]),
254
329
  batchSpanProcessor: tuning,
330
+ oversizedTimers,
255
331
  resourceDetectors: detectors === void 0 || detectors.trim() === "" ? void 0 : readExporterList(detectors)
256
332
  };
257
333
  }
258
334
 
335
+ // src/sdk/export-failure.ts
336
+ var WINDOW_MS = 6e4;
337
+ var SUCCESS = 0;
338
+ var CODE_TOKEN = /^[A-Z0-9_]{1,40}$/;
339
+ function codeOf(error) {
340
+ const code = String(Reflect.get(Object(error), "code"));
341
+ return CODE_TOKEN.test(code) ? code : "UNKNOWN";
342
+ }
343
+ function warnOnExportFailure(exporter, kind, clock = () => performance.now()) {
344
+ const original = exporter.export.bind(exporter);
345
+ let lastWarning = Number.NEGATIVE_INFINITY;
346
+ exporter.export = (spans, done) => {
347
+ original(spans, (result) => {
348
+ if (result.code !== SUCCESS && clock() - lastWarning >= WINDOW_MS) {
349
+ lastWarning = clock();
350
+ try {
351
+ const code = codeOf(result.error);
352
+ reportWarning({
353
+ code: "BYMAX_TELEMETRY_EXPORT_FAILED",
354
+ 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.`,
355
+ fields: { kind, code }
356
+ });
357
+ } catch {
358
+ }
359
+ }
360
+ done(result);
361
+ });
362
+ };
363
+ return exporter;
364
+ }
365
+
259
366
  // src/sdk/resource-detectors.ts
260
- var COMMAND_LINE_ATTRIBUTES = ["process.command_args", "process.command_line"];
367
+ var COMMAND_LINE_ATTRIBUTES = [
368
+ "process.command_args",
369
+ "process.command_line",
370
+ "process.command"
371
+ ];
372
+ var HOST_ID_ATTRIBUTES = ["host.id"];
261
373
  var NAMED = /* @__PURE__ */ new Map([
262
374
  ["process", ["process"]],
263
375
  ["host", ["host", "os"]],
@@ -289,8 +401,12 @@ function withoutAttributes(detector, names) {
289
401
  }
290
402
  };
291
403
  }
292
- function selectResourceDetectors(selection, detectors, keepCommandLine) {
293
- const available = keepCommandLine ? detectors : { ...detectors, process: withoutAttributes(detectors.process, COMMAND_LINE_ATTRIBUTES) };
404
+ function selectResourceDetectors(selection, detectors, keeps) {
405
+ const available = {
406
+ ...detectors,
407
+ process: keeps.keepCommandLine ? detectors.process : withoutAttributes(detectors.process, COMMAND_LINE_ATTRIBUTES),
408
+ host: keeps.keepHostId ? detectors.host : withoutAttributes(detectors.host, HOST_ID_ATTRIBUTES)
409
+ };
294
410
  if (selection?.includes("none") === true && !selection.includes("all")) {
295
411
  return [];
296
412
  }
@@ -365,13 +481,16 @@ function buildSdk(packages, options, env) {
365
481
  process: resources.processDetector,
366
482
  serviceinstance: resources.serviceInstanceIdDetector
367
483
  },
368
- options.unsafe?.exportProcessCommandArgs === true
484
+ {
485
+ keepCommandLine: options.unsafe?.exportProcessCommandArgs === true,
486
+ keepHostId: options.unsafe?.exportHostId === true
487
+ }
369
488
  ),
370
489
  spanProcessors: [
371
490
  // Ordered before the batch processor, so each span is redacted in place before it is exported.
372
491
  ...options.unsafe?.disableUrlRedaction === true ? [] : [createUrlQueryRedactor()],
373
492
  new sdkTrace.BatchSpanProcessor({
374
- exporter: new exporter.OTLPTraceExporter(),
493
+ exporter: warnOnExportFailure(new exporter.OTLPTraceExporter(), "otlp-http traces"),
375
494
  ...env.batchSpanProcessor
376
495
  })
377
496
  ],
@@ -383,9 +502,10 @@ function buildSdk(packages, options, env) {
383
502
  async function boot(options, env) {
384
503
  warnAboutUnsafeOptions(options);
385
504
  warnAboutMissingServiceName(options, env);
505
+ warnAboutOversizedTimers(env);
386
506
  const sdk = buildSdk(await loadPackages(), options, env);
387
507
  sdk.start();
388
- const handle = createHandle(() => sdk.shutdown());
508
+ const handle = createHandle(() => sdk.shutdown(), options.shutdownTimeoutMs);
389
509
  registerHandle(handle);
390
510
  return handle;
391
511
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@bymax-one/nest-telemetry",
3
- "version": "1.0.2",
3
+ "version": "1.0.4",
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",
@@ -190,6 +190,7 @@
190
190
  "jest": "^30.4.2",
191
191
  "lint-staged": "^17.0.7",
192
192
  "mysql2": "3.24.6",
193
+ "pino": "10.4.0",
193
194
  "prettier": "^3.8.3",
194
195
  "redis": "^5.12.2",
195
196
  "reflect-metadata": "^0.2.2",