rules/diagnostics-channel.md
GitHubdiagnostics_channel: bounded channels, scopes, TracingChannel, built-in channels
Source: doc/api/diagnostics_channel.md at nodejs/node ab476eccd03.
Verified on v28.0.0-pre, v26.13.0, and v24.19.0 by examples/bounded-channel.mjs,
store-scope.mjs, trace-promise.mjs, trace-promise-compat.mjs, tracing-instrument.mjs, channel-*.mjs.
TracingChannel (Stable since v26.8.0)
tracingChannel(name) has been around since v19.9.0/v18.19.0. It was promoted from
Experimental to Stable in v26.8.0, and the API itself did not change. It uses five
channels named tracing:${name}:{start,end,asyncStart,asyncEnd,error}. One context
object flows through all of them and receives result or error.
tracePromise(fn, context, thisArg, ...args) changes:
| Version | Return value when subscribers exist |
|---|---|
| v24.x | always a native Promise. A custom thenable is converted, and a non-thenable is wrapped (async events still fire) |
| v26.0.0+ | a non-thenable is returned as-is with a process Warning ("returned a non-thenable"). Only start/end fire |
| v26.5.0+ | a non-native thenable is returned as-is with its own methods. Async events fire when it settles |
On v26+, the non-thenable warning is emitted even when the channel has no subscribers.
On v24 with no subscribers, fn is called directly and its raw value is returned.
Library pattern: create the channel once at module top level. Check ch.hasSubscribers
before building the context object. Name channels module.class.method or module.function.
BoundedChannel (v26.1.0, Stability 1; not on v24)
import { boundedChannel, BoundedChannel } from 'node:diagnostics_channel';
const bc = boundedChannel('mylib.parse'); // or boundedChannel({ start, end })
bc.start === channel('tracing:mylib.parse:start'); // same naming as TracingChannel
bc.subscribe({ start(ctx) {}, end(ctx) {} }); // unsubscribe(handlers) -> boolean
bc.run(ctx, fn, thisArg, ...args); // sync only; returns fn's value
{ using scope = bc.withScope(ctx); ctx.result = work(); } // start now, end at block exit
- It is a synchronous-only TracingChannel with just
startandend. It has noasyncStart,asyncEnd, orerror. run()does not setctx.resultand does not setctx.erroron a throw.endis still published and the error propagates. If subscribers need these values, set them onctxyourself.withScope()without an argument publishes{}.hasSubscribersis true ifstartorendhas a subscriber or a bound store.BoundedChannelis exported.BoundedChannelScopeis not exported (you only get instances), and its only method is[Symbol.dispose].
channel.withStoreScope(data) (v26.1.0, Stability 1; not on v24)
channel.withStoreScope(data) is the using form of channel.runStores(data, fn). It
enters every AsyncLocalStorage bound with bindStore(store, transform) (applying
the transform) and publishes data (untransformed) to subscribers. It returns a
RunStoresScope, whose only method is [Symbol.dispose], which is idempotent. The class is not
exported. Nesting restores the stores in LIFO order.
Async trap: a scope opened in an async function before its first await stays
entered in the caller after the function returns its promise. The same applies to
AsyncLocalStorage.withScope. Use runStores() / als.run() across awaits.
Built-in channels added since v24
| Channel(s) | Versions | Payload |
|---|---|---|
locks.request.start, locks.request.grant, locks.request.miss, locks.request.end |
v25.9.0, v24.15.0 | { name, mode }. end adds steal, ifAvailable, error |
tracing:node.test:start, tracing:node.test:end, tracing:node.test:error (TracingChannel 'node.test') |
v26.1.0, v24.16.0 | { name, nesting, file, type: 'test'|'suite' }. error adds error |
sqlite.db.query |
v26.8.0, v24.22.0 | { sql, database, duration } (duration in ns, C-layer only) |
crypto.fips.indicator |
v26.9.0, v24.22.0 | { operation, reason, blocked, count, dropped }. Needs --enable-fips-indicator-events and OpenSSL ≥ 3.4 (not verified here) |
Observed details:
- Web Locks:
missfires forifAvailable: truewhen the lock is held, and the callback getsnull. Each request publishes its ownend. - Test runner: bind a store with
tracingChannel('node.test').start.bindStore(als, fn)and the store is visible inside the test body and its subtests. The runner's root also publishesstart/endwithname: '<root>'after the tests have run. This is undocumented. NoasyncStart/asyncEndwere observed. A failing subtest publisheserrorfor itself only, not for its parent. - SQLite:
sqlis the expanded SQL. JS numbers bind as REAL, sorun(42)appears as42.0. There is no start event and no context propagation; for spans, wrap calls in your own TracingChannel. Don't close the db or statement inside a subscriber. - FIPS indicator: delivered asynchronously on the main thread only, at most 256 queued messages, and it does not keep the event loop alive.
Older built-in channels (console, http, http2, net, udp, module, child_process, worker_threads, process.execve) are listed in the docs and are all Stability 1.