@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.
- package/CHANGELOG.md +113 -0
- package/README.md +96 -62
- package/dist/nest/index.cjs +48 -0
- package/dist/nest/index.d.cts +35 -6
- package/dist/nest/index.d.ts +35 -6
- package/dist/nest/index.mjs +48 -2
- package/dist/register/index.mjs +106 -15
- package/dist/sdk/index.cjs +108 -16
- package/dist/sdk/index.d.cts +13 -2
- package/dist/sdk/index.d.ts +13 -2
- package/dist/sdk/index.mjs +108 -16
- package/package.json +4 -1
package/dist/sdk/index.d.ts
CHANGED
|
@@ -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.
|
|
114
|
-
*
|
|
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`.
|
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,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
|
|
82
|
-
|
|
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
|
-
|
|
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 ??=
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
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
|
-
|
|
182
|
-
...merged[
|
|
183
|
-
|
|
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.
|
|
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",
|