Node.js Reference ยท node:sqlite and Runtime Services
The diagnostics_channel module
Reference for node:diagnostics_channel: named channels that libraries publish events to and tools subscribe to, with near-zero cost when nobody listens.
node:diagnostics_channel is a small publish/subscribe system for diagnostic messages. A library creates a named channel and publishes objects to it, for example "an HTTP request started" or "a query ran". Monitoring tools subscribe to the channel by name and receive those objects, with no changes to the library and no hard dependency between the two.
The design goal is cost: publishing to a channel that has no subscribers is almost free, and you can check hasSubscribers first to skip even building the message. Node.js itself publishes events for http, net, undici/fetch, dns and more, and APM tools build on them.
import dc from 'node:diagnostics_channel'; dc.subscribe('app:order', (message, name) => console.log(name, message)); dc.channel('app:order').publish({ id: 1 });
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.
Syntax
import dc from 'node:diagnostics_channel'; dc.channel(name): Channel dc.hasSubscribers(name): boolean dc.subscribe(name, onMessage): void dc.unsubscribe(name, onMessage): boolean dc.tracingChannel(nameOrChannels): TracingChannel
| Name | Description |
|---|---|
name |
A string or symbol identifying the channel. Use a prefix such as mylib:event. |
onMessage(message, name) |
Called synchronously on every publish, with the published value and the channel name. |
Channel methods and properties:
| Member | Description |
|---|---|
channel.hasSubscribers |
true if anything is subscribed. |
channel.publish(message) |
Calls every subscriber in order. |
channel.subscribe(fn) / channel.unsubscribe(fn) |
Add or remove a subscriber; unsubscribe returns whether it was found. |
channel.bindStore(store, transform) |
Ties an AsyncLocalStorage to the channel. |
channel.unbindStore(store) |
Removes that binding. |
channel.runStores(data, fn, thisArg, ...args) |
Runs fn with each bound store set to transform(data), and publishes data. |
Returns: channel() returns the same Channel object for the same name.
Usage notes
- Subscribers run synchronously inside
publish(). A slow subscriber slows the publisher, and an exception in a subscriber is reported as an uncaught exception on the next tick, not thrown to the publisher. - Keep a reference to the channel object you publish to. Channels are held weakly: a channel with no subscribers and no references may be garbage collected, and the module-level
dc.subscribe(name, ...)keeps it alive only while subscribed. - Always guard expensive messages with
channel.hasSubscribers. - Naming. Pick unique, namespaced names. Built-in names include
http.client.request.start,http.server.request.start,net.client.socket,undici:request:create,module.require.startand many others; the available set depends on the Node.js version. - Messages are plain objects shared with all subscribers. Do not mutate them, and do not put secrets in them without thinking about who may subscribe.
- Worker threads have their own channels; a subscription in the main thread does not see workers' messages.
- Not an event emitter replacement. Use it for observability hooks, not for application logic.