Instrumentation should explain application behavior without becoming the hidden mechanism that makes the behavior happen. A library may want to publish useful observations only when a monitoring tool is listening. Node's diagnostics_channel supplies named channels for that purpose. This Node 24 reference builds a small application-owned channel, defines its payload, and shows subscription lifecycle and validation. It adds an instrumentation boundary beyond ordinary console logging and EventEmitter usage. The complete examples stay in memory, so their output can verify exactly which observations were received without needing a monitoring service, exporter, or external package.
Define a channel name and payload contract
channel returns the named channel object used to publish and subscribe. Choose an application or library namespace so unrelated components do not accidentally share a vague name such as event. A name alone is not a complete contract. Document when publication occurs, which fields are supplied, their units, and whether values represent a start, completion, or failure. A duration field without a unit is a common source of incorrect dashboards. A completion event should not be emitted before the operation actually reaches its defined completion boundary.
The fixture uses an app.sale.completed channel with a small sale identifier and integer total. It publishes after calculation succeeds. Real instrumentation should avoid sending a full request object, a secret, or an entire body when a few approved fields suffice. If several versions of a library publish under the same name, keep the payload compatible or version the contract deliberately. An observer cannot safely infer a schema from whichever object happened to appear in one development run.
Keep observers optional to business behavior
A sale or query should still perform its required work when nobody subscribes. hasSubscribers can guard the creation of expensive diagnostic data that would otherwise be thrown away. Compute the actual business result regardless of that guard. Only optional observation preparation belongs behind it. If turning monitoring off stops a required audit record, payment notification, or database update, the code is using an instrumentation channel as a workflow dependency.
Diagnostics channels are not durable messaging. They do not retain events for a later subscriber, persist them across a crash, or acknowledge that an external system recorded them. Use a suitable event queue or transactional outbox when delivery is part of correctness. A metric observer can aggregate diagnostic events and send them elsewhere, but that export needs its own buffering, backpressure, and failure policy. The fixture's array is a tiny observation sink for testing, not an unbounded production event store. Optional instrumentation must preserve application semantics whether or not that sink exists.
Respect synchronous subscriber execution
Channel publication invokes subscribers synchronously at the publication point. Slow subscriber work can therefore add latency to the instrumented operation. Do not perform heavy synchronous computation or blocking filesystem operations inside a subscriber merely because it is called monitoring. If export is asynchronous, enqueue a bounded record and let another component handle it under an explicit capacity policy. Publication does not await a subscriber's returned promise as a business completion signal.
Subscribers should avoid throwing. The documented error behavior is not a reliable application recovery interface, and a diagnostic mistake must not become a process-level failure. Validate payload assumptions and handle expected observation errors within the subscriber. Do not mutate the shared message because another subscriber may see the same object. The main fixture freezes its simple payload, while the practice validates a duration and records an invalid observation locally rather than throwing through publish. Freezing is shallow, so more complex payloads still need deliberate ownership and mutation rules.
Manage registration, cleanup, and builtin boundaries
subscribe registers a callback, and unsubscribe removes that callback. Retain the same function reference for cleanup. Repeatedly installing anonymous subscribers during hot reload or request handling can leak observations and duplicate metrics. A monitoring component should own registration for its lifetime and remove it when disabled or shut down. Test that a removed subscriber no longer receives events. Keep subscriptions process-local; a worker or another process needs its own setup and any explicit export path.
Node also documents built-in channels for some operations, but their payloads and stability should be checked for the exact runtime you target. Do not assume every internal channel name or undocumented event is a public stable interface. Application-owned channels make your contract explicit and are a useful starting point before integrating runtime-specific observations. A channel does not replace all tracing: correlated asynchronous lifetimes may require AsyncLocalStorage or the documented tracing facilities. Choose instrumentation that answers a concrete operational question rather than collecting every available value without a retention or privacy plan.
Node.js documentation and version notes
Node.js Diagnostics Channel Instrumentation Examples
Each example shows the code, the output it produces and what each part does.
Observing sales events through a diagnostics channel
Run this complete .mjs fixture on Node 24. A subscriber copies each approved payload into a small observations array. Two sales produce totals and completion observations. After unsubscribe, a third sale still calculates its total but creates no observation for that listener. The final count remains two, proving the monitoring dependency is optional. The payload is frozen at publication to discourage accidental mutation, and the observer records only the declared identifier and total. This is a deterministic instrumentation test, not a claim of durable delivery, distributed tracing, or production metric export.
import { channel } from 'node:diagnostics_channel';
const completed = channel('app.sale.completed');
const observed = [];
const listener = message => { observed.push({ id: message.id, total: message.total }); };
function sale(id, prices) {
const total = prices.reduce((sum, price) => sum + price, 0);
if (completed.hasSubscribers) completed.publish(Object.freeze({ id, total }));
return total;
}
completed.subscribe(listener);
console.log(sale('s1', [8, 8]));
console.log(sale('s2', [5, 7]));
console.log(JSON.stringify(observed));
completed.unsubscribe(listener);
console.log(sale('s3', [2, 3]));
console.log('observations', observed.length);16
12
[{"id":"s1","total":16},{"id":"s2","total":12}]
5
observations 2Node.js Diagnostics Channel Instrumentation in Real Projects
Build a validating duration observer
Build a duration observer that accepts only finite nonnegative millisecond values. Publish two valid durations and one invalid negative duration. Keep a separate count of rejected observations and prevent the subscriber from throwing. The solution then unsubscribes before publishing another valid duration, proving cleanup stops future contribution. A production metric sink would need bounded export behavior and a deliberate policy for reporting malformed payloads. This small practice isolates schema validation and registration lifecycle. Its final totals come only from the two accepted observations received while the callback was registered, not from every value published to the channel.
import { channel } from 'node:diagnostics_channel';
const timing = channel('app.operation.duration');
let totalMs = 0;
let rejected = 0;
const listener = message => {
if (typeof message?.durationMs !== 'number' || !Number.isFinite(message.durationMs) || message.durationMs < 0) {
rejected++; return;
}
totalMs += message.durationMs;
};
timing.subscribe(listener);
try {
timing.publish({ durationMs: 10 });
timing.publish({ durationMs: -1 });
timing.publish({ durationMs: 5 });
} finally { timing.unsubscribe(listener); }
timing.publish({ durationMs: 100 });
console.log('totalMs', totalMs);
console.log('rejected', rejected);totalMs 15
rejected 1Node.js Diagnostics Channel Instrumentation FAQ
Is a diagnostics channel a durable event bus?
No. Publications reach current in-process subscribers and are not retained as a reliable queue for future delivery. Use a durable mechanism when an event is necessary for business correctness. A diagnostic subscriber may export records, but that exporter has its own capacity and failure policy. Do not treat a completed publish call as proof that an external monitoring service persisted the event.
Should required work be inside hasSubscribers?
No. The business operation must behave correctly without an observer. Guard only optional diagnostic preparation that would otherwise be unnecessary. The main fixture still calculates its third sale after unsubscribe. Required audit or transaction work belongs in an explicit workflow with suitable guarantees. Monitoring should explain that workflow, not secretly enable it when someone happens to subscribe.
Can a subscriber perform slow work safely?
It runs synchronously at publication, so slow work adds latency and can block the event loop. Prefer a small bounded observation step and an explicitly managed asynchronous exporter. Do not assume returning a promise makes publication await or supervise its completion. Handle observer errors locally and keep the exporter from accumulating an unlimited queue during an outage.
Why retain the callback reference for unsubscribe?
Removal targets the registered function. Constructing a new equivalent-looking function does not supply the same reference. A component that repeatedly registers without cleanup can duplicate metrics and retain data. Store the listener, register once for its intended lifetime, and remove it in the owning component's shutdown path. Test post-cleanup publication as the practice does.
Node.js Diagnostics Channel Instrumentation Exercises
Answer each one and check it instantly. If you get stuck, open the hint before the answer.
Why is the worked totalMs 15 rather than 115?
Node.js Diagnostics Channel Instrumentation Quiz
2 questions to check what you learned.
What happens to the main sale calculation after unsubscribe?
- It still returns the required total without observation
- It must fail because no monitor authorizes it
- It waits until another subscriber appears
Why avoid mutating a published message in a subscriber?
- Other subscribers may observe the same payload object
- publish clones every message deeply before every callback
- Mutation automatically makes an event durable