@bymax-one/nest-telemetry 1.0.0 → 1.0.1
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 +14 -1
- package/README.md +285 -136
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -8,7 +8,19 @@ 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.1] - 2026-11-12
|
|
12
|
+
|
|
13
|
+
Documentation only; the built files are the same as in 1.0.0.
|
|
14
|
+
|
|
15
|
+
### Changed
|
|
16
|
+
|
|
17
|
+
- The changelog dates 1.0.0, which the published package still lists as unreleased.
|
|
18
|
+
- The README follows the structure of the other `@bymax-one` libraries. Its claims are those of 1.0.0,
|
|
19
|
+
and a `service.name` set only in `OTEL_RESOURCE_ATTRIBUTES` reaches the spans while the `env`
|
|
20
|
+
or `service` resource detector is enabled, and the missing-service-name warning still fires.
|
|
21
|
+
- `docs/mutation_testing_results.md` records the cold mutation run that gated 1.0.0.
|
|
22
|
+
|
|
23
|
+
## [1.0.0] - 2026-11-12
|
|
12
24
|
|
|
13
25
|
First release.
|
|
14
26
|
|
|
@@ -43,4 +55,5 @@ First release.
|
|
|
43
55
|
- Verification from the packed tarball: real `node --import` processes in a CommonJS and a native-ESM
|
|
44
56
|
application, with planted secrets absent from the exported body and negative controls.
|
|
45
57
|
|
|
58
|
+
[1.0.1]: https://github.com/bymaxone/nest-telemetry/releases/tag/v1.0.1
|
|
46
59
|
[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** — `EVAL` and `EVALSHA` payloads never leave the process
|
|
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
|
|
|
@@ -61,10 +131,10 @@ export class AppModule {}
|
|
|
61
131
|
Things to know before you rely on it:
|
|
62
132
|
|
|
63
133
|
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.
|
|
134
|
+
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
135
|
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
136
|
|
|
67
|
-
|
|
137
|
+
### Plain Node
|
|
68
138
|
|
|
69
139
|
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
140
|
|
|
@@ -85,46 +155,52 @@ await telemetry.shutdown()
|
|
|
85
155
|
|
|
86
156
|
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`).
|
|
87
157
|
|
|
88
|
-
|
|
158
|
+
---
|
|
89
159
|
|
|
90
|
-
|
|
160
|
+
## ⚙️ Configuration
|
|
91
161
|
|
|
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.
|
|
162
|
+
### `startTelemetry(options)`
|
|
96
163
|
|
|
97
|
-
|
|
164
|
+
Every field is the host's policy, and none is required.
|
|
98
165
|
|
|
99
|
-
|
|
100
|
-
|
|
166
|
+
| Option | Default | What it does |
|
|
167
|
+
| -------------------------------------- | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
|
|
168
|
+
| `enabled` | `true` | `false` never starts the SDK. `OTEL_SDK_DISABLED=true` disables it regardless. |
|
|
169
|
+
| `serviceName` | `unknown_service:node` | The service name. `OTEL_SERVICE_NAME` overrides it. |
|
|
170
|
+
| `serviceVersion` | none | The service version. |
|
|
171
|
+
| `ignoreIncomingRequest` | none | Returns `true` for an incoming request that must produce no server span. `ignorePaths(patterns)` builds one from anchored patterns. |
|
|
172
|
+
| `instrumentations.fs` | `false` | File-system instrumentation. |
|
|
173
|
+
| `instrumentations.sendLogs` | follows `OTEL_LOGS_EXPORTER` | Whether pino's records are forwarded to the OpenTelemetry logs pipeline. |
|
|
174
|
+
| `instrumentations.overrides` | none | Per-instrumentation configuration, merged over the library's. Redaction settings cannot be replaced here. |
|
|
175
|
+
| `extraRedactedQueryParams` | none | Names added to the list redacted from outgoing request URLs. They add to the defaults and never replace them. |
|
|
176
|
+
| `unsafe.disableUrlRedaction` | off | Keeps `url.query`, `url.full`, `http.url` and `http.target` as recorded. Literal `true`. Warns. |
|
|
177
|
+
| `unsafe.disableRedisArgumentRedaction` | off | Keeps Redis command arguments in `db.query.text`. Literal `true`. Warns. |
|
|
178
|
+
| `unsafe.exportProcessCommandArgs` | off | Keeps `process.command_args` and `process.command_line` in the resource. Literal `true`. Warns. |
|
|
179
|
+
| `env` | the process environment | The environment the library reads. The OpenTelemetry SDK itself always reads the process environment. |
|
|
101
180
|
|
|
102
|
-
|
|
181
|
+
### Environment variables
|
|
103
182
|
|
|
104
|
-
|
|
105
|
-
errorStructured(logKey: string, error: Error): void {
|
|
106
|
-
console.error(logKey, error.message)
|
|
107
|
-
}
|
|
108
|
-
}
|
|
183
|
+
The library reads these in one source file, and a test fails if any other file names `process.env`:
|
|
109
184
|
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
185
|
+
| Variable | Effect |
|
|
186
|
+
| ----------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
|
|
187
|
+
| `OTEL_SDK_DISABLED` | `true` (any letter case) disables the SDK. |
|
|
188
|
+
| `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. |
|
|
189
|
+
| `OTEL_METRICS_EXPORTER`, `OTEL_LOGS_EXPORTER` | Metrics and logs are exported only when these name an exporter. |
|
|
190
|
+
| `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. |
|
|
191
|
+
| `OTEL_NODE_RESOURCE_DETECTORS` | Selects resource detectors, under the specification's names (`service`, `host`, `process`) and the SDK's older ones. |
|
|
116
192
|
|
|
117
|
-
|
|
193
|
+
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
194
|
|
|
119
|
-
|
|
195
|
+
---
|
|
120
196
|
|
|
121
|
-
|
|
197
|
+
## 🧭 How It Behaves
|
|
122
198
|
|
|
123
199
|
### The preload
|
|
124
200
|
|
|
125
201
|
`./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
202
|
|
|
127
|
-
|
|
203
|
+
The start emits these warnings:
|
|
128
204
|
|
|
129
205
|
| Code | Meaning |
|
|
130
206
|
| ------------------------------------------- | ------------------------------------------------------------------------------ |
|
|
@@ -145,73 +221,71 @@ The programmatic `startTelemetry` keeps its rejection when the SDK cannot start,
|
|
|
145
221
|
|
|
146
222
|
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
223
|
|
|
148
|
-
|
|
224
|
+
---
|
|
149
225
|
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
| Option | Default | What it does |
|
|
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. |
|
|
226
|
+
## 🔄 OpenTelemetry Versions
|
|
166
227
|
|
|
167
|
-
|
|
228
|
+
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
229
|
|
|
169
|
-
|
|
230
|
+
| Package | Range |
|
|
231
|
+
| ------------------------------------------- | ---------- |
|
|
232
|
+
| `@opentelemetry/api` | `^1.10.0` |
|
|
233
|
+
| `@opentelemetry/sdk-node` | `^0.301.0` |
|
|
234
|
+
| `@opentelemetry/exporter-trace-otlp-http` | `^0.301.0` |
|
|
235
|
+
| `@opentelemetry/instrumentation` | `^0.301.0` |
|
|
236
|
+
| `@opentelemetry/sdk-trace` | `^3.1.0` |
|
|
237
|
+
| `@opentelemetry/resources` | `^3.1.0` |
|
|
238
|
+
| `@opentelemetry/auto-instrumentations-node` | `^0.83.0` |
|
|
170
239
|
|
|
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. |
|
|
240
|
+
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
241
|
|
|
179
|
-
|
|
242
|
+
---
|
|
180
243
|
|
|
181
|
-
|
|
244
|
+
## 🩺 Troubleshooting
|
|
182
245
|
|
|
183
|
-
|
|
|
184
|
-
|
|
|
185
|
-
|
|
|
186
|
-
|
|
|
187
|
-
|
|
|
246
|
+
| You see | Look at |
|
|
247
|
+
| -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
248
|
+
| No spans at all | `OTEL_SDK_DISABLED`; that the application was started with `--import`; `OTEL_EXPORTER_OTLP_ENDPOINT`; the start warnings. |
|
|
249
|
+
| Spans from a CommonJS app but none from a native-ESM app | `BYMAX_TELEMETRY_ESM_HOOK_UNAVAILABLE`: install `@opentelemetry/instrumentation`. |
|
|
250
|
+
| 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. |
|
|
251
|
+
| `BYMAX_TELEMETRY_START_FAILED` | The warning names the cause, usually an OpenTelemetry peer that is not installed. |
|
|
252
|
+
| HTTP spans but no Redis spans | Commands are traced under an active span only, and `ioredis` must be loaded after the preload. |
|
|
253
|
+
| Metrics or logs missing | They are off unless `OTEL_METRICS_EXPORTER` or `OTEL_LOGS_EXPORTER` names an exporter. |
|
|
254
|
+
| The last spans are lost on `SIGTERM` | Call `app.enableShutdownHooks()` in Nest, or `shutdownTelemetry()` from your own shutdown path. |
|
|
255
|
+
| 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
256
|
|
|
189
|
-
|
|
257
|
+
---
|
|
190
258
|
|
|
191
|
-
|
|
259
|
+
## 🏗️ Architecture
|
|
192
260
|
|
|
193
|
-
|
|
261
|
+
```
|
|
262
|
+
node --import @bymax-one/nest-telemetry/register
|
|
263
|
+
→ Preload registers the ES-module loader hook, then starts the SDK from the
|
|
264
|
+
standard OTEL_* variables; a failure is a warning
|
|
265
|
+
→ startTelemetry(options)
|
|
266
|
+
disabled? returns a no-op handle and loads no OpenTelemetry package
|
|
267
|
+
→ Assembly resource attributes, instrumentation configuration with the redaction
|
|
268
|
+
applied on top of the host's overrides, signal plan (traces only unless
|
|
269
|
+
an exporter is named)
|
|
270
|
+
→ NodeSDK resource detectors (OTEL_NODE_RESOURCE_DETECTORS), a batch span processor
|
|
271
|
+
and a span processor that redacts URL attributes as each span ends
|
|
272
|
+
→ Handle stored under a Symbol.for key on globalThis: one SDK per process,
|
|
273
|
+
one shared flush
|
|
274
|
+
→ Application code (traced)
|
|
275
|
+
→ TelemetryShutdownHook
|
|
276
|
+
Nest's OnApplicationShutdown awaits shutdownTelemetry(); a refused flush
|
|
277
|
+
is reported under TRACING_FLUSH_FAILED
|
|
278
|
+
```
|
|
194
279
|
|
|
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. |
|
|
280
|
+
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
281
|
|
|
202
|
-
|
|
282
|
+
---
|
|
203
283
|
|
|
204
|
-
|
|
284
|
+
## 🔐 Security Model
|
|
205
285
|
|
|
206
|
-
|
|
286
|
+
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
287
|
|
|
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.**
|
|
288
|
+
The layers are in the [Security Table](#-security-table) below.
|
|
215
289
|
|
|
216
290
|
### Exported on purpose
|
|
217
291
|
|
|
@@ -221,57 +295,132 @@ The resource carries `host.name`, `os.*`, `process.pid`, `process.owner`, the ex
|
|
|
221
295
|
|
|
222
296
|
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 proof covers the HTTP and `ioredis` instrumentations; the span-end layer works on attributes, so it applies to spans from other instrumentations too, but those are not each proven individually.
|
|
223
297
|
|
|
224
|
-
To report a vulnerability, follow [SECURITY.md](./SECURITY.md).
|
|
298
|
+
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
299
|
|
|
226
|
-
|
|
300
|
+
---
|
|
227
301
|
|
|
228
|
-
|
|
302
|
+
## 🛡️ Security Table
|
|
229
303
|
|
|
230
|
-
|
|
|
231
|
-
|
|
|
232
|
-
|
|
|
233
|
-
|
|
|
234
|
-
|
|
|
235
|
-
|
|
|
236
|
-
|
|
|
237
|
-
|
|
|
238
|
-
|
|
|
304
|
+
| Layer | Implementation |
|
|
305
|
+
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
306
|
+
| 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 |
|
|
307
|
+
| 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 |
|
|
308
|
+
| Redis | `db.query.text` holds the command name only; `EVAL` and `EVALSHA` payloads, which carry `KEYS` and `ARGV`, never leave the process |
|
|
309
|
+
| 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 |
|
|
310
|
+
| Opt-outs | Literal `unsafe.*: true` options only, each emitting a `SecurityWarning`; no environment variable turns redaction off |
|
|
311
|
+
| Overrides | `instrumentations.overrides` is merged under the library's redaction, which is applied again on top |
|
|
312
|
+
| Environment | Read in one module; a test fails if any other file names `process.env` |
|
|
313
|
+
| Supply chain | `"dependencies": {}`; every OpenTelemetry package is an optional peer |
|
|
239
314
|
|
|
240
|
-
|
|
315
|
+
> [!IMPORTANT]
|
|
316
|
+
> 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).
|
|
317
|
+
|
|
318
|
+
---
|
|
319
|
+
|
|
320
|
+
## 🧱 Tech Stack
|
|
321
|
+
|
|
322
|
+
[](https://opentelemetry.io)
|
|
323
|
+
[](https://nestjs.com)
|
|
324
|
+
[](https://www.typescriptlang.org)
|
|
325
|
+
[](https://nodejs.org)
|
|
326
|
+
[](https://jestjs.io)
|
|
327
|
+
[](https://stryker-mutator.io)
|
|
328
|
+
[](https://pnpm.io)
|
|
329
|
+
[](https://tsup.egoist.dev)
|
|
330
|
+
|
|
331
|
+
---
|
|
332
|
+
|
|
333
|
+
## 🧪 Testing & Quality
|
|
334
|
+
|
|
335
|
+
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".
|
|
336
|
+
|
|
337
|
+
- ✅ **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
|
|
338
|
+
- ✅ **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))
|
|
339
|
+
|
|
340
|
+
```bash
|
|
341
|
+
pnpm test # unit tests (Jest)
|
|
342
|
+
pnpm test:e2e # end-to-end tests
|
|
343
|
+
pnpm test:cov:all # full coverage gate (unit + e2e together)
|
|
344
|
+
pnpm mutation # Stryker mutation testing (100% break gate)
|
|
345
|
+
pnpm check:runtime # packed-tarball consumer proofs
|
|
346
|
+
```
|
|
347
|
+
|
|
348
|
+
> [!NOTE]
|
|
349
|
+
> 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).
|
|
350
|
+
|
|
351
|
+
---
|
|
352
|
+
|
|
353
|
+
## 📖 API Reference
|
|
354
|
+
|
|
355
|
+
### SDK: `@bymax-one/nest-telemetry`
|
|
356
|
+
|
|
357
|
+
| Export | Signature | Purpose |
|
|
358
|
+
| ------------------------------- | ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
|
|
359
|
+
| `startTelemetry` | `(options?: TelemetryOptions) => Promise<TelemetryHandle>` | Assembles and starts the SDK; returns the running handle when one exists; rejects when the SDK cannot start |
|
|
360
|
+
| `shutdownTelemetry` | `() => Promise<void>` | Waits for a start in progress, then flushes and stops the SDK; resolves at once when none was started |
|
|
361
|
+
| `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 |
|
|
362
|
+
| `DEFAULT_REDACTED_QUERY_PARAMS` | `readonly string[]` | The credential-parameter list redacted from outgoing request URLs |
|
|
363
|
+
| `TelemetryOptions` | type | The options of `startTelemetry` ([Configuration](#-configuration)) |
|
|
364
|
+
| `TelemetryHandle` | type | `{ enabled: boolean, shutdown(): Promise<void> }` |
|
|
365
|
+
| `UnsafeOptions` | type | The literal-`true` redaction opt-outs |
|
|
366
|
+
| `InstrumentationOptions` | type | `fs`, `sendLogs` and `overrides` |
|
|
367
|
+
| `IncomingRequestTarget` | type | What an incoming-request predicate sees: the request `url` |
|
|
368
|
+
|
|
369
|
+
`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.
|
|
370
|
+
|
|
371
|
+
### Register: `@bymax-one/nest-telemetry/register`
|
|
372
|
+
|
|
373
|
+
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).
|
|
374
|
+
|
|
375
|
+
### Nest: `@bymax-one/nest-telemetry/nest`
|
|
376
|
+
|
|
377
|
+
| Export | Kind | Purpose |
|
|
378
|
+
| ---------------------------- | -------- | ---------------------------------------------------------------------------------------------------- |
|
|
379
|
+
| `TelemetryModule` | module | Registers `TelemetryShutdownHook` |
|
|
380
|
+
| `TelemetryShutdownHook` | provider | `OnApplicationShutdown`: awaits `shutdownTelemetry()`; a refused flush is reported and never rejects |
|
|
381
|
+
| `TELEMETRY_LOGGER` | token | Optional provider with an `errorStructured(logKey, error)` method, used to report a failed flush |
|
|
382
|
+
| `TELEMETRY_FLUSH_FAILED_KEY` | constant | The stable key, `TRACING_FLUSH_FAILED`, under which a failed flush is reported |
|
|
383
|
+
| `ITelemetryErrorLogger` | type | The shape `TELEMETRY_LOGGER` provides: `errorStructured(logKey, error)` |
|
|
384
|
+
|
|
385
|
+
---
|
|
386
|
+
|
|
387
|
+
## 🚫 What This Library Does NOT Do
|
|
388
|
+
|
|
389
|
+
By design, the following are out of scope:
|
|
390
|
+
|
|
391
|
+
- ❌ **Redact secrets in the URL path** — only the query string is removed. A path such as `/reset/<token>` is exported as it is
|
|
392
|
+
- ❌ **Redact SQL text with inline literals** — database instrumentations record the statement, and values written into it are exported
|
|
393
|
+
- ❌ **Redact `exception.message` in span events** — an exception's message is exported as recorded
|
|
394
|
+
- ❌ **Redact span names your own code builds from raw URLs**
|
|
395
|
+
- ❌ **Redact baggage**
|
|
396
|
+
- ❌ **Redact request and response bodies, or HTTP headers** — they are not captured by default, and they are not redacted if you enable capturing them
|
|
397
|
+
- ❌ **Redact attributes your own code sets**
|
|
398
|
+
- ❌ **Choose a sampler** — configure `OTEL_TRACES_SAMPLER` and `OTEL_TRACES_SAMPLER_ARG`
|
|
399
|
+
- ❌ **Run a collector or a backend** — point `OTEL_EXPORTER_OTLP_ENDPOINT` at one
|
|
400
|
+
- ❌ **Decide your span names** — those come from the instrumentations and from your code
|
|
401
|
+
- ❌ **Install a signal handler** — handling `SIGTERM` belongs to the application
|
|
402
|
+
- ❌ **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
|
|
403
|
+
|
|
404
|
+
---
|
|
405
|
+
|
|
406
|
+
## 🤝 Contributing
|
|
241
407
|
|
|
242
|
-
|
|
408
|
+
The workflow, the commit convention and the checks to run before a pull request are in [CONTRIBUTING.md](./CONTRIBUTING.md).
|
|
243
409
|
|
|
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 |
|
|
410
|
+
---
|
|
255
411
|
|
|
256
|
-
|
|
412
|
+
## 🔒 Security Policy
|
|
257
413
|
|
|
258
|
-
|
|
414
|
+
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
415
|
|
|
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). |
|
|
416
|
+
---
|
|
270
417
|
|
|
271
|
-
##
|
|
418
|
+
## 📄 License
|
|
272
419
|
|
|
273
|
-
|
|
420
|
+
[MIT](./LICENSE) © [Bymax One](https://github.com/bymaxone)
|
|
274
421
|
|
|
275
|
-
|
|
422
|
+
---
|
|
276
423
|
|
|
277
|
-
|
|
424
|
+
<p align="center">
|
|
425
|
+
<sub>Built with ❤️ by <a href="https://github.com/bymaxone">Bymax One</a></sub>
|
|
426
|
+
</p>
|
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.1",
|
|
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",
|