@bymax-one/nest-telemetry 1.0.4 → 1.0.6
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 +109 -0
- package/README.md +102 -45
- package/dist/nest/index.cjs +14 -2
- package/dist/nest/index.mjs +14 -2
- package/dist/observability/index.cjs +50 -0
- package/dist/observability/index.d.cts +19 -0
- package/dist/observability/index.d.ts +19 -0
- package/dist/observability/index.mjs +48 -0
- package/dist/register/index.mjs +139 -25
- package/dist/sdk/index.cjs +114 -9
- package/dist/sdk/index.mjs +114 -9
- package/package.json +31 -4
package/CHANGELOG.md
CHANGED
|
@@ -8,6 +8,113 @@ The `release.yml` workflow extracts the section matching the pushed `vX.Y.Z` tag
|
|
|
8
8
|
as the GitHub Release body, so each released version needs a matching `## [X.Y.Z]`
|
|
9
9
|
heading here.
|
|
10
10
|
|
|
11
|
+
## [Unreleased]
|
|
12
|
+
|
|
13
|
+
## [1.0.6] - 2026-11-18
|
|
14
|
+
|
|
15
|
+
### Added
|
|
16
|
+
|
|
17
|
+
- **A metrics contributor for `@bymax-one/nest-core`, on the new `./observability` subpath.**
|
|
18
|
+
`TelemetryMetrics` registers the counter `bymax_telemetry_span_export_failures_total`, the span export
|
|
19
|
+
batches the collector did not accept, with no label and with a value of 0 before the first failure. The
|
|
20
|
+
exporter wrapper now counts every failed export, not only the one a minute that warns, and keeps the count
|
|
21
|
+
on `globalThis` so the preload's copy and the application's copy agree. `@bymax-one/nest-core` and
|
|
22
|
+
`prom-client` are optional peers, no other entry loads them, and with the core metrics feature off nothing
|
|
23
|
+
is created.
|
|
24
|
+
- **The README catalogs the domain span names of the Bymax libraries**, with a link to each library, the
|
|
25
|
+
attribute and error rules of the observability standard, and the one propagator requirement of the queue.
|
|
26
|
+
A test now fails when the README leaves out an export of any subpath or an `OTEL_*` variable the
|
|
27
|
+
environment reader names.
|
|
28
|
+
- **A start warning for a sampler name that differs from a known one only by case or whitespace.** The SDK
|
|
29
|
+
compares `OTEL_TRACES_SAMPLER` exactly against `always_on`, `always_off`, `traceidratio`,
|
|
30
|
+
`parentbased_always_on`, `parentbased_always_off` and `parentbased_traceidratio`, replaces any other
|
|
31
|
+
value with its default and samples every trace, noting it only on a diagnostic channel. So
|
|
32
|
+
`TraceIdRatio`, ` traceidratio` or `ALWAYS_OFF` kept every trace in silence. The start now warns once
|
|
33
|
+
with `BYMAX_TELEMETRY_SAMPLER_NAME_UNKNOWN`, naming the name that was meant and not repeating the value.
|
|
34
|
+
Measured with the real SDK: `TraceIdRatio`, ` traceidratio` and `ALWAYS_OFF` with a ratio of `0` sampled
|
|
35
|
+
all 200 root spans, and the exact names sampled none.
|
|
36
|
+
|
|
37
|
+
### Changed
|
|
38
|
+
|
|
39
|
+
- **An empty or whitespace-only `OTEL_TRACES_SAMPLER_ARG` is called blank, not unset.** The ratio warning said the
|
|
40
|
+
variable was "not set" for an empty or whitespace-only value, which sends the reader looking for a
|
|
41
|
+
variable that exists. An unset variable still reads "not set".
|
|
42
|
+
- **The winston warning says when to ignore it.** It now says to ignore it when the application never
|
|
43
|
+
creates a winston logger or when `OTEL_LOGS_EXPORTER` is `none`, where nothing is forwarded either way;
|
|
44
|
+
the README says the same and notes that the warning also fires with `instrumentations.sendLogs: true`
|
|
45
|
+
and with the `console` exporter. The sampler matching rule is in the README.
|
|
46
|
+
|
|
47
|
+
### Fixed
|
|
48
|
+
|
|
49
|
+
- **The failed-flush entry on the Nest logger no longer writes the error's message or stack.** Without a
|
|
50
|
+
bound `TELEMETRY_LOGGER`, `TelemetryShutdownHook` wrote `TRACING_FLUSH_FAILED: <message>` with the stack to
|
|
51
|
+
the Nest logger. The error of an exporter can carry the endpoint it called, credentials included, in both,
|
|
52
|
+
so the entry now holds library text and a short error code (`UNKNOWN` unless it is an upper-case token). A bound
|
|
53
|
+
`TELEMETRY_LOGGER` still receives the `Error` object itself.
|
|
54
|
+
- **The two preload warnings no longer write the error's text.** `BYMAX_TELEMETRY_START_FAILED` and
|
|
55
|
+
`BYMAX_TELEMETRY_ESM_HOOK_UNAVAILABLE` interpolated the error, and an SDK or loader error can quote its
|
|
56
|
+
configuration, an endpoint or a header among it. They now name its code and, when its message names one,
|
|
57
|
+
the OpenTelemetry package, so a missing peer is still named. One reader serves them, the flush entry and
|
|
58
|
+
the export warning; it reads a code only when it is a string or a number, so the `code` field of
|
|
59
|
+
`BYMAX_TELEMETRY_EXPORT_FAILED` is `UNKNOWN` for any other type of code, which was passed through as text
|
|
60
|
+
before.
|
|
61
|
+
- **An option key set to `undefined` or `null` is the same as no key, for every option that has a
|
|
62
|
+
default.** A `null` in an instrumentation override, in `ignoreIncomingRequest` or in a repeated call's
|
|
63
|
+
options was read as a given value: an override key set to `undefined` replaced a library default, and a
|
|
64
|
+
repeated start whose options were all `null` was reported as ignoring them. `env: null` threw a `TypeError` at start instead of reading the process environment. The keys are now dropped
|
|
65
|
+
before they are merged with the defaults, and each known option is read by property access, so options
|
|
66
|
+
given as a class instance with getters read as a plain object does. A table covers each defaulted option
|
|
67
|
+
with both values and with a class instance.
|
|
68
|
+
|
|
69
|
+
### Apply to a derived backend
|
|
70
|
+
|
|
71
|
+
The declarations gained the `./observability` subpath; nothing else about the public types changed, and
|
|
72
|
+
a backend that does not use it changes nothing. A derived backend acts on these behaviours:
|
|
73
|
+
|
|
74
|
+
1. To publish the failed-export counter, install `@bymax-one/nest-core` (1.1.0 or a later 1.x release) and `prom-client`
|
|
75
|
+
(15), which are optional peers, with `@nestjs/common` and `reflect-metadata` that a Nest application
|
|
76
|
+
already has; add `TelemetryMetrics` from `@bymax-one/nest-telemetry/observability` to the providers of
|
|
77
|
+
any module, and alert on `increase(bymax_telemetry_span_export_failures_total[5m]) > 0`. The exporter
|
|
78
|
+
counts every failed export from this release on, whether or not the metric is published.
|
|
79
|
+
2. A start can now warn with `BYMAX_TELEMETRY_SAMPLER_NAME_UNKNOWN` for a sampler name that differs from a
|
|
80
|
+
known one only by case or whitespace; an environment that sets such a value was already sampling every
|
|
81
|
+
trace. The existing `BYMAX_TELEMETRY_SAMPLER_ARG_INVALID` warning calls an empty or whitespace-only ratio
|
|
82
|
+
argument blank instead of not set, and the winston warning text says when to ignore it. An alert or a log filter
|
|
83
|
+
that matches either text needs the new words. The `TRACING_FLUSH_FAILED` entry on the Nest logger no
|
|
84
|
+
longer carries the error's message or stack: bind `TELEMETRY_LOGGER` to receive the `Error` itself. The two preload warnings now read `(code <CODE>[, package <name>])` where they quoted the error's text,
|
|
85
|
+
so a log filter that matched that text needs the code. The `code` of `BYMAX_TELEMETRY_EXPORT_FAILED` is `UNKNOWN` for a code that is neither a string nor a number.
|
|
86
|
+
3. An option key set to `undefined` or `null` is the same as no key. A backend that set a key to `undefined` in an
|
|
87
|
+
instrumentation override now gets the library default, and `env: null` no longer throws a
|
|
88
|
+
`TypeError` at start: the process environment is read.
|
|
89
|
+
|
|
90
|
+
## [1.0.5] - 2026-11-17
|
|
91
|
+
|
|
92
|
+
### Added
|
|
93
|
+
|
|
94
|
+
- **A start warning for a ratio sampler that has no usable ratio.** With `OTEL_TRACES_SAMPLER` set to
|
|
95
|
+
`traceidratio` or `parentbased_traceidratio`, the SDK reads `OTEL_TRACES_SAMPLER_ARG` with `Number` and
|
|
96
|
+
falls back to a ratio of 1 when it is unset, empty, not a number or outside 0 to 1, noting it only on a
|
|
97
|
+
diagnostic channel. Every trace was then sampled without a word, which is the cost a ratio was set to
|
|
98
|
+
avoid. The start now warns once with `BYMAX_TELEMETRY_SAMPLER_ARG_INVALID`, naming the variable and,
|
|
99
|
+
when one was given, the value. Measured with the real SDK: `1.5`, `-1`, `10%`, `NaN`, `Infinity` and no
|
|
100
|
+
value sampled all 200 root spans; `0` sampled none.
|
|
101
|
+
|
|
102
|
+
### Fixed
|
|
103
|
+
|
|
104
|
+
- **Winston log forwarding says when it cannot work.** The winston instrumentation forwards a record by
|
|
105
|
+
adding a transport from `@opentelemetry/winston-transport`, which it loads with a `require` and which is
|
|
106
|
+
not one of its dependencies. An application that had not installed the package got no winston record in
|
|
107
|
+
the logs pipeline and no message, although 1.0.4 and the README said `sendLogs` covers winston. The start
|
|
108
|
+
now warns once with `BYMAX_TELEMETRY_WINSTON_TRANSPORT_MISSING` when log sending is on, winston is
|
|
109
|
+
installed for the application and the transport cannot be resolved from the instrumentation. The README
|
|
110
|
+
says to install `@opentelemetry/winston-transport` as a direct dependency of the application, with what
|
|
111
|
+
was measured under npm and pnpm. The check asks whether winston is installed, not loaded, so an installed
|
|
112
|
+
winston the application never uses can warn once for nothing.
|
|
113
|
+
|
|
114
|
+
### Documentation
|
|
115
|
+
|
|
116
|
+
- The README says the node-redis measurements were taken with `redis` 5 and 6.
|
|
117
|
+
|
|
11
118
|
## [1.0.4] - 2026-11-14
|
|
12
119
|
|
|
13
120
|
### Security
|
|
@@ -207,6 +314,8 @@ First release.
|
|
|
207
314
|
- Verification from the packed tarball: real `node --import` processes in a CommonJS and a native-ESM
|
|
208
315
|
application, with planted secrets absent from the exported body and negative controls.
|
|
209
316
|
|
|
317
|
+
[1.0.6]: https://github.com/bymaxone/nest-telemetry/releases/tag/v1.0.6
|
|
318
|
+
[1.0.5]: https://github.com/bymaxone/nest-telemetry/releases/tag/v1.0.5
|
|
210
319
|
[1.0.4]: https://github.com/bymaxone/nest-telemetry/releases/tag/v1.0.4
|
|
211
320
|
[1.0.3]: https://github.com/bymaxone/nest-telemetry/releases/tag/v1.0.3
|
|
212
321
|
[1.0.2]: https://github.com/bymaxone/nest-telemetry/releases/tag/v1.0.2
|
package/README.md
CHANGED
|
@@ -81,13 +81,14 @@ Install it with the OpenTelemetry peers you use: the command is in [Quick Start]
|
|
|
81
81
|
|
|
82
82
|
One package, separate entry points. Import only what your app needs:
|
|
83
83
|
|
|
84
|
-
| Subpath
|
|
85
|
-
|
|
|
86
|
-
| **SDK**
|
|
87
|
-
| **Register**
|
|
88
|
-
| **Nest**
|
|
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`, `TELEMETRY_SHUTDOWN_TIMEOUT_KEY`, `TELEMETRY_EXPORT_FAILED_KEY`, `ITelemetryErrorLogger` (type) | NestJS 11 |
|
|
89
|
+
| **Observability** | `@bymax-one/nest-telemetry/observability` | `TelemetryMetrics`, `SPAN_EXPORT_FAILURES_METRIC` | NestJS 11, `@bymax-one/nest-core`, `prom-client` |
|
|
89
90
|
|
|
90
|
-
The SDK entry and `./register` import no `@nestjs/*` package; only `./nest`
|
|
91
|
+
The SDK entry and `./register` import no `@nestjs/*` package; only `./nest` and `./observability` do. `./observability` is optional: it needs `@bymax-one/nest-core` and `prom-client`, which are optional peers, and the other entries never load them. Requiring `./register` from CommonJS throws and names `node --import`.
|
|
91
92
|
|
|
92
93
|
---
|
|
93
94
|
|
|
@@ -165,22 +166,24 @@ This package installs no signal handler and shows none, because handling signals
|
|
|
165
166
|
|
|
166
167
|
Every field is the host's policy, and none is required.
|
|
167
168
|
|
|
168
|
-
| Option | Default | What it does
|
|
169
|
-
| -------------------------------------- | ---------------------------- |
|
|
170
|
-
| `enabled` | `true` | `false` never starts the SDK. `OTEL_SDK_DISABLED=true` disables it regardless.
|
|
171
|
-
| `serviceName` | `unknown_service:node` | The service name. `OTEL_SERVICE_NAME` overrides it.
|
|
172
|
-
| `serviceVersion` | none | The service version.
|
|
173
|
-
| `ignoreIncomingRequest` | none | Returns `true` for an incoming request that must produce no server span. `ignorePaths(patterns)` builds one from anchored patterns.
|
|
174
|
-
| `instrumentations.fs` | `false` | File-system instrumentation.
|
|
175
|
-
| `instrumentations.sendLogs` | follows `OTEL_LOGS_EXPORTER` | Whether the records of pino, winston and bunyan are forwarded to the OpenTelemetry logs pipeline.
|
|
176
|
-
| `instrumentations.overrides` | none | Per-instrumentation configuration, merged over the library's. Redaction settings cannot be replaced here.
|
|
177
|
-
| `extraRedactedQueryParams` | none | Names added to the list redacted from outgoing request URLs. They add to the defaults and never replace them.
|
|
178
|
-
| `unsafe.disableUrlRedaction` | off | Keeps `url.query`, `url.full`, `http.url` and `http.target` as recorded. Literal `true`. Warns.
|
|
179
|
-
| `unsafe.disableRedisArgumentRedaction` | off | Keeps Redis command arguments in `db.query.text`. Literal `true`. Warns.
|
|
180
|
-
| `unsafe.exportProcessCommandArgs` | off | Keeps `process.command_args`, `process.command_line` and `process.command` in the resource. Literal `true`. Warns.
|
|
181
|
-
| `unsafe.exportHostId` | off | Keeps `host.id`, the machine identifier, in the resource. Literal `true`. Warns.
|
|
182
|
-
| `shutdownTimeoutMs` | `5000` | The longest shutdown waits for the final flush. Past it, shutdown warns and resolves. A value that is not a finite number above zero, or is above `120000`, means the default.
|
|
183
|
-
| `env` | the process environment | The environment the library reads. The OpenTelemetry SDK itself always reads the process environment.
|
|
169
|
+
| Option | Default | What it does |
|
|
170
|
+
| -------------------------------------- | ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
171
|
+
| `enabled` | `true` | `false` never starts the SDK. `OTEL_SDK_DISABLED=true` disables it regardless. |
|
|
172
|
+
| `serviceName` | `unknown_service:node` | The service name. `OTEL_SERVICE_NAME` overrides it. |
|
|
173
|
+
| `serviceVersion` | none | The service version. |
|
|
174
|
+
| `ignoreIncomingRequest` | none | Returns `true` for an incoming request that must produce no server span. `ignorePaths(patterns)` builds one from anchored patterns. |
|
|
175
|
+
| `instrumentations.fs` | `false` | File-system instrumentation. |
|
|
176
|
+
| `instrumentations.sendLogs` | follows `OTEL_LOGS_EXPORTER` | Whether the records of pino, winston and bunyan are forwarded to the OpenTelemetry logs pipeline. Winston also needs `@opentelemetry/winston-transport` installed by your application, see [Forwarding log records](#forwarding-log-records). |
|
|
177
|
+
| `instrumentations.overrides` | none | Per-instrumentation configuration, merged over the library's. Redaction settings cannot be replaced here. |
|
|
178
|
+
| `extraRedactedQueryParams` | none | Names added to the list redacted from outgoing request URLs. They add to the defaults and never replace them. |
|
|
179
|
+
| `unsafe.disableUrlRedaction` | off | Keeps `url.query`, `url.full`, `http.url` and `http.target` as recorded. Literal `true`. Warns. |
|
|
180
|
+
| `unsafe.disableRedisArgumentRedaction` | off | Keeps Redis command arguments in `db.query.text`. Literal `true`. Warns. |
|
|
181
|
+
| `unsafe.exportProcessCommandArgs` | off | Keeps `process.command_args`, `process.command_line` and `process.command` in the resource. Literal `true`. Warns. |
|
|
182
|
+
| `unsafe.exportHostId` | off | Keeps `host.id`, the machine identifier, in the resource. Literal `true`. Warns. |
|
|
183
|
+
| `shutdownTimeoutMs` | `5000` | The longest shutdown waits for the final flush. Past it, shutdown warns and resolves. A value that is not a finite number above zero, or is above `120000`, means the default. |
|
|
184
|
+
| `env` | the process environment | The environment the library reads. The OpenTelemetry SDK itself always reads the process environment. |
|
|
185
|
+
|
|
186
|
+
A key set to `undefined` or `null` in any option is the same as no key. An override is copied by its own enumerable keys, so pass a plain object: getters on a class prototype are not read.
|
|
184
187
|
|
|
185
188
|
### Environment variables
|
|
186
189
|
|
|
@@ -206,26 +209,71 @@ The OpenTelemetry SDK reads these itself, and the library never touches them: `O
|
|
|
206
209
|
|
|
207
210
|
The start emits these warnings:
|
|
208
211
|
|
|
209
|
-
| Code | Meaning
|
|
210
|
-
| ------------------------------------------- |
|
|
211
|
-
| `BYMAX_TELEMETRY_START_FAILED` | The SDK could not start (a peer is missing, or the SDK threw). Tracing is off.
|
|
212
|
-
| `BYMAX_TELEMETRY_ESM_HOOK_UNAVAILABLE` | The loader hook could not be registered. Native-ESM code is not instrumented.
|
|
213
|
-
| `BYMAX_TELEMETRY_SERVICE_NAME_MISSING` | No service name is set; spans use `unknown_service:node`.
|
|
214
|
-
| `BYMAX_TELEMETRY_UNSAFE_REDACTION_DISABLED` | A redaction was turned off through an `unsafe` option.
|
|
215
|
-
| `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.
|
|
216
|
-
| `BYMAX_TELEMETRY_RESTART_UNSUPPORTED` | `startTelemetry` was called after a shutdown in the same process, and is refused.
|
|
217
|
-
| `BYMAX_TELEMETRY_SHUTDOWN_TIMEOUT` | The final flush did not finish within `shutdownTimeoutMs`. Shutdown resolved without it, and spans still queued may be lost. With `TelemetryModule` and a bound `TELEMETRY_LOGGER`, it is reported through `errorStructured` under `TRACING_SHUTDOWN_TIMEOUT` instead.
|
|
218
|
-
| `BYMAX_TELEMETRY_EXPORT_FAILED` | A span export failed, so the batch was dropped. The warning names the exporter and a short error code, never the payload or the endpoint, and repeats at most once a minute. With `TelemetryModule` and a bound `TELEMETRY_LOGGER` that has `warnStructured`, it is reported through it under `TRACING_EXPORT_FAILED` instead.
|
|
219
|
-
| `
|
|
212
|
+
| Code | Meaning |
|
|
213
|
+
| ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
214
|
+
| `BYMAX_TELEMETRY_START_FAILED` | The SDK could not start (a peer is missing, or the SDK threw). Tracing is off. |
|
|
215
|
+
| `BYMAX_TELEMETRY_ESM_HOOK_UNAVAILABLE` | The loader hook could not be registered. Native-ESM code is not instrumented. The warning names the error's code and package in the same way. |
|
|
216
|
+
| `BYMAX_TELEMETRY_SERVICE_NAME_MISSING` | No service name is set; spans use `unknown_service:node`. |
|
|
217
|
+
| `BYMAX_TELEMETRY_UNSAFE_REDACTION_DISABLED` | A redaction was turned off through an `unsafe` option. |
|
|
218
|
+
| `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. |
|
|
219
|
+
| `BYMAX_TELEMETRY_RESTART_UNSUPPORTED` | `startTelemetry` was called after a shutdown in the same process, and is refused. |
|
|
220
|
+
| `BYMAX_TELEMETRY_SHUTDOWN_TIMEOUT` | The final flush did not finish within `shutdownTimeoutMs`. Shutdown resolved without it, and spans still queued may be lost. With `TelemetryModule` and a bound `TELEMETRY_LOGGER`, it is reported through `errorStructured` under `TRACING_SHUTDOWN_TIMEOUT` instead. |
|
|
221
|
+
| `BYMAX_TELEMETRY_EXPORT_FAILED` | A span export failed, so the batch was dropped. The warning names the exporter and a short error code, never the payload or the endpoint, and repeats at most once a minute. With `TelemetryModule` and a bound `TELEMETRY_LOGGER` that has `warnStructured`, it is reported through it under `TRACING_EXPORT_FAILED` instead. |
|
|
222
|
+
| `BYMAX_TELEMETRY_SAMPLER_ARG_INVALID` | A ratio sampler (`traceidratio` or `parentbased_traceidratio`) is selected and `OTEL_TRACES_SAMPLER_ARG` is unset, blank or not a number from 0 to 1, so the SDK samples every trace. Set the share of traces to keep, such as `0.1`. |
|
|
223
|
+
| `BYMAX_TELEMETRY_SAMPLER_NAME_UNKNOWN` | `OTEL_TRACES_SAMPLER` differs from a sampler name the SDK knows only in letter case or surrounding whitespace. The SDK compares the name exactly, ignores the value and samples every trace. Write the name exactly, as the warning says. |
|
|
224
|
+
| `BYMAX_TELEMETRY_WINSTON_TRANSPORT_MISSING` | Log forwarding is on and winston is installed, but `@opentelemetry/winston-transport` cannot be resolved from the winston instrumentation, so winston records are not forwarded. Install it as a direct dependency of the application, or ignore the warning when your application never creates a winston logger or `OTEL_LOGS_EXPORTER` is `none`. |
|
|
225
|
+
| `BYMAX_TELEMETRY_BSP_VALUE_IGNORED` | An `OTEL_BSP_SCHEDULE_DELAY` or `OTEL_BSP_EXPORT_TIMEOUT` above 2147483647 ms was ignored, because a timer cannot hold it and Node would clamp it to 1 ms. The default applies. |
|
|
220
226
|
|
|
221
227
|
The programmatic `startTelemetry` keeps its rejection when the SDK cannot start, for callers that want it.
|
|
222
228
|
|
|
223
229
|
### What is traced
|
|
224
230
|
|
|
225
231
|
- **Load order matters only for modules your application loads itself.** The core `http` module is patched even when the preload runs after it. A client such as `ioredis` is patched only if the preload ran before the application required it. Measured: an application that required `ioredis` first exported no `ioredis` span.
|
|
226
|
-
- **`ioredis` commands are traced only under an active span; node-redis commands are not.** The `ioredis` instrumentation defaults to `requireParentSpan: true`, so a command issued outside any request produces no span. The node-redis (`redis`) instrumentation defaults to `false`, so it traces a command with no request around it too. Measured with `redis` 5.
|
|
232
|
+
- **`ioredis` commands are traced only under an active span; node-redis commands are not.** The `ioredis` instrumentation defaults to `requireParentSpan: true`, so a command issued outside any request produces no span. The node-redis (`redis`) instrumentation defaults to `false`, so it traces a command with no request around it too. Measured with `redis` 5 and 6.
|
|
227
233
|
- **`fs` instrumentation is off by default**, because it floods traces with disk activity that has no context. Turn it on with `instrumentations.fs`.
|
|
228
234
|
|
|
235
|
+
### Forwarding log records
|
|
236
|
+
|
|
237
|
+
With `OTEL_LOGS_EXPORTER=otlp`, or `instrumentations.sendLogs: true`, the records of pino, winston and bunyan go to the OpenTelemetry logs pipeline. Winston needs one more package: install `@opentelemetry/winston-transport` as a direct dependency of your application. The winston instrumentation loads it with a `require` from its own directory, and the package is not one of that instrumentation's dependencies, so without it winston records are not forwarded. Measured with winston 3.19.0 and `@opentelemetry/winston-transport` 0.35.0: a winston record reached the collector when the package was a direct dependency under npm, under pnpm 11.20.0 with the default layout and under pnpm with `hoist=false`, and it did not under npm without the package. A package that reaches the project only as another package's dependency was not measured.
|
|
238
|
+
|
|
239
|
+
At start the library warns once, with `BYMAX_TELEMETRY_WINSTON_TRANSPORT_MISSING`, when log sending is on, winston resolves from the script that started the application (from the working directory when there is none), and the transport does not resolve from the winston instrumentation, which is found through `@opentelemetry/auto-instrumentations-node`. The check asks whether winston is installed, not whether it is loaded, because winston is usually not loaded yet at start: an installed winston that your application never uses causes one warning for nothing. The warning also appears with `instrumentations.sendLogs: true` while `OTEL_LOGS_EXPORTER` is `none`, where no record is forwarded whether the transport is installed or not, and with the `console` exporter, where it is correct.
|
|
240
|
+
|
|
241
|
+
### Metrics
|
|
242
|
+
|
|
243
|
+
With `@bymax-one/nest-core` and `prom-client` installed, the application can publish how many span exports failed. Provide `TelemetryMetrics` from `@bymax-one/nest-telemetry/observability` in any module; `BymaxCoreModule` finds it and hands it the registry its scrape endpoint serves, only when its metrics feature is on. With metrics off, nothing is created.
|
|
244
|
+
|
|
245
|
+
```ts
|
|
246
|
+
import { Module } from '@nestjs/common'
|
|
247
|
+
import { TelemetryMetrics } from '@bymax-one/nest-telemetry/observability'
|
|
248
|
+
|
|
249
|
+
@Module({ providers: [TelemetryMetrics] })
|
|
250
|
+
export class ObservabilityModule {}
|
|
251
|
+
```
|
|
252
|
+
|
|
253
|
+
| Metric | Type | Labels | Meaning |
|
|
254
|
+
| -------------------------------------------- | ------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
255
|
+
| `bymax_telemetry_span_export_failures_total` | counter | none | Span export batches the collector did not accept, so the batch was dropped. Every failure is counted, while `BYMAX_TELEMETRY_EXPORT_FAILED` warns at most once a minute. |
|
|
256
|
+
|
|
257
|
+
The count is the number of failed exports since the process started. It lives on `globalThis`, as the handle does, so it is the same when the SDK starts from the preload and the application loads the library again. The series exists with a value of 0 before the first failure, so an alert on `increase(bymax_telemetry_span_export_failures_total[5m]) > 0` needs no special case. Register the contributor at most once per registry: a second registration of the name fails the boot, and says which name.
|
|
258
|
+
|
|
259
|
+
### Span names across the Bymax libraries
|
|
260
|
+
|
|
261
|
+
This library starts the SDK and traces what the OpenTelemetry instrumentations cover (HTTP, Redis, databases). The Bymax libraries add spans of their own for their domain operations, under the name `<library>.<operation>`, through the optional `@opentelemetry/api`: with no SDK registered the API does nothing, and with this one started the spans are exported like any other. The standard asks that their attributes use the `bymax.<library>.<attribute>` namespace and closed sets of values, with no secret, no user or tenant id and no payload, and that a failure set the span status to error with the library's error code.
|
|
262
|
+
|
|
263
|
+
The names below are the ones the Bymax observability standard reserves for each library; they are not read from this repository. A library emits one from the release whose CHANGELOG lists it, and its own README documents the attributes.
|
|
264
|
+
|
|
265
|
+
| Library | Span names |
|
|
266
|
+
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------- |
|
|
267
|
+
| [nest-auth](https://github.com/bymaxone/nest-auth) | `auth.login`, `auth.refresh`, `auth.mfa.verify`, `auth.password_reset` |
|
|
268
|
+
| [nest-queue](https://github.com/bymaxone/nest-queue) | `queue.enqueue`, `queue.process` |
|
|
269
|
+
| [nest-notification](https://github.com/bymaxone/nest-notification) | `notification.send`, `notification.otp.verify` |
|
|
270
|
+
| [nest-storage](https://github.com/bymaxone/nest-storage) | `storage.upload`, `storage.download_url`, `storage.scan` |
|
|
271
|
+
| [nest-realtime](https://github.com/bymaxone/nest-realtime) | `realtime.handshake`, `realtime.reauthenticate` |
|
|
272
|
+
| [nest-ai-tokens](https://github.com/bymaxone/nest-ai-tokens) | `ai_tokens.consume`, `ai_tokens.hold`, `ai_tokens.settle` |
|
|
273
|
+
| [nest-core](https://github.com/bymaxone/nest-core), [nest-cache](https://github.com/bymaxone/nest-cache), [nest-logger](https://github.com/bymaxone/nest-logger), [nest-config](https://github.com/bymaxone/nest-config) | none: HTTP and Redis are traced by the instrumentations, and the other work is not a domain operation |
|
|
274
|
+
|
|
275
|
+
The standard asks `nest-queue` to carry the trace context from the request that enqueues a job into the job, as a W3C `traceparent` in the job's options metadata, so a request, its job and the job's side effects form one trace. That needs the SDK's default propagator: a host that sets `OTEL_PROPAGATORS` to a list without `tracecontext` breaks it. With no SDK registered the propagation writes nothing, and a job without a `traceparent` starts its own trace.
|
|
276
|
+
|
|
229
277
|
### Flushing
|
|
230
278
|
|
|
231
279
|
Awaiting `shutdown()` or `shutdownTelemetry()` means the spans were exported, whoever started the flush, unless the deadline below passed first: overlapping callers wait for the same flush, and a shutdown that arrives while the SDK is still starting waits for the start and then stops what it built. A flush the collector refuses is reported, never thrown into your shutdown path, by the Nest module; the programmatic functions reject, so their caller decides.
|
|
@@ -240,7 +288,7 @@ A start after a shutdown in the same process is refused: `startTelemetry` reject
|
|
|
240
288
|
|
|
241
289
|
Every figure here was measured on one laptop, with Node 24 and a handler that does nothing but answer. Read them as orders of magnitude for your own measurement to confirm, not as promises.
|
|
242
290
|
|
|
243
|
-
- **Sampling.** The default samples every trace. For high traffic set `OTEL_TRACES_SAMPLER=parentbased_traceidratio` and `OTEL_TRACES_SAMPLER_ARG=0.1`. Of 2,000 spans created in one run each, the default exported all of them, a ratio of `0.1` exported 210 and a ratio of `0.01` exported 25.
|
|
291
|
+
- **Sampling.** The default samples every trace. For high traffic set `OTEL_TRACES_SAMPLER=parentbased_traceidratio` and `OTEL_TRACES_SAMPLER_ARG=0.1`. Of 2,000 spans created in one run each, the default exported all of them, a ratio of `0.1` exported 210 and a ratio of `0.01` exported 25. A ratio sampler needs `OTEL_TRACES_SAMPLER_ARG` to be a number from 0 to 1. When it is unset, empty or only whitespace, not a number or outside that range, the SDK falls back to a ratio of 1 and samples every trace, noting it only on a diagnostic channel; the start warns once with `BYMAX_TELEMETRY_SAMPLER_ARG_INVALID`, naming the variable and, when one was given, the value (a blank value is called blank, not unset). The SDK matches the sampler name exactly: `always_on`, `always_off`, `traceidratio`, `parentbased_always_on`, `parentbased_always_off` and `parentbased_traceidratio`, in lower case and without surrounding whitespace. Any other value, `TraceIdRatio` included, is replaced by its default and samples every trace; when the value differs from one of those names only in letter case or surrounding whitespace, the start warns once with `BYMAX_TELEMETRY_SAMPLER_NAME_UNKNOWN`, naming the name that was meant and not repeating the value. It reads the process environment, as the SDK does, and not the `env` option.
|
|
244
292
|
- **TLS to the collector.** Against a collector whose certificate Node does not trust, every export failed with `self-signed certificate`. Setting `OTEL_EXPORTER_OTLP_CERTIFICATE` to the CA file, or `NODE_EXTRA_CA_CERTS`, exported all 2,000 spans in the same setup.
|
|
245
293
|
- **A collector that is down.** The batch is dropped and the library emits `BYMAX_TELEMETRY_EXPORT_FAILED`, at most once a minute. Shutdown stops waiting at `shutdownTimeoutMs`, 5 seconds by default. Before that deadline existed, shutdown against a closed port took 7,048 ms and 7,214 ms in two runs.
|
|
246
294
|
- **CPU.** One process, 4 runs per mode, median CPU time per request: 25 µs without the library, 26 µs with it loaded and disabled, 58 µs with a healthy collector (range 35 to 66) and 43 µs with the collector down (range 26 to 65). The extra cost in that handler is roughly 10 to 40 µs per request, and a handler that does real I/O dilutes it. The same configuration varied by up to a factor of two between runs.
|
|
@@ -272,8 +320,10 @@ A caret on a `0.x` version allows patch releases only, so each OpenTelemetry min
|
|
|
272
320
|
| No spans at all | `OTEL_SDK_DISABLED`; that the application was started with `--import`; `OTEL_EXPORTER_OTLP_ENDPOINT`; the start warnings. |
|
|
273
321
|
| Spans from a CommonJS app but none from a native-ESM app | `BYMAX_TELEMETRY_ESM_HOOK_UNAVAILABLE`: install `@opentelemetry/instrumentation`. |
|
|
274
322
|
| Spans arrive but carry no service name | `BYMAX_TELEMETRY_SERVICE_NAME_MISSING`: set `OTEL_SERVICE_NAME` or the `serviceName` option. A name set only through `OTEL_RESOURCE_ATTRIBUTES` still reaches the spans, unless `OTEL_NODE_RESOURCE_DETECTORS` leaves out both the `env` and the `service` detector. |
|
|
275
|
-
| `BYMAX_TELEMETRY_START_FAILED` | The warning names the
|
|
323
|
+
| `BYMAX_TELEMETRY_START_FAILED` | The warning names the error's code and, when the message names one, the OpenTelemetry package, usually a peer that is not installed. It never repeats the message, which can quote configuration. |
|
|
276
324
|
| HTTP spans but no Redis spans | `ioredis` commands are traced under an active span only, and the client must be loaded after the preload. |
|
|
325
|
+
| More traces than the sampling ratio should keep | `BYMAX_TELEMETRY_SAMPLER_ARG_INVALID`: `OTEL_TRACES_SAMPLER_ARG` is unset, blank or not a number from 0 to 1, so the SDK samples every trace; or `BYMAX_TELEMETRY_SAMPLER_NAME_UNKNOWN`: `OTEL_TRACES_SAMPLER` is not written exactly (letter case or whitespace). |
|
|
326
|
+
| Winston records missing from the logs pipeline | `BYMAX_TELEMETRY_WINSTON_TRANSPORT_MISSING`: install `@opentelemetry/winston-transport` as a direct dependency of the application. |
|
|
277
327
|
| Metrics or logs missing | They are off unless `OTEL_METRICS_EXPORTER` or `OTEL_LOGS_EXPORTER` names an exporter. |
|
|
278
328
|
| The last spans of another module are lost when the application closes | List `TelemetryModule` first in the application module's imports, so it closes last. |
|
|
279
329
|
| No spans arrive and nothing else is logged | `BYMAX_TELEMETRY_EXPORT_FAILED`: the collector did not accept the export. Check the endpoint in `OTEL_EXPORTER_OTLP_ENDPOINT` and that the collector is reachable. |
|
|
@@ -401,15 +451,22 @@ No exports. `node --import @bymax-one/nest-telemetry/register` registers the loa
|
|
|
401
451
|
|
|
402
452
|
### Nest: `@bymax-one/nest-telemetry/nest`
|
|
403
453
|
|
|
404
|
-
| Export | Kind | Purpose
|
|
405
|
-
| -------------------------------- | -------- |
|
|
406
|
-
| `TelemetryModule` | module | Global; registers `TelemetryShutdownHook`. List it first in the application module's imports
|
|
407
|
-
| `TelemetryShutdownHook` | provider | `OnApplicationShutdown`: awaits `shutdownTelemetry()`; a refused flush is reported and never rejects
|
|
408
|
-
| `TELEMETRY_LOGGER` | token | Optional provider with an `errorStructured(logKey, error)` method for a failed flush and a shutdown that hit its deadline, and an optional `warnStructured(logKey, message, userId, metadata)` for a failed export |
|
|
409
|
-
| `TELEMETRY_FLUSH_FAILED_KEY` | constant | The stable key, `TRACING_FLUSH_FAILED`, under which a failed flush is reported
|
|
410
|
-
| `TELEMETRY_SHUTDOWN_TIMEOUT_KEY` | constant | The stable key, `TRACING_SHUTDOWN_TIMEOUT`, under which a shutdown that hit `shutdownTimeoutMs` is reported
|
|
411
|
-
| `TELEMETRY_EXPORT_FAILED_KEY` | constant | The stable key, `TRACING_EXPORT_FAILED`, under which a failed span export is reported, with the exporter kind and the error code as metadata
|
|
412
|
-
| `ITelemetryErrorLogger` | type | The shape `TELEMETRY_LOGGER` provides: `errorStructured(logKey, error)` and an optional `warnStructured`
|
|
454
|
+
| Export | Kind | Purpose |
|
|
455
|
+
| -------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
456
|
+
| `TelemetryModule` | module | Global; registers `TelemetryShutdownHook`. List it first in the application module's imports |
|
|
457
|
+
| `TelemetryShutdownHook` | provider | `OnApplicationShutdown`: awaits `shutdownTelemetry()`; a refused flush is reported and never rejects |
|
|
458
|
+
| `TELEMETRY_LOGGER` | token | Optional provider with an `errorStructured(logKey, error)` method for a failed flush and a shutdown that hit its deadline, and an optional `warnStructured(logKey, message, userId, metadata)` for a failed export. Without it, a failed flush goes to the Nest logger under `TRACING_FLUSH_FAILED` with a short error code and no message or stack, which can carry the collector's endpoint |
|
|
459
|
+
| `TELEMETRY_FLUSH_FAILED_KEY` | constant | The stable key, `TRACING_FLUSH_FAILED`, under which a failed flush is reported |
|
|
460
|
+
| `TELEMETRY_SHUTDOWN_TIMEOUT_KEY` | constant | The stable key, `TRACING_SHUTDOWN_TIMEOUT`, under which a shutdown that hit `shutdownTimeoutMs` is reported |
|
|
461
|
+
| `TELEMETRY_EXPORT_FAILED_KEY` | constant | The stable key, `TRACING_EXPORT_FAILED`, under which a failed span export is reported, with the exporter kind and the error code as metadata |
|
|
462
|
+
| `ITelemetryErrorLogger` | type | The shape `TELEMETRY_LOGGER` provides: `errorStructured(logKey, error)` and an optional `warnStructured` |
|
|
463
|
+
|
|
464
|
+
### Observability: `@bymax-one/nest-telemetry/observability`
|
|
465
|
+
|
|
466
|
+
| Export | Kind | Purpose |
|
|
467
|
+
| ----------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
468
|
+
| `TelemetryMetrics` | provider | A `@bymax-one/nest-core` metrics contributor: registers the `bymax_telemetry_span_export_failures_total` counter on the registry it is handed, with no label |
|
|
469
|
+
| `SPAN_EXPORT_FAILURES_METRIC` | constant | The metric name, `bymax_telemetry_span_export_failures_total` |
|
|
413
470
|
|
|
414
471
|
---
|
|
415
472
|
|
package/dist/nest/index.cjs
CHANGED
|
@@ -13,6 +13,19 @@ var __decorateClass = (decorators, target, key, kind) => {
|
|
|
13
13
|
};
|
|
14
14
|
var __decorateParam = (index, decorator) => (target, key) => decorator(target, key, index);
|
|
15
15
|
|
|
16
|
+
// src/sdk/error-code.ts
|
|
17
|
+
var CODE_TOKEN = /^[A-Z0-9_]{1,40}$/;
|
|
18
|
+
function codeOf(error) {
|
|
19
|
+
try {
|
|
20
|
+
const code = Reflect.get(Object(error), "code");
|
|
21
|
+
if (typeof code !== "string" && typeof code !== "number") return "UNKNOWN";
|
|
22
|
+
const text = String(code);
|
|
23
|
+
return CODE_TOKEN.test(text) ? text : "UNKNOWN";
|
|
24
|
+
} catch {
|
|
25
|
+
return "UNKNOWN";
|
|
26
|
+
}
|
|
27
|
+
}
|
|
28
|
+
|
|
16
29
|
// src/sdk/warning-sink.ts
|
|
17
30
|
var SINK_KEY = /* @__PURE__ */ Symbol.for("@bymax-one/nest-telemetry/warning-sink");
|
|
18
31
|
function registerWarningSink(sink) {
|
|
@@ -123,8 +136,7 @@ exports.TelemetryShutdownHook = class TelemetryShutdownHook {
|
|
|
123
136
|
}
|
|
124
137
|
try {
|
|
125
138
|
new common.Logger("Telemetry").error(
|
|
126
|
-
`${TELEMETRY_FLUSH_FAILED_KEY}: ${failure.
|
|
127
|
-
failure.stack
|
|
139
|
+
`${TELEMETRY_FLUSH_FAILED_KEY}: the telemetry flush failed (code ${codeOf(failure)}). Bind TELEMETRY_LOGGER to receive the error itself.`
|
|
128
140
|
);
|
|
129
141
|
} catch {
|
|
130
142
|
}
|
package/dist/nest/index.mjs
CHANGED
|
@@ -11,6 +11,19 @@ var __decorateClass = (decorators, target, key, kind) => {
|
|
|
11
11
|
};
|
|
12
12
|
var __decorateParam = (index, decorator) => (target, key) => decorator(target, key, index);
|
|
13
13
|
|
|
14
|
+
// src/sdk/error-code.ts
|
|
15
|
+
var CODE_TOKEN = /^[A-Z0-9_]{1,40}$/;
|
|
16
|
+
function codeOf(error) {
|
|
17
|
+
try {
|
|
18
|
+
const code = Reflect.get(Object(error), "code");
|
|
19
|
+
if (typeof code !== "string" && typeof code !== "number") return "UNKNOWN";
|
|
20
|
+
const text = String(code);
|
|
21
|
+
return CODE_TOKEN.test(text) ? text : "UNKNOWN";
|
|
22
|
+
} catch {
|
|
23
|
+
return "UNKNOWN";
|
|
24
|
+
}
|
|
25
|
+
}
|
|
26
|
+
|
|
14
27
|
// src/sdk/warning-sink.ts
|
|
15
28
|
var SINK_KEY = /* @__PURE__ */ Symbol.for("@bymax-one/nest-telemetry/warning-sink");
|
|
16
29
|
function registerWarningSink(sink) {
|
|
@@ -121,8 +134,7 @@ var TelemetryShutdownHook = class {
|
|
|
121
134
|
}
|
|
122
135
|
try {
|
|
123
136
|
new Logger("Telemetry").error(
|
|
124
|
-
`${TELEMETRY_FLUSH_FAILED_KEY}: ${failure.
|
|
125
|
-
failure.stack
|
|
137
|
+
`${TELEMETRY_FLUSH_FAILED_KEY}: the telemetry flush failed (code ${codeOf(failure)}). Bind TELEMETRY_LOGGER to receive the error itself.`
|
|
126
138
|
);
|
|
127
139
|
} catch {
|
|
128
140
|
}
|
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
|
|
3
|
+
var metrics = require('@bymax-one/nest-core/metrics');
|
|
4
|
+
var common = require('@nestjs/common');
|
|
5
|
+
var promClient = require('prom-client');
|
|
6
|
+
|
|
7
|
+
var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
|
|
8
|
+
var __decorateClass = (decorators, target, key, kind) => {
|
|
9
|
+
var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc(target, key) : target;
|
|
10
|
+
for (var i = decorators.length - 1, decorator; i >= 0; i--)
|
|
11
|
+
if (decorator = decorators[i])
|
|
12
|
+
result = (decorator(result)) || result;
|
|
13
|
+
return result;
|
|
14
|
+
};
|
|
15
|
+
|
|
16
|
+
// src/sdk/export-failure.ts
|
|
17
|
+
var COUNT_KEY = /* @__PURE__ */ Symbol.for("@bymax-one/nest-telemetry/export-failures");
|
|
18
|
+
function exportFailureCount() {
|
|
19
|
+
const count = Reflect.get(globalThis, COUNT_KEY);
|
|
20
|
+
return typeof count === "number" ? count : 0;
|
|
21
|
+
}
|
|
22
|
+
|
|
23
|
+
// src/observability/telemetry-metrics.ts
|
|
24
|
+
var SPAN_EXPORT_FAILURES_METRIC = "bymax_telemetry_span_export_failures_total";
|
|
25
|
+
exports.TelemetryMetrics = class TelemetryMetrics {
|
|
26
|
+
/**
|
|
27
|
+
* Registers the counter on the shared registry.
|
|
28
|
+
*
|
|
29
|
+
* @param registry - The registry the scrape endpoint serves.
|
|
30
|
+
*/
|
|
31
|
+
registerMetrics(registry) {
|
|
32
|
+
let published = 0;
|
|
33
|
+
new promClient.Counter({
|
|
34
|
+
name: SPAN_EXPORT_FAILURES_METRIC,
|
|
35
|
+
help: "Span export batches the collector did not accept, so the batch was dropped.",
|
|
36
|
+
registers: [registry],
|
|
37
|
+
collect() {
|
|
38
|
+
const total = exportFailureCount();
|
|
39
|
+
if (total > published) this.inc(total - published);
|
|
40
|
+
published = total;
|
|
41
|
+
}
|
|
42
|
+
});
|
|
43
|
+
}
|
|
44
|
+
};
|
|
45
|
+
exports.TelemetryMetrics = __decorateClass([
|
|
46
|
+
metrics.BymaxMetricsContributor(),
|
|
47
|
+
common.Injectable()
|
|
48
|
+
], exports.TelemetryMetrics);
|
|
49
|
+
|
|
50
|
+
exports.SPAN_EXPORT_FAILURES_METRIC = SPAN_EXPORT_FAILURES_METRIC;
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
import { IMetricsContributor, MetricsRegistry } from '@bymax-one/nest-core/metrics';
|
|
2
|
+
|
|
3
|
+
/** The name of the counter, stable so an alert can match it. */
|
|
4
|
+
declare const SPAN_EXPORT_FAILURES_METRIC = "bymax_telemetry_span_export_failures_total";
|
|
5
|
+
/**
|
|
6
|
+
* Publishes `bymax_telemetry_span_export_failures_total`, the number of span export batches the
|
|
7
|
+
* collector did not accept, on the registry `BymaxCoreModule` hands every contributor. The counter
|
|
8
|
+
* has no label.
|
|
9
|
+
*/
|
|
10
|
+
declare class TelemetryMetrics implements IMetricsContributor {
|
|
11
|
+
/**
|
|
12
|
+
* Registers the counter on the shared registry.
|
|
13
|
+
*
|
|
14
|
+
* @param registry - The registry the scrape endpoint serves.
|
|
15
|
+
*/
|
|
16
|
+
registerMetrics(registry: MetricsRegistry): void;
|
|
17
|
+
}
|
|
18
|
+
|
|
19
|
+
export { SPAN_EXPORT_FAILURES_METRIC, TelemetryMetrics };
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
import { IMetricsContributor, MetricsRegistry } from '@bymax-one/nest-core/metrics';
|
|
2
|
+
|
|
3
|
+
/** The name of the counter, stable so an alert can match it. */
|
|
4
|
+
declare const SPAN_EXPORT_FAILURES_METRIC = "bymax_telemetry_span_export_failures_total";
|
|
5
|
+
/**
|
|
6
|
+
* Publishes `bymax_telemetry_span_export_failures_total`, the number of span export batches the
|
|
7
|
+
* collector did not accept, on the registry `BymaxCoreModule` hands every contributor. The counter
|
|
8
|
+
* has no label.
|
|
9
|
+
*/
|
|
10
|
+
declare class TelemetryMetrics implements IMetricsContributor {
|
|
11
|
+
/**
|
|
12
|
+
* Registers the counter on the shared registry.
|
|
13
|
+
*
|
|
14
|
+
* @param registry - The registry the scrape endpoint serves.
|
|
15
|
+
*/
|
|
16
|
+
registerMetrics(registry: MetricsRegistry): void;
|
|
17
|
+
}
|
|
18
|
+
|
|
19
|
+
export { SPAN_EXPORT_FAILURES_METRIC, TelemetryMetrics };
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
import { BymaxMetricsContributor } from '@bymax-one/nest-core/metrics';
|
|
2
|
+
import { Injectable } from '@nestjs/common';
|
|
3
|
+
import { Counter } from 'prom-client';
|
|
4
|
+
|
|
5
|
+
var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
|
|
6
|
+
var __decorateClass = (decorators, target, key, kind) => {
|
|
7
|
+
var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc(target, key) : target;
|
|
8
|
+
for (var i = decorators.length - 1, decorator; i >= 0; i--)
|
|
9
|
+
if (decorator = decorators[i])
|
|
10
|
+
result = (decorator(result)) || result;
|
|
11
|
+
return result;
|
|
12
|
+
};
|
|
13
|
+
|
|
14
|
+
// src/sdk/export-failure.ts
|
|
15
|
+
var COUNT_KEY = /* @__PURE__ */ Symbol.for("@bymax-one/nest-telemetry/export-failures");
|
|
16
|
+
function exportFailureCount() {
|
|
17
|
+
const count = Reflect.get(globalThis, COUNT_KEY);
|
|
18
|
+
return typeof count === "number" ? count : 0;
|
|
19
|
+
}
|
|
20
|
+
|
|
21
|
+
// src/observability/telemetry-metrics.ts
|
|
22
|
+
var SPAN_EXPORT_FAILURES_METRIC = "bymax_telemetry_span_export_failures_total";
|
|
23
|
+
var TelemetryMetrics = class {
|
|
24
|
+
/**
|
|
25
|
+
* Registers the counter on the shared registry.
|
|
26
|
+
*
|
|
27
|
+
* @param registry - The registry the scrape endpoint serves.
|
|
28
|
+
*/
|
|
29
|
+
registerMetrics(registry) {
|
|
30
|
+
let published = 0;
|
|
31
|
+
new Counter({
|
|
32
|
+
name: SPAN_EXPORT_FAILURES_METRIC,
|
|
33
|
+
help: "Span export batches the collector did not accept, so the batch was dropped.",
|
|
34
|
+
registers: [registry],
|
|
35
|
+
collect() {
|
|
36
|
+
const total = exportFailureCount();
|
|
37
|
+
if (total > published) this.inc(total - published);
|
|
38
|
+
published = total;
|
|
39
|
+
}
|
|
40
|
+
});
|
|
41
|
+
}
|
|
42
|
+
};
|
|
43
|
+
TelemetryMetrics = __decorateClass([
|
|
44
|
+
BymaxMetricsContributor(),
|
|
45
|
+
Injectable()
|
|
46
|
+
], TelemetryMetrics);
|
|
47
|
+
|
|
48
|
+
export { SPAN_EXPORT_FAILURES_METRIC, TelemetryMetrics };
|