Instrumentation hooks
A library emits structured lifecycle or request events for observability tools without depending on a particular monitoring implementation.
Node.js · Module
node:diagnostics_channel
node:diagnostics_channel provides named channels for sending arbitrary diagnostic data. Producers can publish efficiently when subscribers exist, while consumers attach and remove message handlers.
- Since
- 16.17.0, 15.1.0
How it works
The module lets code expose diagnostic messages through named channels. Obtain a reusable channel with channel(name), register handlers with subscribe, check hasSubscribers before constructing or publishing diagnostic data, and remove handlers with unsubscribe; publication invokes subscribed handlers synchronously.
Syntax
import diagnostics_channel from 'node:diagnostics_channel';
const channel = diagnostics_channel.channel(name);
diagnostics_channel.subscribe(name, onMessage);
channel.publish(message);
diagnostics_channel.unsubscribe(name, onMessage);Parameters
| Name | Type | Description |
|---|---|---|
name | string | symbol | The channel identifier; a string or symbol. |
message | any | The arbitrary diagnostic value delivered to subscribers. |
onMessage | function | The callback invoked for published messages. |
Returns
channel(name) returns the named Channel object; hasSubscribers(name) returns a boolean indicating whether active subscribers exist; publish(message) returns undefined.
Key points
- Use named channels to expose arbitrary diagnostic messages without coupling producers to specific consumers.
- Libraries should generally define their diagnostic channels at module scope.
- diagnostics_channel.channel(name) is the normal way to obtain a Channel instance.
- Reuse the returned channel object to minimize overhead while publishing.
- Use subscribe to attach a callback that receives published messages.
- hasSubscribers lets producers skip unnecessary diagnostic work when nobody is listening.
Common mistakes
- Do not instantiate Channel directly; obtain channel objects through diagnostics_channel.channel(name).
- Prefer creating module-level channels rather than repeatedly acquiring them during runtime.
- Subscriber callbacks run synchronously, so slow handlers can delay the code publishing the message.
Example: Publish diagnostics through a named channel
import diagnostics_channel from 'node:diagnostics_channel';
const channel = diagnostics_channel.channel('orders');
function onOrder(message, name) {
console.log(name, message.id);
}
diagnostics_channel.subscribe('orders', onOrder);
if (channel.hasSubscribers) {
channel.publish({ id: 42, status: 'created' });
}
diagnostics_channel.unsubscribe('orders', onOrder);Creates a reusable named channel, subscribes a handler, publishes only when a subscriber exists, and then removes the handler.
When to use it
Low-overhead optional diagnostics
A producer checks for listeners before creating expensive diagnostic payloads.
Runtime telemetry
A monitoring component subscribes to selected named channels and processes messages centrally.
Interview questions
QWhat problem does node:diagnostics_channel solve?
A named channel is a diagnostics message route identified by a string or symbol. Code publishes arbitrary message data to it, while subscribers receive that data when publication occurs.
Follow-up: How can publishing overhead be reduced? Check hasSubscribers first and avoid building diagnostic payloads when no subscriber is active.
QHow do you publish a message?
Use diagnostics_channel.channel(name) to get the reusable Channel object, then call channel.publish(message). A channel object tracks subscribers and publishes messages when subscribers are present.
Follow-up: Why should new Channel(name) be avoided? The documentation explicitly says direct construction is unsupported.
QHow are handlers registered and removed?
Subscribe with diagnostics_channel.subscribe(name, onMessage) and remove the handler with diagnostics_channel.unsubscribe(name, onMessage). The same handler reference must be supplied when unsubscribing.
Follow-up: What execution behavior should a subscriber expect? Its callback runs synchronously during publication.
Related
Channelchannel.publish(message)channel.subscribe(onMessage)channel.unsubscribe(onMessage)diagnostics_channel.subscribe(name, onMessage)diagnostics_channel.unsubscribe(name, onMessage)diagnostics_channel.hasSubscribers(name)