Skip to main content

​
Diagnostics Channel

The node:diagnostics_channel module provides an API to create named channels to report arbitrary message data for diagnostics purposes.

​
Stability

Stable (Stability: 2)

​
Import

import diagnostics_channel from 'node:diagnostics_channel';

const diagnostics_channel = require('node:diagnostics_channel');

​
Overview

The diagnostics channel module enables pub/sub pattern for diagnostics data. Module writers can create channels to report messages, and consumers can subscribe to receive them. 
import diagnostics_channel from 'node:diagnostics_channel';

// Get a reusable channel object
const channel = diagnostics_channel.channel('my-channel');

function onMessage(message, name) {
  // Received data
}

// Subscribe to the channel
diagnostics_channel.subscribe('my-channel', onMessage);

// Check if the channel has an active subscriber
if (channel.hasSubscribers) {
  // Publish data to the channel
  channel.publish({
    some: 'data',
  });
}

// Unsubscribe from the channel
diagnostics_channel.unsubscribe('my-channel', onMessage);

​
Public API

​
diagnostics_channel.hasSubscribers(name)

Check if there are active subscribers to the named channel. Parameters:
  • name - The channel name
Returns: - If there are active subscribers This is helpful when preparing expensive messages.

​
diagnostics_channel.channel(name)

Get or create a named channel for publishing. Parameters:
  • name - The channel name
Returns: - The named channel object This is the primary entry point for publishing to a channel.

​
diagnostics_channel.subscribe(name, onMessage)

Register a message handler to subscribe to a channel. Parameters:
  • name - The channel name
  • onMessage - Handler to receive messages
    • message - The message data
    • name - The channel name
The handler runs synchronously when messages are published. Errors trigger uncaughtException.

​
diagnostics_channel.unsubscribe(name, onMessage)

Remove a previously registered message handler. Parameters:
  • name - The channel name
  • onMessage - The handler to remove
Returns: - true if handler was found, false otherwise

​
diagnostics_channel.tracingChannel(nameOrChannels)

Create a TracingChannel wrapper for tracing. Parameters:
  • nameOrChannels - Channel name or object
Returns: - Collection of channels to trace with

​
Class: Channel

Represents an individual named channel for publishing messages.

​
channel.hasSubscribers

Returns: - If there are active subscribers Check if there are active subscribers before preparing expensive messages.

​
channel.publish(message)

Publish a message to all subscribers. Parameters:
  • message - The message to send
Messages are delivered synchronously to all subscribers.

​
channel.subscribe(onMessage)

Register a message handler for this channel. Parameters:
  • onMessage - Handler to receive messages
    • message - The message data
    • name - The channel name

​
channel.unsubscribe(onMessage)

Remove a message handler from this channel. Parameters:
  • onMessage - The handler to remove
Returns: - true if handler was found, false otherwise

​
channel.bindStore(store[, transform])

Bind an AsyncLocalStorage to the channel. Parameters:
  • store - Store to bind context data
  • transform - Optional transform for context data
When runStores() is called, context data is applied to bound stores.

​
channel.unbindStore(store)

Unbind an AsyncLocalStorage from the channel. Parameters:
  • store - The store to unbind
Returns: - true if store was found, false otherwise

​
channel.runStores(context, fn[, thisArg[, ...args]])

Apply context to bound stores for the duration of a function. Parameters:
  • context - Message to bind to stores
  • fn - Handler to run within context
  • thisArg - The receiver for the function
  • ...args - Optional arguments to pass

​
Class: TracingChannel

Collection of channels for tracing a single action.

​
tracingChannel.subscribe(subscribers)

Subscribe handlers to all tracing events. Parameters:
  • subscribers - Set of event subscribers
    • start - Start event subscriber
    • end - End event subscriber
    • asyncStart - Async start subscriber
    • asyncEnd - Async end subscriber
    • error - Error event subscriber

​
tracingChannel.unsubscribe(subscribers)

Unsubscribe handlers from tracing events. Parameters:
  • subscribers - Set of event subscribers
Returns: - true if all handlers unsubscribed successfully

​
tracingChannel.traceSync(fn[, context[, thisArg[, ...args]]])

Trace a synchronous function call. Parameters:
  • fn - Function to wrap
  • context - Shared context object
  • thisArg - The receiver
  • ...args - Optional arguments
Returns: - The return value of the function Produces start and end events, and possibly error events.

​
tracingChannel.tracePromise(fn[, context[, thisArg[, ...args]]])

Trace a promise-returning function. Parameters:
  • fn - Promise-returning function
  • context - Shared context object
  • thisArg - The receiver
  • ...args - Optional arguments
Returns: - Chained from the function’s promise Produces start, end, asyncStart, and asyncEnd events.

​
tracingChannel.traceCallback(fn[, position[, context[, thisArg[, ...args]]]])

Trace a callback-receiving function. Parameters:
  • fn - Callback-using function
  • position - Callback argument position (defaults to last)
  • context - Shared context object
  • thisArg - The receiver
  • ...args - Arguments including callback
Returns: - The return value of the function

​
tracingChannel.hasSubscribers

Returns: - true if any channel has subscribers Check if any of the tracing channels have active subscribers.

​
Built-in Channels

​
Console Events

  • console.log - Emitted when console.log() is called
  • console.info - Emitted when console.info() is called
  • console.debug - Emitted when console.debug() is called
  • console.warn - Emitted when console.warn() is called
  • console.error - Emitted when console.error() is called

​
HTTP Events

  • http.client.request.created - Client creates request object
  • http.client.request.start - Client starts request
  • http.client.request.error - Client request error
  • http.client.response.finish - Client receives response
  • http.server.request.start - Server receives request
  • http.server.response.created - Server creates response
  • http.server.response.finish - Server sends response

​
HTTP/2 Events

  • http2.client.stream.created - Client stream created
  • http2.client.stream.start - Client stream started
  • http2.client.stream.error - Client stream error
  • http2.client.stream.finish - Client stream finished
  • http2.server.stream.created - Server stream created
  • http2.server.stream.start - Server stream started
  • http2.server.stream.error - Server stream error
  • http2.server.stream.finish - Server stream finished

​
Module Events

  • module.require.start - require() called
  • module.require.end - require() completed
  • module.require.error - require() error
  • module.import.asyncStart - import() invoked
  • module.import.asyncEnd - import() completed
  • module.import.error - import() error

​
Network Events

  • net.client.socket - TCP/pipe client socket created
  • net.server.socket - TCP/pipe server socket created
  • tracing:net.server.listen:asyncStart - Server listen started
  • tracing:net.server.listen:asyncEnd - Server listen completed
  • tracing:net.server.listen:error - Server listen error

​
UDP Events

  • udp.socket - UDP socket created

​
Process Events

  • child_process - Child process created
  • tracing:child_process.spawn:start - Spawn invoked
  • tracing:child_process.spawn:end - Spawn completed
  • tracing:child_process.spawn:error - Spawn error
  • execve - process.execve() invoked

​
Worker Events

  • worker_threads - Worker thread created