@bymax-one/nest-telemetry 1.0.4 → 1.0.5
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 +31 -0
- package/README.md +28 -18
- package/dist/register/index.mjs +61 -14
- package/dist/sdk/index.cjs +49 -0
- package/dist/sdk/index.mjs +49 -0
- package/package.json +7 -4
package/CHANGELOG.md
CHANGED
|
@@ -8,6 +8,36 @@ The `release.yml` workflow extracts the section matching the pushed `vX.Y.Z` tag
|
|
|
8
8
|
as the GitHub Release body, so each released version needs a matching `## [X.Y.Z]`
|
|
9
9
|
heading here.
|
|
10
10
|
|
|
11
|
+
## [Unreleased]
|
|
12
|
+
|
|
13
|
+
## [1.0.5] - 2026-11-17
|
|
14
|
+
|
|
15
|
+
### Added
|
|
16
|
+
|
|
17
|
+
- **A start warning for a ratio sampler that has no usable ratio.** With `OTEL_TRACES_SAMPLER` set to
|
|
18
|
+
`traceidratio` or `parentbased_traceidratio`, the SDK reads `OTEL_TRACES_SAMPLER_ARG` with `Number` and
|
|
19
|
+
falls back to a ratio of 1 when it is unset, empty, not a number or outside 0 to 1, noting it only on a
|
|
20
|
+
diagnostic channel. Every trace was then sampled without a word, which is the cost a ratio was set to
|
|
21
|
+
avoid. The start now warns once with `BYMAX_TELEMETRY_SAMPLER_ARG_INVALID`, naming the variable and,
|
|
22
|
+
when one was given, the value. Measured with the real SDK: `1.5`, `-1`, `10%`, `NaN`, `Infinity` and no
|
|
23
|
+
value sampled all 200 root spans; `0` sampled none.
|
|
24
|
+
|
|
25
|
+
### Fixed
|
|
26
|
+
|
|
27
|
+
- **Winston log forwarding says when it cannot work.** The winston instrumentation forwards a record by
|
|
28
|
+
adding a transport from `@opentelemetry/winston-transport`, which it loads with a `require` and which is
|
|
29
|
+
not one of its dependencies. An application that had not installed the package got no winston record in
|
|
30
|
+
the logs pipeline and no message, although 1.0.4 and the README said `sendLogs` covers winston. The start
|
|
31
|
+
now warns once with `BYMAX_TELEMETRY_WINSTON_TRANSPORT_MISSING` when log sending is on, winston is
|
|
32
|
+
installed for the application and the transport cannot be resolved from the instrumentation. The README
|
|
33
|
+
says to install `@opentelemetry/winston-transport` as a direct dependency of the application, with what
|
|
34
|
+
was measured under npm and pnpm. The check asks whether winston is installed, not loaded, so an installed
|
|
35
|
+
winston the application never uses can warn once for nothing.
|
|
36
|
+
|
|
37
|
+
### Documentation
|
|
38
|
+
|
|
39
|
+
- The README says the node-redis measurements were taken with `redis` 5 and 6.
|
|
40
|
+
|
|
11
41
|
## [1.0.4] - 2026-11-14
|
|
12
42
|
|
|
13
43
|
### Security
|
|
@@ -207,6 +237,7 @@ First release.
|
|
|
207
237
|
- Verification from the packed tarball: real `node --import` processes in a CommonJS and a native-ESM
|
|
208
238
|
application, with planted secrets absent from the exported body and negative controls.
|
|
209
239
|
|
|
240
|
+
[1.0.5]: https://github.com/bymaxone/nest-telemetry/releases/tag/v1.0.5
|
|
210
241
|
[1.0.4]: https://github.com/bymaxone/nest-telemetry/releases/tag/v1.0.4
|
|
211
242
|
[1.0.3]: https://github.com/bymaxone/nest-telemetry/releases/tag/v1.0.3
|
|
212
243
|
[1.0.2]: https://github.com/bymaxone/nest-telemetry/releases/tag/v1.0.2
|
package/README.md
CHANGED
|
@@ -165,22 +165,22 @@ This package installs no signal handler and shows none, because handling signals
|
|
|
165
165
|
|
|
166
166
|
Every field is the host's policy, and none is required.
|
|
167
167
|
|
|
168
|
-
| Option | Default | What it does
|
|
169
|
-
| -------------------------------------- | ---------------------------- |
|
|
170
|
-
| `enabled` | `true` | `false` never starts the SDK. `OTEL_SDK_DISABLED=true` disables it regardless.
|
|
171
|
-
| `serviceName` | `unknown_service:node` | The service name. `OTEL_SERVICE_NAME` overrides it.
|
|
172
|
-
| `serviceVersion` | none | The service version.
|
|
173
|
-
| `ignoreIncomingRequest` | none | Returns `true` for an incoming request that must produce no server span. `ignorePaths(patterns)` builds one from anchored patterns.
|
|
174
|
-
| `instrumentations.fs` | `false` | File-system instrumentation.
|
|
175
|
-
| `instrumentations.sendLogs` | follows `OTEL_LOGS_EXPORTER` | Whether the records of pino, winston and bunyan are forwarded to the OpenTelemetry logs pipeline.
|
|
176
|
-
| `instrumentations.overrides` | none | Per-instrumentation configuration, merged over the library's. Redaction settings cannot be replaced here.
|
|
177
|
-
| `extraRedactedQueryParams` | none | Names added to the list redacted from outgoing request URLs. They add to the defaults and never replace them.
|
|
178
|
-
| `unsafe.disableUrlRedaction` | off | Keeps `url.query`, `url.full`, `http.url` and `http.target` as recorded. Literal `true`. Warns.
|
|
179
|
-
| `unsafe.disableRedisArgumentRedaction` | off | Keeps Redis command arguments in `db.query.text`. Literal `true`. Warns.
|
|
180
|
-
| `unsafe.exportProcessCommandArgs` | off | Keeps `process.command_args`, `process.command_line` and `process.command` in the resource. Literal `true`. Warns.
|
|
181
|
-
| `unsafe.exportHostId` | off | Keeps `host.id`, the machine identifier, in the resource. Literal `true`. Warns.
|
|
182
|
-
| `shutdownTimeoutMs` | `5000` | The longest shutdown waits for the final flush. Past it, shutdown warns and resolves. A value that is not a finite number above zero, or is above `120000`, means the default.
|
|
183
|
-
| `env` | the process environment | The environment the library reads. The OpenTelemetry SDK itself always reads the process environment.
|
|
168
|
+
| Option | Default | What it does |
|
|
169
|
+
| -------------------------------------- | ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
170
|
+
| `enabled` | `true` | `false` never starts the SDK. `OTEL_SDK_DISABLED=true` disables it regardless. |
|
|
171
|
+
| `serviceName` | `unknown_service:node` | The service name. `OTEL_SERVICE_NAME` overrides it. |
|
|
172
|
+
| `serviceVersion` | none | The service version. |
|
|
173
|
+
| `ignoreIncomingRequest` | none | Returns `true` for an incoming request that must produce no server span. `ignorePaths(patterns)` builds one from anchored patterns. |
|
|
174
|
+
| `instrumentations.fs` | `false` | File-system instrumentation. |
|
|
175
|
+
| `instrumentations.sendLogs` | follows `OTEL_LOGS_EXPORTER` | Whether the records of pino, winston and bunyan are forwarded to the OpenTelemetry logs pipeline. Winston also needs `@opentelemetry/winston-transport` installed by your application, see [Forwarding log records](#forwarding-log-records). |
|
|
176
|
+
| `instrumentations.overrides` | none | Per-instrumentation configuration, merged over the library's. Redaction settings cannot be replaced here. |
|
|
177
|
+
| `extraRedactedQueryParams` | none | Names added to the list redacted from outgoing request URLs. They add to the defaults and never replace them. |
|
|
178
|
+
| `unsafe.disableUrlRedaction` | off | Keeps `url.query`, `url.full`, `http.url` and `http.target` as recorded. Literal `true`. Warns. |
|
|
179
|
+
| `unsafe.disableRedisArgumentRedaction` | off | Keeps Redis command arguments in `db.query.text`. Literal `true`. Warns. |
|
|
180
|
+
| `unsafe.exportProcessCommandArgs` | off | Keeps `process.command_args`, `process.command_line` and `process.command` in the resource. Literal `true`. Warns. |
|
|
181
|
+
| `unsafe.exportHostId` | off | Keeps `host.id`, the machine identifier, in the resource. Literal `true`. Warns. |
|
|
182
|
+
| `shutdownTimeoutMs` | `5000` | The longest shutdown waits for the final flush. Past it, shutdown warns and resolves. A value that is not a finite number above zero, or is above `120000`, means the default. |
|
|
183
|
+
| `env` | the process environment | The environment the library reads. The OpenTelemetry SDK itself always reads the process environment. |
|
|
184
184
|
|
|
185
185
|
### Environment variables
|
|
186
186
|
|
|
@@ -216,6 +216,8 @@ The start emits these warnings:
|
|
|
216
216
|
| `BYMAX_TELEMETRY_RESTART_UNSUPPORTED` | `startTelemetry` was called after a shutdown in the same process, and is refused. |
|
|
217
217
|
| `BYMAX_TELEMETRY_SHUTDOWN_TIMEOUT` | The final flush did not finish within `shutdownTimeoutMs`. Shutdown resolved without it, and spans still queued may be lost. With `TelemetryModule` and a bound `TELEMETRY_LOGGER`, it is reported through `errorStructured` under `TRACING_SHUTDOWN_TIMEOUT` instead. |
|
|
218
218
|
| `BYMAX_TELEMETRY_EXPORT_FAILED` | A span export failed, so the batch was dropped. The warning names the exporter and a short error code, never the payload or the endpoint, and repeats at most once a minute. With `TelemetryModule` and a bound `TELEMETRY_LOGGER` that has `warnStructured`, it is reported through it under `TRACING_EXPORT_FAILED` instead. |
|
|
219
|
+
| `BYMAX_TELEMETRY_SAMPLER_ARG_INVALID` | A ratio sampler (`traceidratio` or `parentbased_traceidratio`) is selected and `OTEL_TRACES_SAMPLER_ARG` is not a number from 0 to 1, so the SDK samples every trace. Set the share of traces to keep, such as `0.1`. |
|
|
220
|
+
| `BYMAX_TELEMETRY_WINSTON_TRANSPORT_MISSING` | Log forwarding is on and winston is installed, but `@opentelemetry/winston-transport` cannot be resolved from the winston instrumentation, so winston records are not forwarded. Install it as a direct dependency of the application. |
|
|
219
221
|
| `BYMAX_TELEMETRY_BSP_VALUE_IGNORED` | An `OTEL_BSP_SCHEDULE_DELAY` or `OTEL_BSP_EXPORT_TIMEOUT` above 2147483647 ms was ignored, because a timer cannot hold it and Node would clamp it to 1 ms. The default applies. |
|
|
220
222
|
|
|
221
223
|
The programmatic `startTelemetry` keeps its rejection when the SDK cannot start, for callers that want it.
|
|
@@ -223,9 +225,15 @@ The programmatic `startTelemetry` keeps its rejection when the SDK cannot start,
|
|
|
223
225
|
### What is traced
|
|
224
226
|
|
|
225
227
|
- **Load order matters only for modules your application loads itself.** The core `http` module is patched even when the preload runs after it. A client such as `ioredis` is patched only if the preload ran before the application required it. Measured: an application that required `ioredis` first exported no `ioredis` span.
|
|
226
|
-
- **`ioredis` commands are traced only under an active span; node-redis commands are not.** The `ioredis` instrumentation defaults to `requireParentSpan: true`, so a command issued outside any request produces no span. The node-redis (`redis`) instrumentation defaults to `false`, so it traces a command with no request around it too. Measured with `redis` 5.
|
|
228
|
+
- **`ioredis` commands are traced only under an active span; node-redis commands are not.** The `ioredis` instrumentation defaults to `requireParentSpan: true`, so a command issued outside any request produces no span. The node-redis (`redis`) instrumentation defaults to `false`, so it traces a command with no request around it too. Measured with `redis` 5 and 6.
|
|
227
229
|
- **`fs` instrumentation is off by default**, because it floods traces with disk activity that has no context. Turn it on with `instrumentations.fs`.
|
|
228
230
|
|
|
231
|
+
### Forwarding log records
|
|
232
|
+
|
|
233
|
+
With `OTEL_LOGS_EXPORTER=otlp`, or `instrumentations.sendLogs: true`, the records of pino, winston and bunyan go to the OpenTelemetry logs pipeline. Winston needs one more package: install `@opentelemetry/winston-transport` as a direct dependency of your application. The winston instrumentation loads it with a `require` from its own directory, and the package is not one of that instrumentation's dependencies, so without it winston records are not forwarded. Measured with winston 3.19.0 and `@opentelemetry/winston-transport` 0.35.0: a winston record reached the collector when the package was a direct dependency under npm, under pnpm 11.20.0 with the default layout and under pnpm with `hoist=false`, and it did not under npm without the package. A package that reaches the project only as another package's dependency was not measured.
|
|
234
|
+
|
|
235
|
+
At start the library warns once, with `BYMAX_TELEMETRY_WINSTON_TRANSPORT_MISSING`, when log sending is on, winston resolves from the script that started the application (from the working directory when there is none), and the transport does not resolve from the winston instrumentation, which is found through `@opentelemetry/auto-instrumentations-node`. The check asks whether winston is installed, not whether it is loaded, because winston is usually not loaded yet at start: an installed winston that your application never uses causes one warning for nothing.
|
|
236
|
+
|
|
229
237
|
### Flushing
|
|
230
238
|
|
|
231
239
|
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.
|
|
@@ -240,7 +248,7 @@ A start after a shutdown in the same process is refused: `startTelemetry` reject
|
|
|
240
248
|
|
|
241
249
|
Every figure here was measured on one laptop, with Node 24 and a handler that does nothing but answer. Read them as orders of magnitude for your own measurement to confirm, not as promises.
|
|
242
250
|
|
|
243
|
-
- **Sampling.** The default samples every trace. For high traffic set `OTEL_TRACES_SAMPLER=parentbased_traceidratio` and `OTEL_TRACES_SAMPLER_ARG=0.1`. Of 2,000 spans created in one run each, the default exported all of them, a ratio of `0.1` exported 210 and a ratio of `0.01` exported 25.
|
|
251
|
+
- **Sampling.** The default samples every trace. For high traffic set `OTEL_TRACES_SAMPLER=parentbased_traceidratio` and `OTEL_TRACES_SAMPLER_ARG=0.1`. Of 2,000 spans created in one run each, the default exported all of them, a ratio of `0.1` exported 210 and a ratio of `0.01` exported 25. A ratio sampler needs `OTEL_TRACES_SAMPLER_ARG` to be a number from 0 to 1. When it is unset, empty, not a number or outside that range, the SDK falls back to a ratio of 1 and samples every trace, noting it only on a diagnostic channel; the start warns once with `BYMAX_TELEMETRY_SAMPLER_ARG_INVALID`, naming the variable and, when one was given, the value. It reads the process environment, as the SDK does, and not the `env` option.
|
|
244
252
|
- **TLS to the collector.** Against a collector whose certificate Node does not trust, every export failed with `self-signed certificate`. Setting `OTEL_EXPORTER_OTLP_CERTIFICATE` to the CA file, or `NODE_EXTRA_CA_CERTS`, exported all 2,000 spans in the same setup.
|
|
245
253
|
- **A collector that is down.** The batch is dropped and the library emits `BYMAX_TELEMETRY_EXPORT_FAILED`, at most once a minute. Shutdown stops waiting at `shutdownTimeoutMs`, 5 seconds by default. Before that deadline existed, shutdown against a closed port took 7,048 ms and 7,214 ms in two runs.
|
|
246
254
|
- **CPU.** One process, 4 runs per mode, median CPU time per request: 25 µs without the library, 26 µs with it loaded and disabled, 58 µs with a healthy collector (range 35 to 66) and 43 µs with the collector down (range 26 to 65). The extra cost in that handler is roughly 10 to 40 µs per request, and a handler that does real I/O dilutes it. The same configuration varied by up to a factor of two between runs.
|
|
@@ -274,6 +282,8 @@ A caret on a `0.x` version allows patch releases only, so each OpenTelemetry min
|
|
|
274
282
|
| Spans arrive but carry no service name | `BYMAX_TELEMETRY_SERVICE_NAME_MISSING`: set `OTEL_SERVICE_NAME` or the `serviceName` option. A name set only through `OTEL_RESOURCE_ATTRIBUTES` still reaches the spans, unless `OTEL_NODE_RESOURCE_DETECTORS` leaves out both the `env` and the `service` detector. |
|
|
275
283
|
| `BYMAX_TELEMETRY_START_FAILED` | The warning names the cause, usually an OpenTelemetry peer that is not installed. |
|
|
276
284
|
| HTTP spans but no Redis spans | `ioredis` commands are traced under an active span only, and the client must be loaded after the preload. |
|
|
285
|
+
| More traces than the sampling ratio should keep | `BYMAX_TELEMETRY_SAMPLER_ARG_INVALID`: `OTEL_TRACES_SAMPLER_ARG` is unset, blank or not a number from 0 to 1, so the SDK samples every trace. |
|
|
286
|
+
| Winston records missing from the logs pipeline | `BYMAX_TELEMETRY_WINSTON_TRANSPORT_MISSING`: install `@opentelemetry/winston-transport` as a direct dependency of the application. |
|
|
277
287
|
| Metrics or logs missing | They are off unless `OTEL_METRICS_EXPORTER` or `OTEL_LOGS_EXPORTER` names an exporter. |
|
|
278
288
|
| The last spans of another module are lost when the application closes | List `TelemetryModule` first in the application module's imports, so it closes last. |
|
|
279
289
|
| No spans arrive and nothing else is logged | `BYMAX_TELEMETRY_EXPORT_FAILED`: the collector did not accept the export. Check the endpoint in `OTEL_EXPORTER_OTLP_ENDPOINT` and that the collector is reachable. |
|
package/dist/register/index.mjs
CHANGED
|
@@ -1,9 +1,11 @@
|
|
|
1
|
-
import { register } from 'module';
|
|
1
|
+
import { register, createRequire } from 'module';
|
|
2
|
+
import { join } from 'path';
|
|
2
3
|
|
|
3
4
|
// src/register/boot.ts
|
|
4
5
|
|
|
5
6
|
// src/sdk/environment.ts
|
|
6
7
|
var MAX_TIMER_MS = 2147483647;
|
|
8
|
+
var RATIO_SAMPLERS = ["traceidratio", "parentbased_traceidratio"];
|
|
7
9
|
function readExporterList(raw) {
|
|
8
10
|
return (raw ?? "").split(",").map((name) => name.trim()).filter((name) => name !== "");
|
|
9
11
|
}
|
|
@@ -50,6 +52,11 @@ function readTelemetryEnvironment(source = process.env) {
|
|
|
50
52
|
resourceDetectors: detectors === void 0 || detectors.trim() === "" ? void 0 : readExporterList(detectors)
|
|
51
53
|
};
|
|
52
54
|
}
|
|
55
|
+
function readRatioSampler(source = process.env) {
|
|
56
|
+
const name = source["OTEL_TRACES_SAMPLER"];
|
|
57
|
+
const arg = source["OTEL_TRACES_SAMPLER_ARG"];
|
|
58
|
+
return name !== void 0 && RATIO_SAMPLERS.includes(name) ? { name, arg: arg?.trim() === "" ? void 0 : arg } : void 0;
|
|
59
|
+
}
|
|
53
60
|
|
|
54
61
|
// src/sdk/redaction.ts
|
|
55
62
|
var REDACTED_QUERY_VALUE = "[redacted]";
|
|
@@ -106,6 +113,19 @@ function serializeRedisCommandName(commandName) {
|
|
|
106
113
|
return commandName;
|
|
107
114
|
}
|
|
108
115
|
|
|
116
|
+
// src/sdk/warning-sink.ts
|
|
117
|
+
var SINK_KEY = /* @__PURE__ */ Symbol.for("@bymax-one/nest-telemetry/warning-sink");
|
|
118
|
+
function reportWarning(warning) {
|
|
119
|
+
try {
|
|
120
|
+
const sink = Reflect.get(globalThis, SINK_KEY);
|
|
121
|
+
if (sink?.(warning) === true) {
|
|
122
|
+
return;
|
|
123
|
+
}
|
|
124
|
+
} catch {
|
|
125
|
+
}
|
|
126
|
+
process.emitWarning(warning.text, { type: "Warning", code: warning.code });
|
|
127
|
+
}
|
|
128
|
+
|
|
109
129
|
// src/sdk/assembly.ts
|
|
110
130
|
var FS_INSTRUMENTATION = "@opentelemetry/instrumentation-fs";
|
|
111
131
|
var HTTP_INSTRUMENTATION = "@opentelemetry/instrumentation-http";
|
|
@@ -213,6 +233,17 @@ function warnAboutUnsafeOptions(options) {
|
|
|
213
233
|
);
|
|
214
234
|
}
|
|
215
235
|
}
|
|
236
|
+
var SHOWN_VALUE_LENGTH = 40;
|
|
237
|
+
function warnAboutSamplerRatio(sampler) {
|
|
238
|
+
if (sampler === void 0) return;
|
|
239
|
+
const ratio = Number(sampler.arg);
|
|
240
|
+
if (ratio >= 0 && ratio <= 1) return;
|
|
241
|
+
const given = sampler.arg === void 0 ? "not set" : `${JSON.stringify(sampler.arg.slice(0, SHOWN_VALUE_LENGTH))}, which is not a number from 0 to 1`;
|
|
242
|
+
reportWarning({
|
|
243
|
+
code: "BYMAX_TELEMETRY_SAMPLER_ARG_INVALID",
|
|
244
|
+
text: `OTEL_TRACES_SAMPLER is ${sampler.name}, but OTEL_TRACES_SAMPLER_ARG is ${given}, so the SDK samples every trace. Set it to the share of traces to keep, from 0 to 1, such as 0.1.`
|
|
245
|
+
});
|
|
246
|
+
}
|
|
216
247
|
function warnAboutOversizedTimers(env) {
|
|
217
248
|
for (const name of env.oversizedTimers) {
|
|
218
249
|
process.emitWarning(
|
|
@@ -231,19 +262,6 @@ function warnAboutIgnoredOptions(options) {
|
|
|
231
262
|
}
|
|
232
263
|
}
|
|
233
264
|
|
|
234
|
-
// src/sdk/warning-sink.ts
|
|
235
|
-
var SINK_KEY = /* @__PURE__ */ Symbol.for("@bymax-one/nest-telemetry/warning-sink");
|
|
236
|
-
function reportWarning(warning) {
|
|
237
|
-
try {
|
|
238
|
-
const sink = Reflect.get(globalThis, SINK_KEY);
|
|
239
|
-
if (sink?.(warning) === true) {
|
|
240
|
-
return;
|
|
241
|
-
}
|
|
242
|
-
} catch {
|
|
243
|
-
}
|
|
244
|
-
process.emitWarning(warning.text, { type: "Warning", code: warning.code });
|
|
245
|
-
}
|
|
246
|
-
|
|
247
265
|
// src/sdk/export-failure.ts
|
|
248
266
|
var WINDOW_MS = 6e4;
|
|
249
267
|
var SUCCESS = 0;
|
|
@@ -402,6 +420,33 @@ function selectResourceDetectors(selection, detectors, keeps) {
|
|
|
402
420
|
}
|
|
403
421
|
return [...new Set(chosen)].map((name) => available[name]);
|
|
404
422
|
}
|
|
423
|
+
var TRANSPORT = "@opentelemetry/winston-transport";
|
|
424
|
+
var BUNDLE = "@opentelemetry/auto-instrumentations-node";
|
|
425
|
+
var INSTRUMENTATION = "@opentelemetry/instrumentation-winston";
|
|
426
|
+
var MESSAGE = `Log forwarding is on and winston is installed, but ${TRANSPORT} cannot be resolved from ${INSTRUMENTATION}, so winston records will not reach the logs pipeline. Install ${TRANSPORT} as a direct dependency of the application, or set instrumentations.sendLogs to false. Ignore this if the application does not use winston.`;
|
|
427
|
+
var resolveFrom = (id, from) => {
|
|
428
|
+
try {
|
|
429
|
+
return createRequire(from).resolve(id);
|
|
430
|
+
} catch {
|
|
431
|
+
return void 0;
|
|
432
|
+
}
|
|
433
|
+
};
|
|
434
|
+
function entryFile(argv = process.argv, cwd = process.cwd()) {
|
|
435
|
+
return argv[1] ?? join(cwd, "entry.js");
|
|
436
|
+
}
|
|
437
|
+
function transportMissing(entry, resolve) {
|
|
438
|
+
if (resolve("winston", entry) === void 0) return false;
|
|
439
|
+
const bundle = resolve(BUNDLE, entry);
|
|
440
|
+
if (bundle === void 0) return false;
|
|
441
|
+
const instrumentation = resolve(INSTRUMENTATION, bundle);
|
|
442
|
+
if (instrumentation === void 0) return false;
|
|
443
|
+
return resolve(TRANSPORT, instrumentation) === void 0;
|
|
444
|
+
}
|
|
445
|
+
function warnAboutMissingWinstonTransport(sendLogs, entry = entryFile(), resolve = resolveFrom) {
|
|
446
|
+
if (sendLogs && transportMissing(entry, resolve)) {
|
|
447
|
+
reportWarning({ code: "BYMAX_TELEMETRY_WINSTON_TRANSPORT_MISSING", text: MESSAGE });
|
|
448
|
+
}
|
|
449
|
+
}
|
|
405
450
|
|
|
406
451
|
// src/sdk/start.ts
|
|
407
452
|
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.";
|
|
@@ -487,6 +532,8 @@ async function boot(options, env) {
|
|
|
487
532
|
warnAboutUnsafeOptions(options);
|
|
488
533
|
warnAboutMissingServiceName(options, env);
|
|
489
534
|
warnAboutOversizedTimers(env);
|
|
535
|
+
warnAboutSamplerRatio(readRatioSampler());
|
|
536
|
+
warnAboutMissingWinstonTransport(options.instrumentations?.sendLogs ?? planSignals(env).sendLogs);
|
|
490
537
|
const sdk = buildSdk(await loadPackages(), options, env);
|
|
491
538
|
sdk.start();
|
|
492
539
|
const handle = createHandle(() => sdk.shutdown(), options.shutdownTimeoutMs);
|
package/dist/sdk/index.cjs
CHANGED
|
@@ -1,5 +1,8 @@
|
|
|
1
1
|
'use strict';
|
|
2
2
|
|
|
3
|
+
var module$1 = require('module');
|
|
4
|
+
var path = require('path');
|
|
5
|
+
|
|
3
6
|
// src/sdk/redaction.ts
|
|
4
7
|
var REDACTED_QUERY_VALUE = "[redacted]";
|
|
5
8
|
var URL_QUERY_ATTRIBUTE = "url.query";
|
|
@@ -267,6 +270,17 @@ function warnAboutUnsafeOptions(options) {
|
|
|
267
270
|
);
|
|
268
271
|
}
|
|
269
272
|
}
|
|
273
|
+
var SHOWN_VALUE_LENGTH = 40;
|
|
274
|
+
function warnAboutSamplerRatio(sampler) {
|
|
275
|
+
if (sampler === void 0) return;
|
|
276
|
+
const ratio = Number(sampler.arg);
|
|
277
|
+
if (ratio >= 0 && ratio <= 1) return;
|
|
278
|
+
const given = sampler.arg === void 0 ? "not set" : `${JSON.stringify(sampler.arg.slice(0, SHOWN_VALUE_LENGTH))}, which is not a number from 0 to 1`;
|
|
279
|
+
reportWarning({
|
|
280
|
+
code: "BYMAX_TELEMETRY_SAMPLER_ARG_INVALID",
|
|
281
|
+
text: `OTEL_TRACES_SAMPLER is ${sampler.name}, but OTEL_TRACES_SAMPLER_ARG is ${given}, so the SDK samples every trace. Set it to the share of traces to keep, from 0 to 1, such as 0.1.`
|
|
282
|
+
});
|
|
283
|
+
}
|
|
270
284
|
function warnAboutOversizedTimers(env) {
|
|
271
285
|
for (const name of env.oversizedTimers) {
|
|
272
286
|
process.emitWarning(
|
|
@@ -287,6 +301,7 @@ function warnAboutIgnoredOptions(options) {
|
|
|
287
301
|
|
|
288
302
|
// src/sdk/environment.ts
|
|
289
303
|
var MAX_TIMER_MS = 2147483647;
|
|
304
|
+
var RATIO_SAMPLERS = ["traceidratio", "parentbased_traceidratio"];
|
|
290
305
|
function readExporterList(raw) {
|
|
291
306
|
return (raw ?? "").split(",").map((name) => name.trim()).filter((name) => name !== "");
|
|
292
307
|
}
|
|
@@ -333,6 +348,11 @@ function readTelemetryEnvironment(source = process.env) {
|
|
|
333
348
|
resourceDetectors: detectors === void 0 || detectors.trim() === "" ? void 0 : readExporterList(detectors)
|
|
334
349
|
};
|
|
335
350
|
}
|
|
351
|
+
function readRatioSampler(source = process.env) {
|
|
352
|
+
const name = source["OTEL_TRACES_SAMPLER"];
|
|
353
|
+
const arg = source["OTEL_TRACES_SAMPLER_ARG"];
|
|
354
|
+
return name !== void 0 && RATIO_SAMPLERS.includes(name) ? { name, arg: arg?.trim() === "" ? void 0 : arg } : void 0;
|
|
355
|
+
}
|
|
336
356
|
|
|
337
357
|
// src/sdk/export-failure.ts
|
|
338
358
|
var WINDOW_MS = 6e4;
|
|
@@ -420,6 +440,33 @@ function selectResourceDetectors(selection, detectors, keeps) {
|
|
|
420
440
|
}
|
|
421
441
|
return [...new Set(chosen)].map((name) => available[name]);
|
|
422
442
|
}
|
|
443
|
+
var TRANSPORT = "@opentelemetry/winston-transport";
|
|
444
|
+
var BUNDLE = "@opentelemetry/auto-instrumentations-node";
|
|
445
|
+
var INSTRUMENTATION = "@opentelemetry/instrumentation-winston";
|
|
446
|
+
var MESSAGE = `Log forwarding is on and winston is installed, but ${TRANSPORT} cannot be resolved from ${INSTRUMENTATION}, so winston records will not reach the logs pipeline. Install ${TRANSPORT} as a direct dependency of the application, or set instrumentations.sendLogs to false. Ignore this if the application does not use winston.`;
|
|
447
|
+
var resolveFrom = (id, from) => {
|
|
448
|
+
try {
|
|
449
|
+
return module$1.createRequire(from).resolve(id);
|
|
450
|
+
} catch {
|
|
451
|
+
return void 0;
|
|
452
|
+
}
|
|
453
|
+
};
|
|
454
|
+
function entryFile(argv = process.argv, cwd = process.cwd()) {
|
|
455
|
+
return argv[1] ?? path.join(cwd, "entry.js");
|
|
456
|
+
}
|
|
457
|
+
function transportMissing(entry, resolve) {
|
|
458
|
+
if (resolve("winston", entry) === void 0) return false;
|
|
459
|
+
const bundle = resolve(BUNDLE, entry);
|
|
460
|
+
if (bundle === void 0) return false;
|
|
461
|
+
const instrumentation = resolve(INSTRUMENTATION, bundle);
|
|
462
|
+
if (instrumentation === void 0) return false;
|
|
463
|
+
return resolve(TRANSPORT, instrumentation) === void 0;
|
|
464
|
+
}
|
|
465
|
+
function warnAboutMissingWinstonTransport(sendLogs, entry = entryFile(), resolve = resolveFrom) {
|
|
466
|
+
if (sendLogs && transportMissing(entry, resolve)) {
|
|
467
|
+
reportWarning({ code: "BYMAX_TELEMETRY_WINSTON_TRANSPORT_MISSING", text: MESSAGE });
|
|
468
|
+
}
|
|
469
|
+
}
|
|
423
470
|
|
|
424
471
|
// src/sdk/start.ts
|
|
425
472
|
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.";
|
|
@@ -505,6 +552,8 @@ async function boot(options, env) {
|
|
|
505
552
|
warnAboutUnsafeOptions(options);
|
|
506
553
|
warnAboutMissingServiceName(options, env);
|
|
507
554
|
warnAboutOversizedTimers(env);
|
|
555
|
+
warnAboutSamplerRatio(readRatioSampler());
|
|
556
|
+
warnAboutMissingWinstonTransport(options.instrumentations?.sendLogs ?? planSignals(env).sendLogs);
|
|
508
557
|
const sdk = buildSdk(await loadPackages(), options, env);
|
|
509
558
|
sdk.start();
|
|
510
559
|
const handle = createHandle(() => sdk.shutdown(), options.shutdownTimeoutMs);
|
package/dist/sdk/index.mjs
CHANGED
|
@@ -1,3 +1,6 @@
|
|
|
1
|
+
import { createRequire } from 'module';
|
|
2
|
+
import { join } from 'path';
|
|
3
|
+
|
|
1
4
|
// src/sdk/redaction.ts
|
|
2
5
|
var REDACTED_QUERY_VALUE = "[redacted]";
|
|
3
6
|
var URL_QUERY_ATTRIBUTE = "url.query";
|
|
@@ -265,6 +268,17 @@ function warnAboutUnsafeOptions(options) {
|
|
|
265
268
|
);
|
|
266
269
|
}
|
|
267
270
|
}
|
|
271
|
+
var SHOWN_VALUE_LENGTH = 40;
|
|
272
|
+
function warnAboutSamplerRatio(sampler) {
|
|
273
|
+
if (sampler === void 0) return;
|
|
274
|
+
const ratio = Number(sampler.arg);
|
|
275
|
+
if (ratio >= 0 && ratio <= 1) return;
|
|
276
|
+
const given = sampler.arg === void 0 ? "not set" : `${JSON.stringify(sampler.arg.slice(0, SHOWN_VALUE_LENGTH))}, which is not a number from 0 to 1`;
|
|
277
|
+
reportWarning({
|
|
278
|
+
code: "BYMAX_TELEMETRY_SAMPLER_ARG_INVALID",
|
|
279
|
+
text: `OTEL_TRACES_SAMPLER is ${sampler.name}, but OTEL_TRACES_SAMPLER_ARG is ${given}, so the SDK samples every trace. Set it to the share of traces to keep, from 0 to 1, such as 0.1.`
|
|
280
|
+
});
|
|
281
|
+
}
|
|
268
282
|
function warnAboutOversizedTimers(env) {
|
|
269
283
|
for (const name of env.oversizedTimers) {
|
|
270
284
|
process.emitWarning(
|
|
@@ -285,6 +299,7 @@ function warnAboutIgnoredOptions(options) {
|
|
|
285
299
|
|
|
286
300
|
// src/sdk/environment.ts
|
|
287
301
|
var MAX_TIMER_MS = 2147483647;
|
|
302
|
+
var RATIO_SAMPLERS = ["traceidratio", "parentbased_traceidratio"];
|
|
288
303
|
function readExporterList(raw) {
|
|
289
304
|
return (raw ?? "").split(",").map((name) => name.trim()).filter((name) => name !== "");
|
|
290
305
|
}
|
|
@@ -331,6 +346,11 @@ function readTelemetryEnvironment(source = process.env) {
|
|
|
331
346
|
resourceDetectors: detectors === void 0 || detectors.trim() === "" ? void 0 : readExporterList(detectors)
|
|
332
347
|
};
|
|
333
348
|
}
|
|
349
|
+
function readRatioSampler(source = process.env) {
|
|
350
|
+
const name = source["OTEL_TRACES_SAMPLER"];
|
|
351
|
+
const arg = source["OTEL_TRACES_SAMPLER_ARG"];
|
|
352
|
+
return name !== void 0 && RATIO_SAMPLERS.includes(name) ? { name, arg: arg?.trim() === "" ? void 0 : arg } : void 0;
|
|
353
|
+
}
|
|
334
354
|
|
|
335
355
|
// src/sdk/export-failure.ts
|
|
336
356
|
var WINDOW_MS = 6e4;
|
|
@@ -418,6 +438,33 @@ function selectResourceDetectors(selection, detectors, keeps) {
|
|
|
418
438
|
}
|
|
419
439
|
return [...new Set(chosen)].map((name) => available[name]);
|
|
420
440
|
}
|
|
441
|
+
var TRANSPORT = "@opentelemetry/winston-transport";
|
|
442
|
+
var BUNDLE = "@opentelemetry/auto-instrumentations-node";
|
|
443
|
+
var INSTRUMENTATION = "@opentelemetry/instrumentation-winston";
|
|
444
|
+
var MESSAGE = `Log forwarding is on and winston is installed, but ${TRANSPORT} cannot be resolved from ${INSTRUMENTATION}, so winston records will not reach the logs pipeline. Install ${TRANSPORT} as a direct dependency of the application, or set instrumentations.sendLogs to false. Ignore this if the application does not use winston.`;
|
|
445
|
+
var resolveFrom = (id, from) => {
|
|
446
|
+
try {
|
|
447
|
+
return createRequire(from).resolve(id);
|
|
448
|
+
} catch {
|
|
449
|
+
return void 0;
|
|
450
|
+
}
|
|
451
|
+
};
|
|
452
|
+
function entryFile(argv = process.argv, cwd = process.cwd()) {
|
|
453
|
+
return argv[1] ?? join(cwd, "entry.js");
|
|
454
|
+
}
|
|
455
|
+
function transportMissing(entry, resolve) {
|
|
456
|
+
if (resolve("winston", entry) === void 0) return false;
|
|
457
|
+
const bundle = resolve(BUNDLE, entry);
|
|
458
|
+
if (bundle === void 0) return false;
|
|
459
|
+
const instrumentation = resolve(INSTRUMENTATION, bundle);
|
|
460
|
+
if (instrumentation === void 0) return false;
|
|
461
|
+
return resolve(TRANSPORT, instrumentation) === void 0;
|
|
462
|
+
}
|
|
463
|
+
function warnAboutMissingWinstonTransport(sendLogs, entry = entryFile(), resolve = resolveFrom) {
|
|
464
|
+
if (sendLogs && transportMissing(entry, resolve)) {
|
|
465
|
+
reportWarning({ code: "BYMAX_TELEMETRY_WINSTON_TRANSPORT_MISSING", text: MESSAGE });
|
|
466
|
+
}
|
|
467
|
+
}
|
|
421
468
|
|
|
422
469
|
// src/sdk/start.ts
|
|
423
470
|
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.";
|
|
@@ -503,6 +550,8 @@ async function boot(options, env) {
|
|
|
503
550
|
warnAboutUnsafeOptions(options);
|
|
504
551
|
warnAboutMissingServiceName(options, env);
|
|
505
552
|
warnAboutOversizedTimers(env);
|
|
553
|
+
warnAboutSamplerRatio(readRatioSampler());
|
|
554
|
+
warnAboutMissingWinstonTransport(options.instrumentations?.sendLogs ?? planSignals(env).sendLogs);
|
|
506
555
|
const sdk = buildSdk(await loadPackages(), options, env);
|
|
507
556
|
sdk.start();
|
|
508
557
|
const handle = createHandle(() => sdk.shutdown(), options.shutdownTimeoutMs);
|
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.5",
|
|
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",
|
|
@@ -76,7 +76,8 @@
|
|
|
76
76
|
"check:file-length": "node scripts/check-file-length.mjs",
|
|
77
77
|
"clean": "rm -rf dist coverage",
|
|
78
78
|
"check:socket-gate": "node scripts/check-socket-gate.mjs",
|
|
79
|
-
"
|
|
79
|
+
"check:spec-headers": "node scripts/check-spec-headers.mjs",
|
|
80
|
+
"lint": "eslint src scripts test '*.config.ts' '*.config.mjs' '*.config.cjs' && pnpm check:socket-gate && pnpm check:spec-headers && node --test scripts/check-spec-headers.test.mjs",
|
|
80
81
|
"lint:fix": "eslint src scripts test '*.config.ts' '*.config.mjs' '*.config.cjs' --fix",
|
|
81
82
|
"mutation": "stryker run",
|
|
82
83
|
"mutation:full": "node -e \"require('node:fs').rmSync('reports/stryker-incremental.json',{force:true,recursive:true})\" && stryker run",
|
|
@@ -169,6 +170,7 @@
|
|
|
169
170
|
"@opentelemetry/resources": "^3.1.1",
|
|
170
171
|
"@opentelemetry/sdk-node": "^0.301.1",
|
|
171
172
|
"@opentelemetry/sdk-trace": "^3.1.1",
|
|
173
|
+
"@opentelemetry/winston-transport": "0.35.0",
|
|
172
174
|
"@stryker-mutator/core": "^9",
|
|
173
175
|
"@stryker-mutator/jest-runner": "^9",
|
|
174
176
|
"@stryker-mutator/typescript-checker": "^9",
|
|
@@ -192,14 +194,15 @@
|
|
|
192
194
|
"mysql2": "3.24.6",
|
|
193
195
|
"pino": "10.4.0",
|
|
194
196
|
"prettier": "^3.8.3",
|
|
195
|
-
"redis": "^
|
|
197
|
+
"redis": "^6.3.1",
|
|
196
198
|
"reflect-metadata": "^0.2.2",
|
|
197
199
|
"rxjs": "^7.8.0",
|
|
198
200
|
"supertest": "^7.2.2",
|
|
199
201
|
"ts-jest": "^29.4.9",
|
|
200
202
|
"ts-node": "^10.9.2",
|
|
201
203
|
"tsup": "^9.0.0",
|
|
202
|
-
"typescript": "^5.9.3"
|
|
204
|
+
"typescript": "^5.9.3",
|
|
205
|
+
"winston": "3.19.0"
|
|
203
206
|
},
|
|
204
207
|
"keywords": [
|
|
205
208
|
"nestjs",
|