Skip to content
Tutorials Center
My learning

Topics

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.

NODE
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

Node.js Publish and subscribe

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.

Node.js Same name, same channel; stores follow the call

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

NODE
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.start and 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.