@bymax-one/nest-telemetry 1.0.0 → 1.0.2
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 +73 -1
- package/README.md +307 -144
- package/dist/nest/index.cjs +1 -0
- package/dist/nest/index.d.cts +3 -3
- package/dist/nest/index.d.ts +3 -3
- package/dist/nest/index.mjs +2 -1
- package/dist/register/index.mjs +31 -8
- package/dist/sdk/index.cjs +31 -8
- package/dist/sdk/index.mjs +31 -8
- package/package.json +3 -1
package/CHANGELOG.md
CHANGED
|
@@ -8,7 +8,77 @@ 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
|
-
## [1.0.
|
|
11
|
+
## [1.0.2] - 2026-11-13
|
|
12
|
+
|
|
13
|
+
### Security
|
|
14
|
+
|
|
15
|
+
- **node-redis command arguments and keys no longer reach `db.query.text`.** The command-name serializer
|
|
16
|
+
was applied to `instrumentation-ioredis` only, so `instrumentation-redis` kept the default one: an
|
|
17
|
+
`EVAL` argument and a key were exported on node-redis 3.1.2, 4.7.1, 5.12.2 and 6.3.1. Both
|
|
18
|
+
instrumentations now export the command name only, behind the same
|
|
19
|
+
`unsafe.disableRedisArgumentRedaction`, and a host override cannot replace the serializer of either.
|
|
20
|
+
|
|
21
|
+
### Fixed
|
|
22
|
+
|
|
23
|
+
- `OTEL_SDK_DISABLED` is read as the SDK reads it, trimmed. A value such as `"true "` or `" TRUE"`
|
|
24
|
+
made the library load the loader hook and every OpenTelemetry package and report `enabled: true`,
|
|
25
|
+
while the SDK itself did nothing.
|
|
26
|
+
- A later `startTelemetry` call against a running SDK no longer drops its options silently: see the
|
|
27
|
+
warning below.
|
|
28
|
+
|
|
29
|
+
### Added
|
|
30
|
+
|
|
31
|
+
- `BYMAX_TELEMETRY_OPTIONS_IGNORED`: a `startTelemetry` call reached an SDK that was already running, so its
|
|
32
|
+
options were ignored, or `enabled: false` did not stop it. Any defined option counts, `env` included, and a
|
|
33
|
+
call that passes none stays silent.
|
|
34
|
+
- `BYMAX_TELEMETRY_RESTART_UNSUPPORTED`: see below.
|
|
35
|
+
|
|
36
|
+
### Changed
|
|
37
|
+
|
|
38
|
+
- **A start after a shutdown in the same process is refused.** `startTelemetry` rejects with an error that
|
|
39
|
+
says to start once per process, and once in a global setup for a test suite, and the process emits
|
|
40
|
+
`BYMAX_TELEMETRY_RESTART_UNSUPPORTED`; the preload turns it into its start-failed warning. Auto-instrumented
|
|
41
|
+
spans can never resume after a shutdown in the same process, because the modules are already patched;
|
|
42
|
+
spans created through the API could, but a half-working restart is refused on purpose. Before, the second
|
|
43
|
+
start reported `enabled: true` and exported nothing. A test suite that started one SDK per case now has to
|
|
44
|
+
start once.
|
|
45
|
+
- The README names both Redis clients, says which one needs an active span, states what was measured about
|
|
46
|
+
mysql2 bound values, and lists the identifiers the library does not redact. A canary in the runtime proofs
|
|
47
|
+
fails if a bound mysql2 value ever reaches `db.query.text`.
|
|
48
|
+
|
|
49
|
+
### Shutdown order of `TelemetryModule`
|
|
50
|
+
|
|
51
|
+
`TelemetryModule` is now global, so its shutdown hook runs among the last. A span that another global module
|
|
52
|
+
ends in its own shutdown hook, such as a queue drain, is now exported when `TelemetryModule` is listed first in
|
|
53
|
+
the application module's imports, and was dropped before. Nest closes global modules in the reverse of the
|
|
54
|
+
order it registers them, so list it before any module that is global or imports a global module. Applications
|
|
55
|
+
that provided `TelemetryShutdownHook` in a module of their own to get this order can import the module.
|
|
56
|
+
|
|
57
|
+
### Apply to a derived backend
|
|
58
|
+
|
|
59
|
+
The declarations did not change; four behaviours did, and a derived backend acts on them:
|
|
60
|
+
|
|
61
|
+
1. A start after a shutdown in the same process now throws. Start telemetry once per process, and in a
|
|
62
|
+
test suite start it once in a global setup.
|
|
63
|
+
2. `TelemetryModule` is global. List it **first** in the application module's imports, so its flush runs
|
|
64
|
+
last; a module of your own that only provided `TelemetryShutdownHook` to get that order can import it.
|
|
65
|
+
3. `OTEL_SDK_DISABLED` is trimmed as the SDK trims it, so a padded `" true "` now really disables.
|
|
66
|
+
4. node-redis spans now carry the command name only. A dashboard or alert that matched node-redis
|
|
67
|
+
arguments or keys in `db.query.text` has to change.
|
|
68
|
+
|
|
69
|
+
## [1.0.1] - 2026-11-12
|
|
70
|
+
|
|
71
|
+
Documentation only; the built files are the same as in 1.0.0.
|
|
72
|
+
|
|
73
|
+
### Changed
|
|
74
|
+
|
|
75
|
+
- The changelog dates 1.0.0, which the published package still lists as unreleased.
|
|
76
|
+
- The README follows the structure of the other `@bymax-one` libraries. Its claims are those of 1.0.0,
|
|
77
|
+
and a `service.name` set only in `OTEL_RESOURCE_ATTRIBUTES` reaches the spans while the `env`
|
|
78
|
+
or `service` resource detector is enabled, and the missing-service-name warning still fires.
|
|
79
|
+
- `docs/mutation_testing_results.md` records the cold mutation run that gated 1.0.0.
|
|
80
|
+
|
|
81
|
+
## [1.0.0] - 2026-11-12
|
|
12
82
|
|
|
13
83
|
First release.
|
|
14
84
|
|
|
@@ -43,4 +113,6 @@ First release.
|
|
|
43
113
|
- Verification from the packed tarball: real `node --import` processes in a CommonJS and a native-ESM
|
|
44
114
|
application, with planted secrets absent from the exported body and negative controls.
|
|
45
115
|
|
|
116
|
+
[1.0.2]: https://github.com/bymaxone/nest-telemetry/releases/tag/v1.0.2
|
|
117
|
+
[1.0.1]: https://github.com/bymaxone/nest-telemetry/releases/tag/v1.0.1
|
|
46
118
|
[1.0.0]: https://github.com/bymaxone/nest-telemetry/releases/tag/v1.0.0
|
package/README.md
CHANGED
|
@@ -1,29 +1,99 @@
|
|
|
1
|
-
|
|
1
|
+
<p align="center">
|
|
2
|
+
<img src="https://img.shields.io/badge/%40bymax--one-nest--telemetry-000000?style=for-the-badge&logo=opentelemetry&logoColor=F5A800" alt="@bymax-one/nest-telemetry" />
|
|
3
|
+
</p>
|
|
2
4
|
|
|
3
|
-
|
|
5
|
+
<h1 align="center">@bymax-one/nest-telemetry</h1>
|
|
4
6
|
|
|
5
|
-
|
|
7
|
+
<p align="center">
|
|
8
|
+
<strong>OpenTelemetry tracing for NestJS 11 and plain Node</strong><br />
|
|
9
|
+
<sub>Preload · Span Redaction · Native ESM · Graceful Flush · Zero Runtime Dependencies</sub>
|
|
10
|
+
</p>
|
|
6
11
|
|
|
7
|
-
|
|
12
|
+
<p align="center">
|
|
13
|
+
<a href="https://www.npmjs.com/package/@bymax-one/nest-telemetry"><img src="https://img.shields.io/npm/v/@bymax-one/nest-telemetry?style=flat-square&colorA=000000&colorB=000000" alt="npm version" /></a>
|
|
14
|
+
<a href="https://www.npmjs.com/package/@bymax-one/nest-telemetry"><img src="https://img.shields.io/npm/dm/@bymax-one/nest-telemetry?style=flat-square&colorA=000000&colorB=000000" alt="npm downloads" /></a>
|
|
15
|
+
<a href="https://github.com/bymaxone/nest-telemetry/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/bymaxone/nest-telemetry/ci.yml?branch=main&style=flat-square&colorA=000000&label=CI" alt="CI status" /></a>
|
|
16
|
+
<a href="https://github.com/bymaxone/nest-telemetry/actions/workflows/ci.yml"><img src="https://img.shields.io/badge/coverage-100%25-brightgreen?style=flat-square&colorA=000000" alt="coverage" /></a>
|
|
17
|
+
<a href="https://github.com/bymaxone/nest-telemetry/blob/main/docs/mutation_testing_results.md"><img src="https://img.shields.io/badge/mutation-100%25-brightgreen?style=flat-square&colorA=000000" alt="mutation score" /></a>
|
|
18
|
+
<a href="https://scorecard.dev/viewer/?uri=github.com/bymaxone/nest-telemetry"><img src="https://api.scorecard.dev/projects/github.com/bymaxone/nest-telemetry/badge?style=flat-square" alt="OpenSSF Scorecard" /></a>
|
|
19
|
+
<a href="https://github.com/bymaxone/nest-telemetry/blob/main/LICENSE"><img src="https://img.shields.io/github/license/bymaxone/nest-telemetry?style=flat-square&colorA=000000&colorB=000000" alt="license" /></a>
|
|
20
|
+
<a href="https://www.typescriptlang.org/"><img src="https://img.shields.io/badge/TypeScript-strict-3178C6?style=flat-square&logo=typescript&logoColor=white" alt="TypeScript" /></a>
|
|
21
|
+
<a href="https://nodejs.org/"><img src="https://img.shields.io/badge/Node.js-24%2B-339933?style=flat-square&logo=node.js&logoColor=white" alt="Node.js" /></a>
|
|
22
|
+
</p>
|
|
8
23
|
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
24
|
+
<p align="center">
|
|
25
|
+
<a href="https://github.com/bymaxone/nest-telemetry">GitHub</a> ·
|
|
26
|
+
<a href="https://github.com/bymaxone/nest-telemetry/issues">Issues</a> ·
|
|
27
|
+
<a href="#-quick-start">Quick Start</a> ·
|
|
28
|
+
<a href="#-api-reference">API Reference</a>
|
|
29
|
+
</p>
|
|
15
30
|
|
|
16
|
-
|
|
31
|
+
---
|
|
32
|
+
|
|
33
|
+
## ✨ Overview
|
|
34
|
+
|
|
35
|
+
`@bymax-one/nest-telemetry` starts the OpenTelemetry SDK before your application loads, redacts secrets from spans by default (URL query strings, Redis arguments, the process command line), keeps probe paths out of your traces and flushes on shutdown. It ships as a single npm package with **subpath exports**: an SDK part that works from plain Node, a `node --import` preload, and a NestJS module.
|
|
36
|
+
|
|
37
|
+
Every `@opentelemetry/*` package is an **optional peer dependency**, and a boot with telemetry disabled loads none of them. The library is the mechanism; the host application keeps the policy: whether tracing is on, which paths are probes, what the service is called.
|
|
38
|
+
|
|
39
|
+
### Support matrix
|
|
40
|
+
|
|
41
|
+
| Part | Supported |
|
|
42
|
+
| ------------------------ | ------------------------------------------------------------- |
|
|
43
|
+
| Node.js | 24 or newer |
|
|
44
|
+
| NestJS (`./nest` only) | 11 |
|
|
45
|
+
| Applications | CommonJS and native ES modules |
|
|
46
|
+
| OpenTelemetry generation | The one in [OpenTelemetry Versions](#-opentelemetry-versions) |
|
|
17
47
|
|
|
18
48
|
**Native ES modules.** Auto-instrumentation patches CommonJS modules as they load, and native ES modules only through a loader hook. The preload registers that hook, and it needs the optional peer `@opentelemetry/instrumentation`. Without that package, a native-ESM application gets no auto-instrumentation at all; CommonJS code is unaffected, and the start warns (`BYMAX_TELEMETRY_ESM_HOOK_UNAVAILABLE`) so the gap is not silent. Measured on real consumers: an ESM application with the SDK started and no hook exported no HTTP span; with the hook it did.
|
|
19
49
|
|
|
20
|
-
|
|
50
|
+
### Why nest-telemetry?
|
|
51
|
+
|
|
52
|
+
- **💤 Zero cost when disabled** — A boot with `OTEL_SDK_DISABLED=true` registers no loader hook and loads no OpenTelemetry package, `@opentelemetry/api` included; this is checked from the packed tarball in ESM and CommonJS, with a positive control that proves the check can fail.
|
|
53
|
+
- **🔒 Secret-safe by default** — Span data is a leak surface, so URL query strings, Redis arguments and the process command line are redacted unless an explicit option, which also warns, turns one off. No environment variable does.
|
|
54
|
+
- **🚦 Preload ordering done right** — The SDK has to start before the libraries it instruments load, and `main.ts` is too late; a `node --import` preload runs first and reads only the standard `OTEL_*` variables.
|
|
55
|
+
- **🔌 Your policy, your rules** — Enabling, probe paths, service name and version, extra redacted parameters and the structured logger are passed in.
|
|
56
|
+
|
|
57
|
+
Install it with the OpenTelemetry peers you use: the command is in [Quick Start](#-quick-start).
|
|
58
|
+
|
|
59
|
+
---
|
|
60
|
+
|
|
61
|
+
## 🔥 Features
|
|
62
|
+
|
|
63
|
+
### 🚦 Boot and lifecycle
|
|
64
|
+
|
|
65
|
+
- ✅ **`node --import` preload** — Registers the ES-module loader hook, starts the SDK from the standard variables and flushes on a natural exit
|
|
66
|
+
- ✅ **One SDK per process** — The handle lives under a `Symbol.for` key on `globalThis`, so an ES-module preload and a CommonJS application share it, and a second start returns the one already running
|
|
67
|
+
- ✅ **Graceful Nest shutdown** — `TelemetryModule` awaits the flush as part of the application's own shutdown, under the stable failure key `TRACING_FLUSH_FAILED`
|
|
68
|
+
- ✅ **Never takes the host down** — Each failure the preload can meet is a warning and the application still starts; a flush the collector refuses is reported by the Nest module, never thrown into your shutdown path
|
|
69
|
+
|
|
70
|
+
### 🔐 Redaction
|
|
71
|
+
|
|
72
|
+
- ✅ **Span-end query redaction** — `url.query` is replaced and the query is cut from `url.full`, `http.url` and `http.target`, on spans from any instrumentation
|
|
73
|
+
- ✅ **Outgoing-URL credential list** — A list of credential-bearing parameters, checked in a test against the SDK's own default list; a host can add names and never drop them
|
|
74
|
+
- ✅ **Redis commands reduced to their name** — for `ioredis` and node-redis (`redis`), arguments and keys never leave the process, `EVAL` and `EVALSHA` payloads included
|
|
75
|
+
- ✅ **Command line kept out of the resource** — `process.command_args` and `process.command_line` are dropped
|
|
76
|
+
- ✅ **Explicit, loud opt-outs** — Each off switch is a literal `unsafe.*: true` and emits a `SecurityWarning`
|
|
77
|
+
|
|
78
|
+
---
|
|
21
79
|
|
|
22
|
-
|
|
23
|
-
- **Secret-safe by default.** Span data is a leak surface: a magic-link token in a query string, a Redis `EVAL` payload, a secret in a command line. Each is redacted by default, and turning one off takes an explicit option that also emits a warning. There is no environment variable that turns redaction off.
|
|
24
|
-
- **Preload ordering done right.** The SDK has to start before the libraries it instruments are loaded, and starting it from `main.ts` is too late. A `node --import` preload runs first, and this package ships one that reads only the standard `OTEL_*` variables.
|
|
80
|
+
## 📦 Subpath Exports
|
|
25
81
|
|
|
26
|
-
|
|
82
|
+
One package, separate entry points. Import only what your app needs:
|
|
83
|
+
|
|
84
|
+
| Subpath | Import | Purpose | Dependencies |
|
|
85
|
+
| ------------ | ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------- | :-----------------: |
|
|
86
|
+
| **SDK** | `@bymax-one/nest-telemetry` | `startTelemetry`, `shutdownTelemetry`, `ignorePaths`, `DEFAULT_REDACTED_QUERY_PARAMS`, types | OpenTelemetry peers |
|
|
87
|
+
| **Register** | `@bymax-one/nest-telemetry/register` | The preload for `node --import`; importing it runs it, and it exports nothing | OpenTelemetry peers |
|
|
88
|
+
| **Nest** | `@bymax-one/nest-telemetry/nest` | `TelemetryModule`, `TelemetryShutdownHook`, `TELEMETRY_LOGGER`, `TELEMETRY_FLUSH_FAILED_KEY`, `ITelemetryErrorLogger` (type) | NestJS 11 |
|
|
89
|
+
|
|
90
|
+
The SDK entry and `./register` import no `@nestjs/*` package; only `./nest` does. Requiring `./register` from CommonJS throws and names `node --import`.
|
|
91
|
+
|
|
92
|
+
---
|
|
93
|
+
|
|
94
|
+
## 🚀 Quick Start
|
|
95
|
+
|
|
96
|
+
### NestJS
|
|
27
97
|
|
|
28
98
|
Install the package and the OpenTelemetry peers you use:
|
|
29
99
|
|
|
@@ -58,13 +128,15 @@ import { TelemetryModule } from '@bymax-one/nest-telemetry/nest'
|
|
|
58
128
|
export class AppModule {}
|
|
59
129
|
```
|
|
60
130
|
|
|
131
|
+
`TelemetryModule` is global, and Nest closes global modules last, in the reverse of the order it registers them. List it **first** in the application module's imports, before any module that is global or that imports a global module, so it closes after them: a span that another global module, such as a queue drain or a database module, ends in its own shutdown hook is exported only if `TelemetryModule` was registered first. Measured with Nest 11: listed first, the span arrives whether the other global module is imported directly or through a feature module; listed after a feature module that imports a global module, or after the global module itself, the span is dropped.
|
|
132
|
+
|
|
61
133
|
Things to know before you rely on it:
|
|
62
134
|
|
|
63
135
|
1. **Traces only, by default.** Metrics and logs stay off unless `OTEL_METRICS_EXPORTER` or `OTEL_LOGS_EXPORTER` names an exporter. This departs from the OpenTelemetry default, which exports both through OTLP, and it does so on purpose: otherwise a host that already ships metrics and logs another way would send them twice.
|
|
64
|
-
2. **Name your service.** With neither `OTEL_SERVICE_NAME` nor a `serviceName` option, the start warns once (`BYMAX_TELEMETRY_SERVICE_NAME_MISSING`) and spans are exported as `unknown_service:node`, which groups unrelated services under one name. The start is never refused.
|
|
136
|
+
2. **Name your service.** With neither `OTEL_SERVICE_NAME` nor a `serviceName` option, the start warns once (`BYMAX_TELEMETRY_SERVICE_NAME_MISSING`) and spans are exported as `unknown_service:node`, which groups unrelated services under one name. A `service.name` set only in `OTEL_RESOURCE_ATTRIBUTES` is honoured and the spans carry it while the `env` or `service` resource detector is enabled, as every detector is by default, but the warning still fires, because the library looks only at `OTEL_SERVICE_NAME` and the option; set `OTEL_SERVICE_NAME` to silence it. The start is never refused.
|
|
65
137
|
3. **Signals.** The preload flushes when the process runs out of work. It installs no signal handler, because a handler in the preload would race the application's own shutdown. In Nest, call `app.enableShutdownHooks()` so `SIGTERM` closes the application, and the module flushes the SDK. In plain Node, call `shutdownTelemetry()` yourself.
|
|
66
138
|
|
|
67
|
-
|
|
139
|
+
### Plain Node
|
|
68
140
|
|
|
69
141
|
The SDK part never imports `@nestjs/*`. Start it from your own preload, or from the first lines of your entry point if nothing instrumented has been imported yet:
|
|
70
142
|
|
|
@@ -83,135 +155,144 @@ const telemetry = await startTelemetry({
|
|
|
83
155
|
await telemetry.shutdown()
|
|
84
156
|
```
|
|
85
157
|
|
|
86
|
-
This package installs no signal handler and shows none, because handling signals belongs to the application: a `SIGTERM` listener replaces Node's default termination, so it has to end the process itself once its work is done. `startTelemetry` resolves to a handle with `enabled` and `shutdown()`. Starting twice returns the handle already running, including across two copies of the module (an ES-module preload and a CommonJS application share the handle through `globalThis`).
|
|
158
|
+
This package installs no signal handler and shows none, because handling signals belongs to the application: a `SIGTERM` listener replaces Node's default termination, so it has to end the process itself once its work is done. `startTelemetry` resolves to a handle with `enabled` and `shutdown()`. Starting twice returns the handle already running, including across two copies of the module (an ES-module preload and a CommonJS application share the handle through `globalThis`). A later call that passes options is told they were ignored, and `enabled: false` against a running SDK is told it does not stop it: `shutdownTelemetry()` does.
|
|
87
159
|
|
|
88
|
-
|
|
160
|
+
---
|
|
89
161
|
|
|
90
|
-
|
|
162
|
+
## ⚙️ Configuration
|
|
91
163
|
|
|
92
|
-
|
|
93
|
-
- its probe paths become `ignoreIncomingRequest: ignorePaths(...)`;
|
|
94
|
-
- its service name and version variables become `serviceName` and `serviceVersion`, with `OTEL_SERVICE_NAME` still overriding;
|
|
95
|
-
- `TELEMETRY_LOGGER` is bound to its structured logger, so a failed flush keeps arriving under the key `TRACING_FLUSH_FAILED` that alerts already match.
|
|
164
|
+
### `startTelemetry(options)`
|
|
96
165
|
|
|
97
|
-
|
|
166
|
+
Every field is the host's policy, and none is required.
|
|
98
167
|
|
|
99
|
-
|
|
100
|
-
|
|
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 pino's records 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` and `process.command_line` in the resource. Literal `true`. Warns. |
|
|
181
|
+
| `env` | the process environment | The environment the library reads. The OpenTelemetry SDK itself always reads the process environment. |
|
|
101
182
|
|
|
102
|
-
|
|
183
|
+
### Environment variables
|
|
103
184
|
|
|
104
|
-
|
|
105
|
-
errorStructured(logKey: string, error: Error): void {
|
|
106
|
-
console.error(logKey, error.message)
|
|
107
|
-
}
|
|
108
|
-
}
|
|
185
|
+
The library reads these in one source file, and a test fails if any other file names `process.env`:
|
|
109
186
|
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
187
|
+
| Variable | Effect |
|
|
188
|
+
| ----------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
|
|
189
|
+
| `OTEL_SDK_DISABLED` | `true` disables the SDK, in any letter case and with surrounding whitespace ignored, as the SDK reads it. |
|
|
190
|
+
| `OTEL_SERVICE_NAME` | Service name; overrides the option, because the operator's standard variable wins over what the code chose. Blank values count as absent. |
|
|
191
|
+
| `OTEL_METRICS_EXPORTER`, `OTEL_LOGS_EXPORTER` | Metrics and logs are exported only when these name an exporter. |
|
|
192
|
+
| `OTEL_BSP_MAX_QUEUE_SIZE`, `OTEL_BSP_SCHEDULE_DELAY`, `OTEL_BSP_EXPORT_TIMEOUT`, `OTEL_BSP_MAX_EXPORT_BATCH_SIZE` | Mapped onto the batch span processor the library passes; the SDK applies them only to one it builds itself. |
|
|
193
|
+
| `OTEL_NODE_RESOURCE_DETECTORS` | Selects resource detectors, under the specification's names (`service`, `host`, `process`) and the SDK's older ones. |
|
|
116
194
|
|
|
117
|
-
|
|
195
|
+
The OpenTelemetry SDK reads these itself, and the library never touches them: `OTEL_EXPORTER_OTLP_*`, `OTEL_TRACES_SAMPLER` and `OTEL_TRACES_SAMPLER_ARG`, `OTEL_RESOURCE_ATTRIBUTES`.
|
|
118
196
|
|
|
119
|
-
|
|
197
|
+
---
|
|
120
198
|
|
|
121
|
-
|
|
199
|
+
## 🧭 How It Behaves
|
|
122
200
|
|
|
123
201
|
### The preload
|
|
124
202
|
|
|
125
203
|
`./register` is for `node --import`. It registers the loader hook, starts the SDK from the standard variables and flushes on a natural exit. It is ES-module only in substance: requiring it from CommonJS throws and names `node --import`, because starting the SDK is asynchronous and a `--require` preload cannot wait for it, which would let the application load first, unnoticed.
|
|
126
204
|
|
|
127
|
-
|
|
205
|
+
The start emits these warnings:
|
|
128
206
|
|
|
129
|
-
| Code | Meaning
|
|
130
|
-
| ------------------------------------------- |
|
|
131
|
-
| `BYMAX_TELEMETRY_START_FAILED` | The SDK could not start (a peer is missing, or the SDK threw). Tracing is off.
|
|
132
|
-
| `BYMAX_TELEMETRY_ESM_HOOK_UNAVAILABLE` | The loader hook could not be registered. Native-ESM code is not instrumented.
|
|
133
|
-
| `BYMAX_TELEMETRY_SERVICE_NAME_MISSING` | No service name is set; spans use `unknown_service:node`.
|
|
134
|
-
| `BYMAX_TELEMETRY_UNSAFE_REDACTION_DISABLED` | A redaction was turned off through an `unsafe` option.
|
|
207
|
+
| Code | Meaning |
|
|
208
|
+
| ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
209
|
+
| `BYMAX_TELEMETRY_START_FAILED` | The SDK could not start (a peer is missing, or the SDK threw). Tracing is off. |
|
|
210
|
+
| `BYMAX_TELEMETRY_ESM_HOOK_UNAVAILABLE` | The loader hook could not be registered. Native-ESM code is not instrumented. |
|
|
211
|
+
| `BYMAX_TELEMETRY_SERVICE_NAME_MISSING` | No service name is set; spans use `unknown_service:node`. |
|
|
212
|
+
| `BYMAX_TELEMETRY_UNSAFE_REDACTION_DISABLED` | A redaction was turned off through an `unsafe` option. |
|
|
213
|
+
| `BYMAX_TELEMETRY_OPTIONS_IGNORED` | A `startTelemetry` call reached an SDK that was already running, so its options were ignored, or `enabled: false` did not stop it. Any defined option counts, `env` included. |
|
|
214
|
+
| `BYMAX_TELEMETRY_RESTART_UNSUPPORTED` | `startTelemetry` was called after a shutdown in the same process, and is refused. |
|
|
135
215
|
|
|
136
216
|
The programmatic `startTelemetry` keeps its rejection when the SDK cannot start, for callers that want it.
|
|
137
217
|
|
|
138
218
|
### What is traced
|
|
139
219
|
|
|
140
220
|
- **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.
|
|
141
|
-
-
|
|
221
|
+
- **`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.
|
|
142
222
|
- **`fs` instrumentation is off by default**, because it floods traces with disk activity that has no context. Turn it on with `instrumentations.fs`.
|
|
143
223
|
|
|
144
224
|
### Flushing
|
|
145
225
|
|
|
146
226
|
Awaiting `shutdown()` or `shutdownTelemetry()` means the spans were exported, whoever started the flush: 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.
|
|
147
227
|
|
|
148
|
-
|
|
228
|
+
A start after a shutdown in the same process is refused: `startTelemetry` rejects, with an error that says to start once per process (in a test suite, once in a global setup), and the process emits `BYMAX_TELEMETRY_RESTART_UNSUPPORTED`. Auto-instrumented spans can never resume after a shutdown, because the modules the first start instrumented are already patched against its tracer provider; spans created through the API could, but a half-working restart is refused on purpose. Measured with an in-process HTTP request and one manual span per run: after a restart that released the API globals, the manual span was exported and the HTTP spans were not. The preload turns the refusal into a `BYMAX_TELEMETRY_START_FAILED` warning and the application still boots.
|
|
149
229
|
|
|
150
|
-
|
|
230
|
+
---
|
|
151
231
|
|
|
152
|
-
|
|
153
|
-
| -------------------------------------- | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
|
|
154
|
-
| `enabled` | `true` | `false` never starts the SDK. `OTEL_SDK_DISABLED=true` disables it regardless. |
|
|
155
|
-
| `serviceName` | `unknown_service:node` | The service name. `OTEL_SERVICE_NAME` overrides it. |
|
|
156
|
-
| `serviceVersion` | none | The service version. |
|
|
157
|
-
| `ignoreIncomingRequest` | none | Returns `true` for an incoming request that must produce no server span. `ignorePaths(patterns)` builds one from anchored patterns. |
|
|
158
|
-
| `instrumentations.fs` | `false` | File-system instrumentation. |
|
|
159
|
-
| `instrumentations.sendLogs` | follows `OTEL_LOGS_EXPORTER` | Whether pino's records are forwarded to the OpenTelemetry logs pipeline. |
|
|
160
|
-
| `instrumentations.overrides` | none | Per-instrumentation configuration, merged over the library's. Redaction settings cannot be replaced here. |
|
|
161
|
-
| `extraRedactedQueryParams` | none | Names added to the list redacted from outgoing request URLs. They add to the defaults and never replace them. |
|
|
162
|
-
| `unsafe.disableUrlRedaction` | off | Keeps `url.query`, `url.full`, `http.url` and `http.target` as recorded. Literal `true`. Warns. |
|
|
163
|
-
| `unsafe.disableRedisArgumentRedaction` | off | Keeps Redis command arguments in `db.query.text`. Literal `true`. Warns. |
|
|
164
|
-
| `unsafe.exportProcessCommandArgs` | off | Keeps `process.command_args` and `process.command_line` in the resource. Literal `true`. Warns. |
|
|
165
|
-
| `env` | the process environment | The environment the library reads. The OpenTelemetry SDK itself always reads the process environment. |
|
|
232
|
+
## 🔄 OpenTelemetry Versions
|
|
166
233
|
|
|
167
|
-
|
|
234
|
+
Every `@opentelemetry/*` package is an optional peer. The `0.x` packages break between minors, and `sdk-node` pins its own dependencies to exact versions, so the ranges here name only the generation the tests run against:
|
|
168
235
|
|
|
169
|
-
|
|
236
|
+
| Package | Range |
|
|
237
|
+
| ------------------------------------------- | ---------- |
|
|
238
|
+
| `@opentelemetry/api` | `^1.10.0` |
|
|
239
|
+
| `@opentelemetry/sdk-node` | `^0.301.0` |
|
|
240
|
+
| `@opentelemetry/exporter-trace-otlp-http` | `^0.301.0` |
|
|
241
|
+
| `@opentelemetry/instrumentation` | `^0.301.0` |
|
|
242
|
+
| `@opentelemetry/sdk-trace` | `^3.1.0` |
|
|
243
|
+
| `@opentelemetry/resources` | `^3.1.0` |
|
|
244
|
+
| `@opentelemetry/auto-instrumentations-node` | `^0.83.0` |
|
|
170
245
|
|
|
171
|
-
|
|
172
|
-
| ----------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
|
|
173
|
-
| `OTEL_SDK_DISABLED` | `true` (any letter case) disables the SDK. |
|
|
174
|
-
| `OTEL_SERVICE_NAME` | Service name; overrides the option. |
|
|
175
|
-
| `OTEL_METRICS_EXPORTER`, `OTEL_LOGS_EXPORTER` | Metrics and logs are exported only when these name an exporter. |
|
|
176
|
-
| `OTEL_BSP_MAX_QUEUE_SIZE`, `OTEL_BSP_SCHEDULE_DELAY`, `OTEL_BSP_EXPORT_TIMEOUT`, `OTEL_BSP_MAX_EXPORT_BATCH_SIZE` | Mapped onto the batch span processor the library passes; the SDK applies them only to one it builds itself. |
|
|
177
|
-
| `OTEL_NODE_RESOURCE_DETECTORS` | Selects resource detectors, under the specification's names (`service`, `host`, `process`) and the SDK's older ones. |
|
|
246
|
+
A caret on a `0.x` version allows patch releases only, so each OpenTelemetry minor needs a release of this package to widen the range. That is a human decision: a weekly job runs the unit and end-to-end suites, the build and the tarball checks against the newest release of every OpenTelemetry package, ignoring the lockfile, and opens an issue when they fail. A range is widened in a pull request after the job passes against the new generation. Dependabot groups the OpenTelemetry packages, so they move as one set.
|
|
178
247
|
|
|
179
|
-
|
|
248
|
+
---
|
|
180
249
|
|
|
181
|
-
|
|
250
|
+
## 🩺 Troubleshooting
|
|
182
251
|
|
|
183
|
-
|
|
|
184
|
-
|
|
|
185
|
-
|
|
|
186
|
-
|
|
|
187
|
-
|
|
|
252
|
+
| You see | Look at |
|
|
253
|
+
| --------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
254
|
+
| No spans at all | `OTEL_SDK_DISABLED`; that the application was started with `--import`; `OTEL_EXPORTER_OTLP_ENDPOINT`; the start warnings. |
|
|
255
|
+
| Spans from a CommonJS app but none from a native-ESM app | `BYMAX_TELEMETRY_ESM_HOOK_UNAVAILABLE`: install `@opentelemetry/instrumentation`. |
|
|
256
|
+
| 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. |
|
|
257
|
+
| `BYMAX_TELEMETRY_START_FAILED` | The warning names the cause, usually an OpenTelemetry peer that is not installed. |
|
|
258
|
+
| HTTP spans but no Redis spans | `ioredis` commands are traced under an active span only, and the client must be loaded after the preload. |
|
|
259
|
+
| Metrics or logs missing | They are off unless `OTEL_METRICS_EXPORTER` or `OTEL_LOGS_EXPORTER` names an exporter. |
|
|
260
|
+
| 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. |
|
|
261
|
+
| The last spans are lost on `SIGTERM` | Call `app.enableShutdownHooks()` in Nest, or `shutdownTelemetry()` from your own shutdown path. |
|
|
262
|
+
| A query string still appears in a span | It is on an attribute other than `url.query`, `url.full`, `http.url` or `http.target`: see [What This Library Does NOT Do](#-what-this-library-does-not-do). |
|
|
188
263
|
|
|
189
|
-
|
|
264
|
+
---
|
|
190
265
|
|
|
191
|
-
|
|
266
|
+
## 🏗️ Architecture
|
|
192
267
|
|
|
193
|
-
|
|
268
|
+
```
|
|
269
|
+
node --import @bymax-one/nest-telemetry/register
|
|
270
|
+
→ Preload registers the ES-module loader hook, then starts the SDK from the
|
|
271
|
+
standard OTEL_* variables; a failure is a warning
|
|
272
|
+
→ startTelemetry(options)
|
|
273
|
+
disabled? returns a no-op handle and loads no OpenTelemetry package
|
|
274
|
+
→ Assembly resource attributes, instrumentation configuration with the redaction
|
|
275
|
+
applied on top of the host's overrides, signal plan (traces only unless
|
|
276
|
+
an exporter is named)
|
|
277
|
+
→ NodeSDK resource detectors (OTEL_NODE_RESOURCE_DETECTORS), a batch span processor
|
|
278
|
+
and a span processor that redacts URL attributes as each span ends
|
|
279
|
+
→ Handle stored under a Symbol.for key on globalThis: one SDK per process,
|
|
280
|
+
one shared flush
|
|
281
|
+
→ Application code (traced)
|
|
282
|
+
→ TelemetryShutdownHook
|
|
283
|
+
Nest's OnApplicationShutdown awaits shutdownTelemetry(); a refused flush
|
|
284
|
+
is reported under TRACING_FLUSH_FAILED
|
|
285
|
+
```
|
|
194
286
|
|
|
195
|
-
|
|
196
|
-
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
197
|
-
| Span end, every span | `url.query` is replaced by `[redacted]`, and the query is cut from `url.full`, `http.url` and `http.target`. It runs on spans from any instrumentation, not only HTTP. |
|
|
198
|
-
| Outgoing request URLs | The HTTP instrumentation redacts a list of credential-bearing parameters (`token`, `code`, `access_token`, `signature`, `X-Amz-*`, and more). A host can add names, not drop them. The list is compared in a test with the SDK's own default list, so a name the SDK adds later is caught. |
|
|
199
|
-
| Redis | `db.query.text` holds the command name only. `EVAL` and `EVALSHA` payloads, which carry `KEYS` and `ARGV`, never leave the process. |
|
|
200
|
-
| Resource | `process.command_args` and `process.command_line` are left out, because command-line arguments are a common carrier of secrets. |
|
|
287
|
+
The SDK part is plain functions over the OpenTelemetry packages, loaded on demand with dynamic imports so a disabled boot touches none of them. The environment is read in one module and handed to everything else as a parameter.
|
|
201
288
|
|
|
202
|
-
|
|
289
|
+
---
|
|
203
290
|
|
|
204
|
-
|
|
291
|
+
## 🔐 Security Model
|
|
205
292
|
|
|
206
|
-
|
|
293
|
+
A span can carry whatever an instrumentation or your code records on it. This package redacts what it can know is dangerous, by default, and says plainly what it does not cover.
|
|
207
294
|
|
|
208
|
-
|
|
209
|
-
- **SQL text with inline literals.** Database instrumentations record the statement; values written into it are exported.
|
|
210
|
-
- **`exception.message` in span events.** An exception's message is exported as recorded.
|
|
211
|
-
- **Span names your own code builds from raw URLs.**
|
|
212
|
-
- **Baggage.**
|
|
213
|
-
- **Request and response bodies, and HTTP headers.** They are not captured by default, and they are not redacted if you enable capturing them.
|
|
214
|
-
- **Attributes your own code sets.**
|
|
295
|
+
The layers are in the [Security Table](#-security-table) below.
|
|
215
296
|
|
|
216
297
|
### Exported on purpose
|
|
217
298
|
|
|
@@ -219,59 +300,141 @@ The resource carries `host.name`, `os.*`, `process.pid`, `process.owner`, the ex
|
|
|
219
300
|
|
|
220
301
|
### How this is verified
|
|
221
302
|
|
|
222
|
-
The packed tarball is installed and run with real `node --import` processes, in a CommonJS application and a native-ESM application, against a local OTLP receiver and a fake Redis. A real HTTP request carries a planted query secret and a real `EVAL` carries a planted argument; both are absent from the whole exported body, while the HTTP spans and the Redis command name are present. Negative controls (no loader hook, no preload, a preload loaded after `ioredis`, `OTEL_SDK_DISABLED=true`) export no such span, so the checks can fail. The
|
|
303
|
+
The packed tarball is installed and run with real `node --import` processes, in a CommonJS application and a native-ESM application, against a local OTLP receiver and a fake Redis. A real HTTP request carries a planted query secret and a real `EVAL` carries a planted argument; both are absent from the whole exported body, while the HTTP spans and the Redis command name are present. Negative controls (no loader hook, no preload, a preload loaded after `ioredis`, `OTEL_SDK_DISABLED=true`) export no such span, so the checks can fail. The span-end layer works on attributes, so it applies to spans from any instrumentation; an instrumentation the proofs do not exercise is not proven individually.
|
|
223
304
|
|
|
224
|
-
To report a vulnerability, follow [SECURITY.md](./SECURITY.md).
|
|
305
|
+
What is **not** redacted is listed flat in [What This Library Does NOT Do](#-what-this-library-does-not-do). To report a vulnerability, follow [SECURITY.md](./SECURITY.md).
|
|
225
306
|
|
|
226
|
-
|
|
307
|
+
---
|
|
227
308
|
|
|
228
|
-
|
|
309
|
+
## 🛡️ Security Table
|
|
229
310
|
|
|
230
|
-
|
|
|
231
|
-
|
|
|
232
|
-
|
|
|
233
|
-
|
|
|
234
|
-
|
|
|
235
|
-
|
|
|
236
|
-
|
|
|
237
|
-
|
|
|
238
|
-
|
|
|
311
|
+
| Layer | Implementation |
|
|
312
|
+
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
313
|
+
| Query redaction | `url.query` is replaced by `[redacted]` and the query is cut from `url.full`, `http.url` and `http.target` as each span ends, for any instrumentation |
|
|
314
|
+
| Outgoing URLs | The HTTP instrumentation redacts a credential-parameter list (`token`, `code`, `access_token`, `signature`, `X-Amz-*`, and more); hosts add names, never drop them; a test compares the list with the SDK's own, so a name the SDK adds later is caught |
|
|
315
|
+
| Redis | `db.query.text` holds the command name only, for `ioredis` and node-redis; `EVAL` and `EVALSHA` payloads, which carry `KEYS` and `ARGV`, and every key never leave the process |
|
|
316
|
+
| Process command line | `process.command_args` and `process.command_line` are dropped from the resource, because command-line arguments are a common carrier of secrets |
|
|
317
|
+
| Opt-outs | Literal `unsafe.*: true` options only, each emitting a `SecurityWarning`; no environment variable turns redaction off |
|
|
318
|
+
| Overrides | `instrumentations.overrides` is merged under the library's redaction, which is applied again on top |
|
|
319
|
+
| Environment | Read in one module; a test fails if any other file names `process.env` |
|
|
320
|
+
| Supply chain | `"dependencies": {}`; every OpenTelemetry package is an optional peer |
|
|
239
321
|
|
|
240
|
-
|
|
322
|
+
> [!IMPORTANT]
|
|
323
|
+
> Redaction protects the attributes it knows about. Secrets that reach a span some other way, such as a token inside a URL path or a value written into SQL text, are yours to keep out. The flat list is in [What This Library Does NOT Do](#-what-this-library-does-not-do).
|
|
324
|
+
|
|
325
|
+
---
|
|
326
|
+
|
|
327
|
+
## 🧱 Tech Stack
|
|
328
|
+
|
|
329
|
+
[](https://opentelemetry.io)
|
|
330
|
+
[](https://nestjs.com)
|
|
331
|
+
[](https://www.typescriptlang.org)
|
|
332
|
+
[](https://nodejs.org)
|
|
333
|
+
[](https://jestjs.io)
|
|
334
|
+
[](https://stryker-mutator.io)
|
|
335
|
+
[](https://pnpm.io)
|
|
336
|
+
[](https://tsup.egoist.dev)
|
|
337
|
+
|
|
338
|
+
---
|
|
339
|
+
|
|
340
|
+
## 🧪 Testing & Quality
|
|
341
|
+
|
|
342
|
+
A tracing library sits on the boot path of every service that installs it, and its redaction is what keeps secrets out of a tracing backend, so the suite is held to a bar beyond "it runs".
|
|
343
|
+
|
|
344
|
+
- ✅ **100% coverage** — statements, branches, functions and lines, enforced in the unit suite, in the end-to-end suite and in both together, with no exclusions
|
|
345
|
+
- ✅ **100% mutation score** — verified with [Stryker](https://stryker-mutator.io/) on a cold run against a `break` threshold of 100, and every unit test confirmed to have run in the mutation run (see the [report](./docs/mutation_testing_results.md))
|
|
346
|
+
|
|
347
|
+
```bash
|
|
348
|
+
pnpm test # unit tests (Jest)
|
|
349
|
+
pnpm test:e2e # end-to-end tests
|
|
350
|
+
pnpm test:cov:all # full coverage gate (unit + e2e together)
|
|
351
|
+
pnpm mutation # Stryker mutation testing (100% break gate)
|
|
352
|
+
pnpm check:runtime # packed-tarball consumer proofs
|
|
353
|
+
```
|
|
354
|
+
|
|
355
|
+
> [!NOTE]
|
|
356
|
+
> Line coverage proves a line _executed_ under test; mutation testing proves a test _would fail_ if that line were wrong. The full methodology and the figures are in [docs/mutation_testing_results.md](./docs/mutation_testing_results.md).
|
|
357
|
+
|
|
358
|
+
---
|
|
359
|
+
|
|
360
|
+
## 📖 API Reference
|
|
361
|
+
|
|
362
|
+
### SDK: `@bymax-one/nest-telemetry`
|
|
363
|
+
|
|
364
|
+
| Export | Signature | Purpose |
|
|
365
|
+
| ------------------------------- | ---------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
366
|
+
| `startTelemetry` | `(options?: TelemetryOptions) => Promise<TelemetryHandle>` | Assembles and starts the SDK; returns the running handle when one exists; rejects when the SDK cannot start or was already shut down in this process |
|
|
367
|
+
| `shutdownTelemetry` | `() => Promise<void>` | Waits for a start in progress, then flushes and stops the SDK; resolves at once when none was started |
|
|
368
|
+
| `ignorePaths` | `(patterns: readonly RegExp[]) => (request) => boolean` | Predicate for `ignoreIncomingRequest`: matches the request path with its query cut; a request with no target is not matched |
|
|
369
|
+
| `DEFAULT_REDACTED_QUERY_PARAMS` | `readonly string[]` | The credential-parameter list redacted from outgoing request URLs |
|
|
370
|
+
| `TelemetryOptions` | type | The options of `startTelemetry` ([Configuration](#-configuration)) |
|
|
371
|
+
| `TelemetryHandle` | type | `{ enabled: boolean, shutdown(): Promise<void> }` |
|
|
372
|
+
| `UnsafeOptions` | type | The literal-`true` redaction opt-outs |
|
|
373
|
+
| `InstrumentationOptions` | type | `fs`, `sendLogs` and `overrides` |
|
|
374
|
+
| `IncomingRequestTarget` | type | What an incoming-request predicate sees: the request `url` |
|
|
375
|
+
|
|
376
|
+
`ignorePaths` copies each pattern without its `g` and `y` flags, which would keep state between calls. Anchor the patterns at both ends; an unanchored one also matches routes that merely contain the word.
|
|
377
|
+
|
|
378
|
+
### Register: `@bymax-one/nest-telemetry/register`
|
|
379
|
+
|
|
380
|
+
No exports. `node --import @bymax-one/nest-telemetry/register` registers the loader hook, starts the SDK from the standard variables and flushes on a natural exit. It emits the warning codes in [The preload](#the-preload).
|
|
381
|
+
|
|
382
|
+
### Nest: `@bymax-one/nest-telemetry/nest`
|
|
383
|
+
|
|
384
|
+
| Export | Kind | Purpose |
|
|
385
|
+
| ---------------------------- | -------- | ---------------------------------------------------------------------------------------------------- |
|
|
386
|
+
| `TelemetryModule` | module | Global; registers `TelemetryShutdownHook`. List it first in the application module's imports |
|
|
387
|
+
| `TelemetryShutdownHook` | provider | `OnApplicationShutdown`: awaits `shutdownTelemetry()`; a refused flush is reported and never rejects |
|
|
388
|
+
| `TELEMETRY_LOGGER` | token | Optional provider with an `errorStructured(logKey, error)` method, used to report a failed flush |
|
|
389
|
+
| `TELEMETRY_FLUSH_FAILED_KEY` | constant | The stable key, `TRACING_FLUSH_FAILED`, under which a failed flush is reported |
|
|
390
|
+
| `ITelemetryErrorLogger` | type | The shape `TELEMETRY_LOGGER` provides: `errorStructured(logKey, error)` |
|
|
391
|
+
|
|
392
|
+
---
|
|
393
|
+
|
|
394
|
+
## 🚫 What This Library Does NOT Do
|
|
395
|
+
|
|
396
|
+
By design, the following are out of scope:
|
|
397
|
+
|
|
398
|
+
- ❌ **Redact secrets in the URL path** — only the query string is removed. A path such as `/reset/<token>` is exported as it is
|
|
399
|
+
- ❌ **Redact SQL text with inline literals** — database instrumentations record the statement, and values written into it are exported. A value bound to a placeholder is not recorded by `instrumentation-mysql2` 0.71, measured with mysql2 2.3.3, 3.0.0, 3.9.0 and 3.24.6; a canary in the proofs fails if that stops being true
|
|
400
|
+
- ❌ **Redact `exception.message` in span events** — an exception's message is exported as recorded
|
|
401
|
+
- ❌ **Redact the text of database driver errors** — not measured; an error recorded on a span carries whatever message the driver wrote
|
|
402
|
+
- ❌ **Redact the memcached key** — `db.memcached.key` is recorded on every memcached span
|
|
403
|
+
- ❌ **Redact an SNS phone number** — a publish to a `PhoneNumber` records the number as the destination name
|
|
404
|
+
- ❌ **Redact the Kafka message key** — `messaging.kafka.message.key` is recorded on producer and consumer spans
|
|
405
|
+
- ❌ **Redact gRPC error messages** — `grpc.error_message` is recorded when a call fails
|
|
406
|
+
- ❌ **Stop the OpenAI instrumentation from capturing prompts** — it reads `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT` itself, and when that is set, message content is recorded
|
|
407
|
+
- ❌ **Redact span names your own code builds from raw URLs**
|
|
408
|
+
- ❌ **Redact baggage**
|
|
409
|
+
- ❌ **Redact request and response bodies, or HTTP headers** — they are not captured by default, and they are not redacted if you enable capturing them
|
|
410
|
+
- ❌ **Redact attributes your own code sets**
|
|
411
|
+
- ❌ **Choose a sampler** — configure `OTEL_TRACES_SAMPLER` and `OTEL_TRACES_SAMPLER_ARG`
|
|
412
|
+
- ❌ **Run a collector or a backend** — point `OTEL_EXPORTER_OTLP_ENDPOINT` at one
|
|
413
|
+
- ❌ **Decide your span names** — those come from the instrumentations and from your code
|
|
414
|
+
- ❌ **Start again after a shutdown in the same process** — `startTelemetry` is refused, because auto-instrumented modules stay patched against the first SDK
|
|
415
|
+
- ❌ **Install a signal handler** — handling `SIGTERM` belongs to the application
|
|
416
|
+
- ❌ **Provide strict semantic versioning** — each release in the [CHANGELOG](./CHANGELOG.md) says what changed and what to do about it, and the version number alone is not the compatibility information
|
|
417
|
+
|
|
418
|
+
---
|
|
419
|
+
|
|
420
|
+
## 🤝 Contributing
|
|
241
421
|
|
|
242
|
-
|
|
422
|
+
The workflow, the commit convention and the checks to run before a pull request are in [CONTRIBUTING.md](./CONTRIBUTING.md).
|
|
243
423
|
|
|
244
|
-
|
|
245
|
-
| ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------- |
|
|
246
|
-
| A preload that starts the SDK before the application loads | `node --import @bymax-one/nest-telemetry/register`, reading the standard variables |
|
|
247
|
-
| The loader hook for native-ESM applications | Registered by the preload, with a warning when its peer is missing |
|
|
248
|
-
| Query-string redaction for every span, and the credential parameter list | On by default; the list is checked against the SDK's own |
|
|
249
|
-
| A Redis serializer that keeps `EVAL` payloads out of spans | On by default |
|
|
250
|
-
| Keeping the command line out of the resource | On by default |
|
|
251
|
-
| Mapping `OTEL_BSP_*` onto the batch processor you pass | Done |
|
|
252
|
-
| Sharing the SDK between a preload and the application | A handle under a `Symbol.for` key, one SDK even across module copies |
|
|
253
|
-
| Flushing on shutdown without racing the framework's own shutdown | `TelemetryModule` flushes through Nest's hook; a failed flush is reported, never thrown |
|
|
254
|
-
| Making sure a telemetry failure cannot stop the host from booting | Each failure the preload can meet is a warning |
|
|
424
|
+
---
|
|
255
425
|
|
|
256
|
-
|
|
426
|
+
## 🔒 Security Policy
|
|
257
427
|
|
|
258
|
-
|
|
428
|
+
If you discover a security vulnerability, please **do not** open a public issue. Follow [SECURITY.md](./SECURITY.md), or email us at **support@bymax.one** with details. We take security seriously and will respond promptly.
|
|
259
429
|
|
|
260
|
-
|
|
261
|
-
| -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
|
|
262
|
-
| No spans at all | `OTEL_SDK_DISABLED`; that the application was started with `--import`; `OTEL_EXPORTER_OTLP_ENDPOINT`; the start warnings. |
|
|
263
|
-
| Spans from a CommonJS app but none from a native-ESM app | `BYMAX_TELEMETRY_ESM_HOOK_UNAVAILABLE`: install `@opentelemetry/instrumentation`. |
|
|
264
|
-
| Spans arrive but carry no service name | `BYMAX_TELEMETRY_SERVICE_NAME_MISSING`: set `OTEL_SERVICE_NAME` or the `serviceName` option. |
|
|
265
|
-
| `BYMAX_TELEMETRY_START_FAILED` | The warning names the cause, usually an OpenTelemetry peer that is not installed. |
|
|
266
|
-
| HTTP spans but no Redis spans | Commands are traced under an active span only, and `ioredis` must be loaded after the preload. |
|
|
267
|
-
| Metrics or logs missing | They are off unless `OTEL_METRICS_EXPORTER` or `OTEL_LOGS_EXPORTER` names an exporter. |
|
|
268
|
-
| The last spans are lost on `SIGTERM` | Call `app.enableShutdownHooks()` in Nest, or `shutdownTelemetry()` from your own shutdown path. |
|
|
269
|
-
| A query string still appears in a span | It is on an attribute other than `url.query`, `url.full`, `http.url` or `http.target`: see [Not covered](#not-covered). |
|
|
430
|
+
---
|
|
270
431
|
|
|
271
|
-
##
|
|
432
|
+
## 📄 License
|
|
272
433
|
|
|
273
|
-
|
|
434
|
+
[MIT](./LICENSE) © [Bymax One](https://github.com/bymaxone)
|
|
274
435
|
|
|
275
|
-
|
|
436
|
+
---
|
|
276
437
|
|
|
277
|
-
|
|
438
|
+
<p align="center">
|
|
439
|
+
<sub>Built with ❤️ by <a href="https://github.com/bymaxone">Bymax One</a></sub>
|
|
440
|
+
</p>
|
package/dist/nest/index.cjs
CHANGED
|
@@ -104,6 +104,7 @@ exports.TelemetryShutdownHook = __decorateClass([
|
|
|
104
104
|
exports.TelemetryModule = class TelemetryModule {
|
|
105
105
|
};
|
|
106
106
|
exports.TelemetryModule = __decorateClass([
|
|
107
|
+
common.Global(),
|
|
107
108
|
common.Module({ providers: [exports.TelemetryShutdownHook] })
|
|
108
109
|
], exports.TelemetryModule);
|
|
109
110
|
|
package/dist/nest/index.d.cts
CHANGED
|
@@ -65,9 +65,9 @@ declare class TelemetryShutdownHook implements OnApplicationShutdown {
|
|
|
65
65
|
}
|
|
66
66
|
|
|
67
67
|
/**
|
|
68
|
-
*
|
|
69
|
-
*
|
|
70
|
-
*
|
|
68
|
+
* List it first in the imports of the application module, before any module that is global or
|
|
69
|
+
* imports a global module. Nest then awaits the SDK flush while closing the application, so
|
|
70
|
+
* buffered spans are exported before the process exits.
|
|
71
71
|
*/
|
|
72
72
|
declare class TelemetryModule {
|
|
73
73
|
}
|
package/dist/nest/index.d.ts
CHANGED
|
@@ -65,9 +65,9 @@ declare class TelemetryShutdownHook implements OnApplicationShutdown {
|
|
|
65
65
|
}
|
|
66
66
|
|
|
67
67
|
/**
|
|
68
|
-
*
|
|
69
|
-
*
|
|
70
|
-
*
|
|
68
|
+
* List it first in the imports of the application module, before any module that is global or
|
|
69
|
+
* imports a global module. Nest then awaits the SDK flush while closing the application, so
|
|
70
|
+
* buffered spans are exported before the process exits.
|
|
71
71
|
*/
|
|
72
72
|
declare class TelemetryModule {
|
|
73
73
|
}
|
package/dist/nest/index.mjs
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { Injectable, Inject, Module, Logger } from '@nestjs/common';
|
|
1
|
+
import { Injectable, Inject, Global, Module, Logger } from '@nestjs/common';
|
|
2
2
|
import { ModuleRef } from '@nestjs/core';
|
|
3
3
|
|
|
4
4
|
var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
|
|
@@ -102,6 +102,7 @@ TelemetryShutdownHook = __decorateClass([
|
|
|
102
102
|
var TelemetryModule = class {
|
|
103
103
|
};
|
|
104
104
|
TelemetryModule = __decorateClass([
|
|
105
|
+
Global(),
|
|
105
106
|
Module({ providers: [TelemetryShutdownHook] })
|
|
106
107
|
], TelemetryModule);
|
|
107
108
|
|
package/dist/register/index.mjs
CHANGED
|
@@ -23,7 +23,7 @@ function readTelemetryEnvironment(source = process.env) {
|
|
|
23
23
|
const serviceName = source["OTEL_SERVICE_NAME"]?.trim();
|
|
24
24
|
const detectors = source["OTEL_NODE_RESOURCE_DETECTORS"];
|
|
25
25
|
return {
|
|
26
|
-
sdkDisabled: source["OTEL_SDK_DISABLED"]?.toLowerCase() === "true",
|
|
26
|
+
sdkDisabled: source["OTEL_SDK_DISABLED"]?.trim().toLowerCase() === "true",
|
|
27
27
|
serviceName: serviceName === "" ? void 0 : serviceName,
|
|
28
28
|
metricsExporters: readExporterList(source["OTEL_METRICS_EXPORTER"]),
|
|
29
29
|
logsExporters: readExporterList(source["OTEL_LOGS_EXPORTER"]),
|
|
@@ -91,6 +91,7 @@ function serializeRedisCommandName(commandName) {
|
|
|
91
91
|
var FS_INSTRUMENTATION = "@opentelemetry/instrumentation-fs";
|
|
92
92
|
var HTTP_INSTRUMENTATION = "@opentelemetry/instrumentation-http";
|
|
93
93
|
var IOREDIS_INSTRUMENTATION = "@opentelemetry/instrumentation-ioredis";
|
|
94
|
+
var REDIS_INSTRUMENTATION = "@opentelemetry/instrumentation-redis";
|
|
94
95
|
var PINO_INSTRUMENTATION = "@opentelemetry/instrumentation-pino";
|
|
95
96
|
var LOG_EXPORTERS = /* @__PURE__ */ new Set(["otlp", "console"]);
|
|
96
97
|
var UNKNOWN_SERVICE_NAME = "unknown_service:node";
|
|
@@ -98,6 +99,7 @@ var WARNING_OPTIONS = {
|
|
|
98
99
|
type: "SecurityWarning",
|
|
99
100
|
code: "BYMAX_TELEMETRY_UNSAFE_REDACTION_DISABLED"
|
|
100
101
|
};
|
|
102
|
+
var IGNORED_WARNING = { type: "Warning", code: "BYMAX_TELEMETRY_OPTIONS_IGNORED" };
|
|
101
103
|
function planSignals(env) {
|
|
102
104
|
const overrides = {};
|
|
103
105
|
if (env.metricsExporters.length === 0) overrides.metricReaders = [];
|
|
@@ -147,10 +149,9 @@ function buildInstrumentationConfig(options, signals) {
|
|
|
147
149
|
merged[HTTP_INSTRUMENTATION]["ignoreIncomingRequestHook"] = options.ignoreIncomingRequest;
|
|
148
150
|
}
|
|
149
151
|
if (redactRedis) {
|
|
150
|
-
|
|
151
|
-
...merged[
|
|
152
|
-
|
|
153
|
-
};
|
|
152
|
+
for (const name of [IOREDIS_INSTRUMENTATION, REDIS_INSTRUMENTATION]) {
|
|
153
|
+
merged[name] = { ...merged[name], dbStatementSerializer: serializeRedisCommandName };
|
|
154
|
+
}
|
|
154
155
|
}
|
|
155
156
|
return merged;
|
|
156
157
|
}
|
|
@@ -182,10 +183,20 @@ function warnAboutUnsafeOptions(options) {
|
|
|
182
183
|
);
|
|
183
184
|
}
|
|
184
185
|
}
|
|
186
|
+
function warnAboutIgnoredOptions(options) {
|
|
187
|
+
const stop = options.enabled === false;
|
|
188
|
+
if (stop || Object.values(options).some((v) => v !== void 0)) {
|
|
189
|
+
process.emitWarning(
|
|
190
|
+
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.",
|
|
191
|
+
IGNORED_WARNING
|
|
192
|
+
);
|
|
193
|
+
}
|
|
194
|
+
}
|
|
185
195
|
|
|
186
196
|
// src/sdk/handle.ts
|
|
187
197
|
var HANDLE_KEY = /* @__PURE__ */ Symbol.for("@bymax-one/nest-telemetry/handle");
|
|
188
198
|
var PENDING_KEY = /* @__PURE__ */ Symbol.for("@bymax-one/nest-telemetry/pending-start");
|
|
199
|
+
var STOPPED_KEY = /* @__PURE__ */ Symbol.for("@bymax-one/nest-telemetry/stopped");
|
|
189
200
|
var store = globalThis;
|
|
190
201
|
function registerHandle(handle) {
|
|
191
202
|
store[HANDLE_KEY] = handle;
|
|
@@ -193,8 +204,8 @@ function registerHandle(handle) {
|
|
|
193
204
|
function currentHandle() {
|
|
194
205
|
return store[HANDLE_KEY];
|
|
195
206
|
}
|
|
196
|
-
function
|
|
197
|
-
|
|
207
|
+
function hasStopped() {
|
|
208
|
+
return Reflect.get(globalThis, STOPPED_KEY) === true;
|
|
198
209
|
}
|
|
199
210
|
function pendingStart() {
|
|
200
211
|
return store[PENDING_KEY];
|
|
@@ -219,8 +230,9 @@ function createHandle(stopSdk) {
|
|
|
219
230
|
}
|
|
220
231
|
flush ??= stopSdk().finally(() => {
|
|
221
232
|
finished = true;
|
|
233
|
+
Reflect.set(globalThis, STOPPED_KEY, true);
|
|
222
234
|
if (currentHandle() === handle) {
|
|
223
|
-
|
|
235
|
+
Reflect.deleteProperty(globalThis, HANDLE_KEY);
|
|
224
236
|
}
|
|
225
237
|
});
|
|
226
238
|
return flush;
|
|
@@ -277,6 +289,7 @@ function selectResourceDetectors(selection, detectors, keepCommandLine) {
|
|
|
277
289
|
}
|
|
278
290
|
|
|
279
291
|
// src/sdk/start.ts
|
|
292
|
+
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.";
|
|
280
293
|
var DISABLED_HANDLE = {
|
|
281
294
|
enabled: false,
|
|
282
295
|
shutdown: () => Promise.resolve()
|
|
@@ -284,6 +297,7 @@ var DISABLED_HANDLE = {
|
|
|
284
297
|
async function startTelemetry(options = {}) {
|
|
285
298
|
const env = readTelemetryEnvironment(options.env);
|
|
286
299
|
if (options.enabled === false || env.sdkDisabled) {
|
|
300
|
+
if (currentHandle()?.stopping === false || pendingStart()) warnAboutIgnoredOptions(options);
|
|
287
301
|
return DISABLED_HANDLE;
|
|
288
302
|
}
|
|
289
303
|
let running = currentHandle();
|
|
@@ -292,12 +306,21 @@ async function startTelemetry(options = {}) {
|
|
|
292
306
|
running = currentHandle();
|
|
293
307
|
}
|
|
294
308
|
if (running !== void 0) {
|
|
309
|
+
warnAboutIgnoredOptions(options);
|
|
295
310
|
return running;
|
|
296
311
|
}
|
|
297
312
|
const joined = pendingStart();
|
|
298
313
|
if (joined !== void 0) {
|
|
314
|
+
warnAboutIgnoredOptions(options);
|
|
299
315
|
return joined;
|
|
300
316
|
}
|
|
317
|
+
if (hasStopped()) {
|
|
318
|
+
process.emitWarning(RESTART_MESSAGE, {
|
|
319
|
+
type: "Warning",
|
|
320
|
+
code: "BYMAX_TELEMETRY_RESTART_UNSUPPORTED"
|
|
321
|
+
});
|
|
322
|
+
throw new Error(RESTART_MESSAGE);
|
|
323
|
+
}
|
|
301
324
|
const start = boot(options, env).finally(clearPendingStart);
|
|
302
325
|
setPendingStart(start);
|
|
303
326
|
return start;
|
package/dist/sdk/index.cjs
CHANGED
|
@@ -73,6 +73,7 @@ function ignorePaths(patterns) {
|
|
|
73
73
|
// src/sdk/handle.ts
|
|
74
74
|
var HANDLE_KEY = /* @__PURE__ */ Symbol.for("@bymax-one/nest-telemetry/handle");
|
|
75
75
|
var PENDING_KEY = /* @__PURE__ */ Symbol.for("@bymax-one/nest-telemetry/pending-start");
|
|
76
|
+
var STOPPED_KEY = /* @__PURE__ */ Symbol.for("@bymax-one/nest-telemetry/stopped");
|
|
76
77
|
var store = globalThis;
|
|
77
78
|
function registerHandle(handle) {
|
|
78
79
|
store[HANDLE_KEY] = handle;
|
|
@@ -80,8 +81,8 @@ function registerHandle(handle) {
|
|
|
80
81
|
function currentHandle() {
|
|
81
82
|
return store[HANDLE_KEY];
|
|
82
83
|
}
|
|
83
|
-
function
|
|
84
|
-
|
|
84
|
+
function hasStopped() {
|
|
85
|
+
return Reflect.get(globalThis, STOPPED_KEY) === true;
|
|
85
86
|
}
|
|
86
87
|
function pendingStart() {
|
|
87
88
|
return store[PENDING_KEY];
|
|
@@ -106,8 +107,9 @@ function createHandle(stopSdk) {
|
|
|
106
107
|
}
|
|
107
108
|
flush ??= stopSdk().finally(() => {
|
|
108
109
|
finished = true;
|
|
110
|
+
Reflect.set(globalThis, STOPPED_KEY, true);
|
|
109
111
|
if (currentHandle() === handle) {
|
|
110
|
-
|
|
112
|
+
Reflect.deleteProperty(globalThis, HANDLE_KEY);
|
|
111
113
|
}
|
|
112
114
|
});
|
|
113
115
|
return flush;
|
|
@@ -124,6 +126,7 @@ async function shutdownTelemetry() {
|
|
|
124
126
|
var FS_INSTRUMENTATION = "@opentelemetry/instrumentation-fs";
|
|
125
127
|
var HTTP_INSTRUMENTATION = "@opentelemetry/instrumentation-http";
|
|
126
128
|
var IOREDIS_INSTRUMENTATION = "@opentelemetry/instrumentation-ioredis";
|
|
129
|
+
var REDIS_INSTRUMENTATION = "@opentelemetry/instrumentation-redis";
|
|
127
130
|
var PINO_INSTRUMENTATION = "@opentelemetry/instrumentation-pino";
|
|
128
131
|
var LOG_EXPORTERS = /* @__PURE__ */ new Set(["otlp", "console"]);
|
|
129
132
|
var UNKNOWN_SERVICE_NAME = "unknown_service:node";
|
|
@@ -131,6 +134,7 @@ var WARNING_OPTIONS = {
|
|
|
131
134
|
type: "SecurityWarning",
|
|
132
135
|
code: "BYMAX_TELEMETRY_UNSAFE_REDACTION_DISABLED"
|
|
133
136
|
};
|
|
137
|
+
var IGNORED_WARNING = { type: "Warning", code: "BYMAX_TELEMETRY_OPTIONS_IGNORED" };
|
|
134
138
|
function planSignals(env) {
|
|
135
139
|
const overrides = {};
|
|
136
140
|
if (env.metricsExporters.length === 0) overrides.metricReaders = [];
|
|
@@ -180,10 +184,9 @@ function buildInstrumentationConfig(options, signals) {
|
|
|
180
184
|
merged[HTTP_INSTRUMENTATION]["ignoreIncomingRequestHook"] = options.ignoreIncomingRequest;
|
|
181
185
|
}
|
|
182
186
|
if (redactRedis) {
|
|
183
|
-
|
|
184
|
-
...merged[
|
|
185
|
-
|
|
186
|
-
};
|
|
187
|
+
for (const name of [IOREDIS_INSTRUMENTATION, REDIS_INSTRUMENTATION]) {
|
|
188
|
+
merged[name] = { ...merged[name], dbStatementSerializer: serializeRedisCommandName };
|
|
189
|
+
}
|
|
187
190
|
}
|
|
188
191
|
return merged;
|
|
189
192
|
}
|
|
@@ -215,6 +218,15 @@ function warnAboutUnsafeOptions(options) {
|
|
|
215
218
|
);
|
|
216
219
|
}
|
|
217
220
|
}
|
|
221
|
+
function warnAboutIgnoredOptions(options) {
|
|
222
|
+
const stop = options.enabled === false;
|
|
223
|
+
if (stop || Object.values(options).some((v) => v !== void 0)) {
|
|
224
|
+
process.emitWarning(
|
|
225
|
+
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.",
|
|
226
|
+
IGNORED_WARNING
|
|
227
|
+
);
|
|
228
|
+
}
|
|
229
|
+
}
|
|
218
230
|
|
|
219
231
|
// src/sdk/environment.ts
|
|
220
232
|
function readExporterList(raw) {
|
|
@@ -237,7 +249,7 @@ function readTelemetryEnvironment(source = process.env) {
|
|
|
237
249
|
const serviceName = source["OTEL_SERVICE_NAME"]?.trim();
|
|
238
250
|
const detectors = source["OTEL_NODE_RESOURCE_DETECTORS"];
|
|
239
251
|
return {
|
|
240
|
-
sdkDisabled: source["OTEL_SDK_DISABLED"]?.toLowerCase() === "true",
|
|
252
|
+
sdkDisabled: source["OTEL_SDK_DISABLED"]?.trim().toLowerCase() === "true",
|
|
241
253
|
serviceName: serviceName === "" ? void 0 : serviceName,
|
|
242
254
|
metricsExporters: readExporterList(source["OTEL_METRICS_EXPORTER"]),
|
|
243
255
|
logsExporters: readExporterList(source["OTEL_LOGS_EXPORTER"]),
|
|
@@ -294,6 +306,7 @@ function selectResourceDetectors(selection, detectors, keepCommandLine) {
|
|
|
294
306
|
}
|
|
295
307
|
|
|
296
308
|
// src/sdk/start.ts
|
|
309
|
+
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.";
|
|
297
310
|
var DISABLED_HANDLE = {
|
|
298
311
|
enabled: false,
|
|
299
312
|
shutdown: () => Promise.resolve()
|
|
@@ -301,6 +314,7 @@ var DISABLED_HANDLE = {
|
|
|
301
314
|
async function startTelemetry(options = {}) {
|
|
302
315
|
const env = readTelemetryEnvironment(options.env);
|
|
303
316
|
if (options.enabled === false || env.sdkDisabled) {
|
|
317
|
+
if (currentHandle()?.stopping === false || pendingStart()) warnAboutIgnoredOptions(options);
|
|
304
318
|
return DISABLED_HANDLE;
|
|
305
319
|
}
|
|
306
320
|
let running = currentHandle();
|
|
@@ -309,12 +323,21 @@ async function startTelemetry(options = {}) {
|
|
|
309
323
|
running = currentHandle();
|
|
310
324
|
}
|
|
311
325
|
if (running !== void 0) {
|
|
326
|
+
warnAboutIgnoredOptions(options);
|
|
312
327
|
return running;
|
|
313
328
|
}
|
|
314
329
|
const joined = pendingStart();
|
|
315
330
|
if (joined !== void 0) {
|
|
331
|
+
warnAboutIgnoredOptions(options);
|
|
316
332
|
return joined;
|
|
317
333
|
}
|
|
334
|
+
if (hasStopped()) {
|
|
335
|
+
process.emitWarning(RESTART_MESSAGE, {
|
|
336
|
+
type: "Warning",
|
|
337
|
+
code: "BYMAX_TELEMETRY_RESTART_UNSUPPORTED"
|
|
338
|
+
});
|
|
339
|
+
throw new Error(RESTART_MESSAGE);
|
|
340
|
+
}
|
|
318
341
|
const start = boot(options, env).finally(clearPendingStart);
|
|
319
342
|
setPendingStart(start);
|
|
320
343
|
return start;
|
package/dist/sdk/index.mjs
CHANGED
|
@@ -71,6 +71,7 @@ function ignorePaths(patterns) {
|
|
|
71
71
|
// src/sdk/handle.ts
|
|
72
72
|
var HANDLE_KEY = /* @__PURE__ */ Symbol.for("@bymax-one/nest-telemetry/handle");
|
|
73
73
|
var PENDING_KEY = /* @__PURE__ */ Symbol.for("@bymax-one/nest-telemetry/pending-start");
|
|
74
|
+
var STOPPED_KEY = /* @__PURE__ */ Symbol.for("@bymax-one/nest-telemetry/stopped");
|
|
74
75
|
var store = globalThis;
|
|
75
76
|
function registerHandle(handle) {
|
|
76
77
|
store[HANDLE_KEY] = handle;
|
|
@@ -78,8 +79,8 @@ function registerHandle(handle) {
|
|
|
78
79
|
function currentHandle() {
|
|
79
80
|
return store[HANDLE_KEY];
|
|
80
81
|
}
|
|
81
|
-
function
|
|
82
|
-
|
|
82
|
+
function hasStopped() {
|
|
83
|
+
return Reflect.get(globalThis, STOPPED_KEY) === true;
|
|
83
84
|
}
|
|
84
85
|
function pendingStart() {
|
|
85
86
|
return store[PENDING_KEY];
|
|
@@ -104,8 +105,9 @@ function createHandle(stopSdk) {
|
|
|
104
105
|
}
|
|
105
106
|
flush ??= stopSdk().finally(() => {
|
|
106
107
|
finished = true;
|
|
108
|
+
Reflect.set(globalThis, STOPPED_KEY, true);
|
|
107
109
|
if (currentHandle() === handle) {
|
|
108
|
-
|
|
110
|
+
Reflect.deleteProperty(globalThis, HANDLE_KEY);
|
|
109
111
|
}
|
|
110
112
|
});
|
|
111
113
|
return flush;
|
|
@@ -122,6 +124,7 @@ async function shutdownTelemetry() {
|
|
|
122
124
|
var FS_INSTRUMENTATION = "@opentelemetry/instrumentation-fs";
|
|
123
125
|
var HTTP_INSTRUMENTATION = "@opentelemetry/instrumentation-http";
|
|
124
126
|
var IOREDIS_INSTRUMENTATION = "@opentelemetry/instrumentation-ioredis";
|
|
127
|
+
var REDIS_INSTRUMENTATION = "@opentelemetry/instrumentation-redis";
|
|
125
128
|
var PINO_INSTRUMENTATION = "@opentelemetry/instrumentation-pino";
|
|
126
129
|
var LOG_EXPORTERS = /* @__PURE__ */ new Set(["otlp", "console"]);
|
|
127
130
|
var UNKNOWN_SERVICE_NAME = "unknown_service:node";
|
|
@@ -129,6 +132,7 @@ var WARNING_OPTIONS = {
|
|
|
129
132
|
type: "SecurityWarning",
|
|
130
133
|
code: "BYMAX_TELEMETRY_UNSAFE_REDACTION_DISABLED"
|
|
131
134
|
};
|
|
135
|
+
var IGNORED_WARNING = { type: "Warning", code: "BYMAX_TELEMETRY_OPTIONS_IGNORED" };
|
|
132
136
|
function planSignals(env) {
|
|
133
137
|
const overrides = {};
|
|
134
138
|
if (env.metricsExporters.length === 0) overrides.metricReaders = [];
|
|
@@ -178,10 +182,9 @@ function buildInstrumentationConfig(options, signals) {
|
|
|
178
182
|
merged[HTTP_INSTRUMENTATION]["ignoreIncomingRequestHook"] = options.ignoreIncomingRequest;
|
|
179
183
|
}
|
|
180
184
|
if (redactRedis) {
|
|
181
|
-
|
|
182
|
-
...merged[
|
|
183
|
-
|
|
184
|
-
};
|
|
185
|
+
for (const name of [IOREDIS_INSTRUMENTATION, REDIS_INSTRUMENTATION]) {
|
|
186
|
+
merged[name] = { ...merged[name], dbStatementSerializer: serializeRedisCommandName };
|
|
187
|
+
}
|
|
185
188
|
}
|
|
186
189
|
return merged;
|
|
187
190
|
}
|
|
@@ -213,6 +216,15 @@ function warnAboutUnsafeOptions(options) {
|
|
|
213
216
|
);
|
|
214
217
|
}
|
|
215
218
|
}
|
|
219
|
+
function warnAboutIgnoredOptions(options) {
|
|
220
|
+
const stop = options.enabled === false;
|
|
221
|
+
if (stop || Object.values(options).some((v) => v !== void 0)) {
|
|
222
|
+
process.emitWarning(
|
|
223
|
+
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.",
|
|
224
|
+
IGNORED_WARNING
|
|
225
|
+
);
|
|
226
|
+
}
|
|
227
|
+
}
|
|
216
228
|
|
|
217
229
|
// src/sdk/environment.ts
|
|
218
230
|
function readExporterList(raw) {
|
|
@@ -235,7 +247,7 @@ function readTelemetryEnvironment(source = process.env) {
|
|
|
235
247
|
const serviceName = source["OTEL_SERVICE_NAME"]?.trim();
|
|
236
248
|
const detectors = source["OTEL_NODE_RESOURCE_DETECTORS"];
|
|
237
249
|
return {
|
|
238
|
-
sdkDisabled: source["OTEL_SDK_DISABLED"]?.toLowerCase() === "true",
|
|
250
|
+
sdkDisabled: source["OTEL_SDK_DISABLED"]?.trim().toLowerCase() === "true",
|
|
239
251
|
serviceName: serviceName === "" ? void 0 : serviceName,
|
|
240
252
|
metricsExporters: readExporterList(source["OTEL_METRICS_EXPORTER"]),
|
|
241
253
|
logsExporters: readExporterList(source["OTEL_LOGS_EXPORTER"]),
|
|
@@ -292,6 +304,7 @@ function selectResourceDetectors(selection, detectors, keepCommandLine) {
|
|
|
292
304
|
}
|
|
293
305
|
|
|
294
306
|
// src/sdk/start.ts
|
|
307
|
+
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
308
|
var DISABLED_HANDLE = {
|
|
296
309
|
enabled: false,
|
|
297
310
|
shutdown: () => Promise.resolve()
|
|
@@ -299,6 +312,7 @@ var DISABLED_HANDLE = {
|
|
|
299
312
|
async function startTelemetry(options = {}) {
|
|
300
313
|
const env = readTelemetryEnvironment(options.env);
|
|
301
314
|
if (options.enabled === false || env.sdkDisabled) {
|
|
315
|
+
if (currentHandle()?.stopping === false || pendingStart()) warnAboutIgnoredOptions(options);
|
|
302
316
|
return DISABLED_HANDLE;
|
|
303
317
|
}
|
|
304
318
|
let running = currentHandle();
|
|
@@ -307,12 +321,21 @@ async function startTelemetry(options = {}) {
|
|
|
307
321
|
running = currentHandle();
|
|
308
322
|
}
|
|
309
323
|
if (running !== void 0) {
|
|
324
|
+
warnAboutIgnoredOptions(options);
|
|
310
325
|
return running;
|
|
311
326
|
}
|
|
312
327
|
const joined = pendingStart();
|
|
313
328
|
if (joined !== void 0) {
|
|
329
|
+
warnAboutIgnoredOptions(options);
|
|
314
330
|
return joined;
|
|
315
331
|
}
|
|
332
|
+
if (hasStopped()) {
|
|
333
|
+
process.emitWarning(RESTART_MESSAGE, {
|
|
334
|
+
type: "Warning",
|
|
335
|
+
code: "BYMAX_TELEMETRY_RESTART_UNSUPPORTED"
|
|
336
|
+
});
|
|
337
|
+
throw new Error(RESTART_MESSAGE);
|
|
338
|
+
}
|
|
316
339
|
const start = boot(options, env).finally(clearPendingStart);
|
|
317
340
|
setPendingStart(start);
|
|
318
341
|
return start;
|
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.2",
|
|
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,9 @@
|
|
|
189
189
|
"ioredis": "^6.0.0",
|
|
190
190
|
"jest": "^30.4.2",
|
|
191
191
|
"lint-staged": "^17.0.7",
|
|
192
|
+
"mysql2": "3.24.6",
|
|
192
193
|
"prettier": "^3.8.3",
|
|
194
|
+
"redis": "^5.12.2",
|
|
193
195
|
"reflect-metadata": "^0.2.2",
|
|
194
196
|
"rxjs": "^7.8.0",
|
|
195
197
|
"supertest": "^7.2.2",
|