diagnostics_channel.hasSubscribers(name)#

• name<string> |<symbol> The channel name
• Returns:<boolean> If there are active subscribers

Check if there are active subscribers to the named channel. This is helpful ifthe message you want to send might be expensive to prepare.

This API is optional but helpful when trying to publish messages from veryperformance-sensitive code.

import diagnostics_channelfrom'node:diagnostics_channel';if (diagnostics_channel.hasSubscribers('my-channel')) {// There are subscribers, prepare and publish message}const diagnostics_channel =require('node:diagnostics_channel');if (diagnostics_channel.hasSubscribers('my-channel')) {// There are subscribers, prepare and publish message}copy

diagnostics_channel.channel(name)#

• name<string> |<symbol> The channel name
• Returns:<Channel> The named channel object

This is the primary entry-point for anyone wanting to publish to a namedchannel. It produces a channel object which is optimized to reduce overhead atpublish time as much as possible.

import diagnostics_channelfrom'node:diagnostics_channel';const channel = diagnostics_channel.channel('my-channel');const diagnostics_channel =require('node:diagnostics_channel');const channel = diagnostics_channel.channel('my-channel');copy

diagnostics_channel.subscribe(name, onMessage)#

• name<string> |<symbol> The channel name
• onMessage<Function> The handler to receive channel messages
  • message<any> The message data
  • name<string> |<symbol> The name of the channel

Register a message handler to subscribe to this channel. This message handlerwill be run synchronously whenever a message is published to the channel. Anyerrors thrown in the message handler will trigger an'uncaughtException'.

import diagnostics_channelfrom'node:diagnostics_channel';diagnostics_channel.subscribe('my-channel',(message, name) => {// Received data});const diagnostics_channel =require('node:diagnostics_channel');diagnostics_channel.subscribe('my-channel',(message, name) => {// Received data});copy

diagnostics_channel.unsubscribe(name, onMessage)#

• name<string> |<symbol> The channel name
• onMessage<Function> The previous subscribed handler to remove
• Returns:<boolean>true if the handler was found,false otherwise.

Remove a message handler previously registered to this channel withdiagnostics_channel.subscribe(name, onMessage).

import diagnostics_channelfrom'node:diagnostics_channel';functiononMessage(message, name) {// Received data}diagnostics_channel.subscribe('my-channel', onMessage);diagnostics_channel.unsubscribe('my-channel', onMessage);const diagnostics_channel =require('node:diagnostics_channel');functiononMessage(message, name) {// Received data}diagnostics_channel.subscribe('my-channel', onMessage);diagnostics_channel.unsubscribe('my-channel', onMessage);copy

diagnostics_channel.tracingChannel(nameOrChannels)#

• nameOrChannels<string> |<TracingChannel> Channel name orobject containing all theTracingChannel Channels
• Returns:<TracingChannel> Collection of channels to trace with

Creates aTracingChannel wrapper for the givenTracingChannel Channels. If a name is given, the corresponding tracingchannels will be created in the form oftracing:${name}:${eventType} whereeventType corresponds to the types ofTracingChannel Channels.

import diagnostics_channelfrom'node:diagnostics_channel';const channelsByName = diagnostics_channel.tracingChannel('my-channel');// or...const channelsByCollection = diagnostics_channel.tracingChannel({start: diagnostics_channel.channel('tracing:my-channel:start'),end: diagnostics_channel.channel('tracing:my-channel:end'),asyncStart: diagnostics_channel.channel('tracing:my-channel:asyncStart'),asyncEnd: diagnostics_channel.channel('tracing:my-channel:asyncEnd'),error: diagnostics_channel.channel('tracing:my-channel:error'),});const diagnostics_channel =require('node:diagnostics_channel');const channelsByName = diagnostics_channel.tracingChannel('my-channel');// or...const channelsByCollection = diagnostics_channel.tracingChannel({start: diagnostics_channel.channel('tracing:my-channel:start'),end: diagnostics_channel.channel('tracing:my-channel:end'),asyncStart: diagnostics_channel.channel('tracing:my-channel:asyncStart'),asyncEnd: diagnostics_channel.channel('tracing:my-channel:asyncEnd'),error: diagnostics_channel.channel('tracing:my-channel:error'),});copy

channel.hasSubscribers#

• Returns:<boolean> If there are active subscribers

Check if there are active subscribers to this channel. This is helpful ifthe message you want to send might be expensive to prepare.

This API is optional but helpful when trying to publish messages from veryperformance-sensitive code.

import diagnostics_channelfrom'node:diagnostics_channel';const channel = diagnostics_channel.channel('my-channel');if (channel.hasSubscribers) {// There are subscribers, prepare and publish message}const diagnostics_channel =require('node:diagnostics_channel');const channel = diagnostics_channel.channel('my-channel');if (channel.hasSubscribers) {// There are subscribers, prepare and publish message}copy

channel.publish(message)#

• message<any> The message to send to the channel subscribers

Publish a message to any subscribers to the channel. This will triggermessage handlers synchronously so they will execute within the same context.

import diagnostics_channelfrom'node:diagnostics_channel';const channel = diagnostics_channel.channel('my-channel');channel.publish({some:'message',});const diagnostics_channel =require('node:diagnostics_channel');const channel = diagnostics_channel.channel('my-channel');channel.publish({some:'message',});copy

channel.subscribe(onMessage)#

• onMessage<Function> The handler to receive channel messages
  • message<any> The message data
  • name<string> |<symbol> The name of the channel

Register a message handler to subscribe to this channel. This message handlerwill be run synchronously whenever a message is published to the channel. Anyerrors thrown in the message handler will trigger an'uncaughtException'.

import diagnostics_channelfrom'node:diagnostics_channel';const channel = diagnostics_channel.channel('my-channel');channel.subscribe((message, name) => {// Received data});const diagnostics_channel =require('node:diagnostics_channel');const channel = diagnostics_channel.channel('my-channel');channel.subscribe((message, name) => {// Received data});copy

channel.unsubscribe(onMessage)#

• onMessage<Function> The previous subscribed handler to remove
• Returns:<boolean>true if the handler was found,false otherwise.

Remove a message handler previously registered to this channel withchannel.subscribe(onMessage).

import diagnostics_channelfrom'node:diagnostics_channel';const channel = diagnostics_channel.channel('my-channel');functiononMessage(message, name) {// Received data}channel.subscribe(onMessage);channel.unsubscribe(onMessage);const diagnostics_channel =require('node:diagnostics_channel');const channel = diagnostics_channel.channel('my-channel');functiononMessage(message, name) {// Received data}channel.subscribe(onMessage);channel.unsubscribe(onMessage);copy

channel.bindStore(store[, transform])#

• store<AsyncLocalStorage> The store to which to bind the context data
• transform<Function> Transform context data before setting the store context

Whenchannel.runStores(context, ...) is called, the given context datawill be applied to any store bound to the channel. If the store has already beenbound the previoustransform function will be replaced with the new one.Thetransform function may be omitted to set the given context data as thecontext directly.

import diagnostics_channelfrom'node:diagnostics_channel';import {AsyncLocalStorage }from'node:async_hooks';const store =newAsyncLocalStorage();const channel = diagnostics_channel.channel('my-channel');channel.bindStore(store,(data) => {return { data };});const diagnostics_channel =require('node:diagnostics_channel');const {AsyncLocalStorage } =require('node:async_hooks');const store =newAsyncLocalStorage();const channel = diagnostics_channel.channel('my-channel');channel.bindStore(store,(data) => {return { data };});copy

channel.unbindStore(store)#

• store<AsyncLocalStorage> The store to unbind from the channel.
• Returns:<boolean>true if the store was found,false otherwise.

Remove a message handler previously registered to this channel withchannel.bindStore(store).

import diagnostics_channelfrom'node:diagnostics_channel';import {AsyncLocalStorage }from'node:async_hooks';const store =newAsyncLocalStorage();const channel = diagnostics_channel.channel('my-channel');channel.bindStore(store);channel.unbindStore(store);const diagnostics_channel =require('node:diagnostics_channel');const {AsyncLocalStorage } =require('node:async_hooks');const store =newAsyncLocalStorage();const channel = diagnostics_channel.channel('my-channel');channel.bindStore(store);channel.unbindStore(store);copy

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

• context<any> Message to send to subscribers and bind to stores
• fn<Function> Handler to run within the entered storage context
• thisArg<any> The receiver to be used for the function call.
• ...args<any> Optional arguments to pass to the function.

Applies the given data to any AsyncLocalStorage instances bound to the channelfor the duration of the given function, then publishes to the channel withinthe scope of that data is applied to the stores.

If a transform function was given tochannel.bindStore(store) it will beapplied to transform the message data before it becomes the context value forthe store. The prior storage context is accessible from within the transformfunction in cases where context linking is required.

The context applied to the store should be accessible in any async code whichcontinues from execution which began during the given function, howeverthere are some situations in whichcontext loss may occur.

import diagnostics_channelfrom'node:diagnostics_channel';import {AsyncLocalStorage }from'node:async_hooks';const store =newAsyncLocalStorage();const channel = diagnostics_channel.channel('my-channel');channel.bindStore(store,(message) => {const parent = store.getStore();returnnewSpan(message, parent);});channel.runStores({some:'message' },() => {  store.getStore();// Span({ some: 'message' })});const diagnostics_channel =require('node:diagnostics_channel');const {AsyncLocalStorage } =require('node:async_hooks');const store =newAsyncLocalStorage();const channel = diagnostics_channel.channel('my-channel');channel.bindStore(store,(message) => {const parent = store.getStore();returnnewSpan(message, parent);});channel.runStores({some:'message' },() => {  store.getStore();// Span({ some: 'message' })});copy

tracingChannel.subscribe(subscribers)#

• subscribers<Object> Set ofTracingChannel Channels subscribers
  • start<Function> Thestart event subscriber
  • end<Function> Theend event subscriber
  • asyncStart<Function> TheasyncStart event subscriber
  • asyncEnd<Function> TheasyncEnd event subscriber
  • error<Function> Theerror event subscriber

Helper to subscribe a collection of functions to the corresponding channels.This is the same as callingchannel.subscribe(onMessage) on each channelindividually.

import diagnostics_channelfrom'node:diagnostics_channel';const channels = diagnostics_channel.tracingChannel('my-channel');channels.subscribe({start(message) {// Handle start message  },end(message) {// Handle end message  },asyncStart(message) {// Handle asyncStart message  },asyncEnd(message) {// Handle asyncEnd message  },error(message) {// Handle error message  },});const diagnostics_channel =require('node:diagnostics_channel');const channels = diagnostics_channel.tracingChannel('my-channel');channels.subscribe({start(message) {// Handle start message  },end(message) {// Handle end message  },asyncStart(message) {// Handle asyncStart message  },asyncEnd(message) {// Handle asyncEnd message  },error(message) {// Handle error message  },});copy

tracingChannel.unsubscribe(subscribers)#

• subscribers<Object> Set ofTracingChannel Channels subscribers
  • start<Function> Thestart event subscriber
  • end<Function> Theend event subscriber
  • asyncStart<Function> TheasyncStart event subscriber
  • asyncEnd<Function> TheasyncEnd event subscriber
  • error<Function> Theerror event subscriber
• Returns:<boolean>true if all handlers were successfully unsubscribed,andfalse otherwise.

Helper to unsubscribe a collection of functions from the corresponding channels.This is the same as callingchannel.unsubscribe(onMessage) on each channelindividually.

import diagnostics_channelfrom'node:diagnostics_channel';const channels = diagnostics_channel.tracingChannel('my-channel');channels.unsubscribe({start(message) {// Handle start message  },end(message) {// Handle end message  },asyncStart(message) {// Handle asyncStart message  },asyncEnd(message) {// Handle asyncEnd message  },error(message) {// Handle error message  },});const diagnostics_channel =require('node:diagnostics_channel');const channels = diagnostics_channel.tracingChannel('my-channel');channels.unsubscribe({start(message) {// Handle start message  },end(message) {// Handle end message  },asyncStart(message) {// Handle asyncStart message  },asyncEnd(message) {// Handle asyncEnd message  },error(message) {// Handle error message  },});copy

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

• fn<Function> Function to wrap a trace around
• context<Object> Shared object to correlate events through
• thisArg<any> The receiver to be used for the function call
• ...args<any> Optional arguments to pass to the function
• Returns:<any> The return value of the given function

Trace a synchronous function call. This will always produce astart eventandend event around the execution and may produce anerror eventif the given function throws an error. This will run the given function usingchannel.runStores(context, ...) on thestart channel which ensures allevents should have any bound stores set to match this trace context.

To ensure only correct trace graphs are formed, events will only be publishedif subscribers are present prior to starting the trace. Subscriptions which areadded after the trace begins will not receive future events from that trace,only future traces will be seen.

import diagnostics_channelfrom'node:diagnostics_channel';const channels = diagnostics_channel.tracingChannel('my-channel');channels.traceSync(() => {// Do something}, {some:'thing',});const diagnostics_channel =require('node:diagnostics_channel');const channels = diagnostics_channel.tracingChannel('my-channel');channels.traceSync(() => {// Do something}, {some:'thing',});copy

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

• fn<Function> Promise-returning function to wrap a trace around
• context<Object> Shared object to correlate trace events through
• thisArg<any> The receiver to be used for the function call
• ...args<any> Optional arguments to pass to the function
• Returns:<Promise> Chained from promise returned by the given function

Trace a promise-returning function call. This will always produce astart event andend event around the synchronous portion of thefunction execution, and will produce anasyncStart event andasyncEnd event when a promise continuation is reached. It may alsoproduce anerror event if the given function throws an error or thereturned promise rejects. This will run the given function usingchannel.runStores(context, ...) on thestart channel which ensures allevents should have any bound stores set to match this trace context.

To ensure only correct trace graphs are formed, events will only be publishedif subscribers are present prior to starting the trace. Subscriptions which areadded after the trace begins will not receive future events from that trace,only future traces will be seen.

import diagnostics_channelfrom'node:diagnostics_channel';const channels = diagnostics_channel.tracingChannel('my-channel');channels.tracePromise(async () => {// Do something}, {some:'thing',});const diagnostics_channel =require('node:diagnostics_channel');const channels = diagnostics_channel.tracingChannel('my-channel');channels.tracePromise(async () => {// Do something}, {some:'thing',});copy

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

• fn<Function> callback using function to wrap a trace around
• position<number> Zero-indexed argument position of expected callback(defaults to last argument ifundefined is passed)
• context<Object> Shared object to correlate trace events through (defaultsto{} ifundefined is passed)
• thisArg<any> The receiver to be used for the function call
• ...args<any> arguments to pass to the function (must include the callback)
• Returns:<any> The return value of the given function

Trace a callback-receiving function call. The callback is expected to followthe error as first arg convention typically used. This will always produce astart event andend event around the synchronous portion of thefunction execution, and will produce aasyncStart event andasyncEnd event around the callback execution. It may also produce anerror event if the given function throws or the first argument passed tothe callback is set. This will run the given function usingchannel.runStores(context, ...) on thestart channel which ensures allevents should have any bound stores set to match this trace context.

To ensure only correct trace graphs are formed, events will only be publishedif subscribers are present prior to starting the trace. Subscriptions which areadded after the trace begins will not receive future events from that trace,only future traces will be seen.

import diagnostics_channelfrom'node:diagnostics_channel';const channels = diagnostics_channel.tracingChannel('my-channel');channels.traceCallback((arg1, callback) => {// Do somethingcallback(null,'result');},1, {some:'thing',}, thisArg, arg1, callback);const diagnostics_channel =require('node:diagnostics_channel');const channels = diagnostics_channel.tracingChannel('my-channel');channels.traceCallback((arg1, callback) => {// Do somethingcallback(null,'result');},1, {some:'thing',}, thisArg, arg1, callback);copy

The callback will also be run withchannel.runStores(context, ...) whichenables context loss recovery in some cases.

import diagnostics_channelfrom'node:diagnostics_channel';import {AsyncLocalStorage }from'node:async_hooks';const channels = diagnostics_channel.tracingChannel('my-channel');const myStore =newAsyncLocalStorage();// The start channel sets the initial store data to something// and stores that store data value on the trace context objectchannels.start.bindStore(myStore,(data) => {const span =newSpan(data);  data.span = span;return span;});// Then asyncStart can restore from that data it stored previouslychannels.asyncStart.bindStore(myStore,(data) => {return data.span;});const diagnostics_channel =require('node:diagnostics_channel');const {AsyncLocalStorage } =require('node:async_hooks');const channels = diagnostics_channel.tracingChannel('my-channel');const myStore =newAsyncLocalStorage();// The start channel sets the initial store data to something// and stores that store data value on the trace context objectchannels.start.bindStore(myStore,(data) => {const span =newSpan(data);  data.span = span;return span;});// Then asyncStart can restore from that data it stored previouslychannels.asyncStart.bindStore(myStore,(data) => {return data.span;});copy

tracingChannel.hasSubscribers#

• Returns:<boolean>true if any of the individual channels has a subscriber,false if not.

This is a helper method available on aTracingChannel instance to check ifany of theTracingChannel Channels have subscribers. Atrue is returned ifany of them have at least one subscriber, afalse is returned otherwise.

import diagnostics_channelfrom'node:diagnostics_channel';const channels = diagnostics_channel.tracingChannel('my-channel');if (channels.hasSubscribers) {// Do something}const diagnostics_channel =require('node:diagnostics_channel');const channels = diagnostics_channel.tracingChannel('my-channel');if (channels.hasSubscribers) {// Do something}copy

start(event)#

• Name:tracing:${name}:start

Thestart event represents the point at which a function is called. At thispoint the event data may contain function arguments or anything else availableat the very start of the execution of the function.

end(event)#

• Name:tracing:${name}:end

Theend event represents the point at which a function call returns a value.In the case of an async function this is when the promise returned not when thefunction itself makes a return statement internally. At this point, if thetraced function was synchronous theresult field will be set to the returnvalue of the function. Alternatively, theerror field may be present torepresent any thrown errors.

It is recommended to listen specifically to theerror event to track errorsas it may be possible for a traceable action to produce multiple errors. Forexample, an async task which fails may be started internally before the syncpart of the task then throws an error.

asyncStart(event)#

• Name:tracing:${name}:asyncStart

TheasyncStart event represents the callback or continuation of a traceablefunction being reached. At this point things like callback arguments may beavailable, or anything else expressing the "result" of the action.

For callbacks-based functions, the first argument of the callback will beassigned to theerror field, if notundefined ornull, and the secondargument will be assigned to theresult field.

For promises, the argument to theresolve path will be assigned toresultor the argument to thereject path will be assign toerror.

It is recommended to listen specifically to theerror event to track errorsas it may be possible for a traceable action to produce multiple errors. Forexample, an async task which fails may be started internally before the syncpart of the task then throws an error.

asyncEnd(event)#

• Name:tracing:${name}:asyncEnd

TheasyncEnd event represents the callback of an asynchronous functionreturning. It's not likely event data will change after theasyncStart event,however it may be useful to see the point where the callback completes.

error(event)#

• Name:tracing:${name}:error

Theerror event represents any error produced by the traceable functioneither synchronously or asynchronously. If an error is thrown in thesynchronous portion of the traced function the error will be assigned to theerror field of the event and theerror event will be triggered. If an erroris received asynchronously through a callback or promise rejection it will alsobe assigned to theerror field of the event and trigger theerror event.

It is possible for a single traceable function call to produce errors multipletimes so this should be considered when consuming this event. For example, ifanother async task is triggered internally which fails and then the sync partof the function then throws and error twoerror events will be emitted, onefor the sync error and one for the async error.

Console#

HTTP#

HTTP/2#

Modules#

NET#

UDP#

Process#

Worker Thread#