@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.
- package/CHANGELOG.md +96 -0
- package/README.md +80 -57
- package/dist/nest/index.cjs +47 -0
- package/dist/nest/index.d.cts +32 -3
- package/dist/nest/index.d.ts +32 -3
- package/dist/nest/index.mjs +46 -1
- package/dist/register/index.mjs +136 -17
- package/dist/sdk/index.cjs +138 -18
- package/dist/sdk/index.d.cts +24 -6
- package/dist/sdk/index.d.ts +24 -6
- package/dist/sdk/index.mjs +138 -18
- package/package.json +2 -1
package/dist/sdk/index.d.ts
CHANGED
|
@@ -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.
|
|
45
|
-
* removed by default, because command-line arguments are a common carrier of
|
|
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
|
|
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.
|
|
114
|
-
*
|
|
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`.
|
package/dist/sdk/index.mjs
CHANGED
|
@@ -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
|
-
|
|
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 ??=
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
Reflect.
|
|
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
|
|
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.
|
|
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
|
|
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 =
|
|
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 = [
|
|
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,
|
|
293
|
-
const available =
|
|
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
|
-
|
|
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.
|
|
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",
|