{ "type": "module", "source": "doc/api/diagnostics_channel.md", "modules": [ { "textRaw": "Diagnostics Channel", "name": "diagnostics_channel", "meta": { "added": [ "v15.1.0", "v14.17.0" ], "changes": [ { "version": "v18.13.0", "pr-url": "https://github.com/nodejs/node/pull/45290", "description": "diagnostics_channel is now Stable." } ] }, "introduced_in": "v15.1.0", "stability": 2, "stabilityText": "Stable", "desc": "

Source Code: lib/diagnostics_channel.js

\n

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

\n

It can be accessed using:

\n
import diagnostics_channel from 'node:diagnostics_channel';\n
\n
const diagnostics_channel = require('node:diagnostics_channel');\n
\n

It is intended that a module writer wanting to report diagnostics messages\nwill create one or many top-level channels to report messages through.\nChannels may also be acquired at runtime but it is not encouraged\ndue to the additional overhead of doing so. Channels may be exported for\nconvenience, but as long as the name is known it can be acquired anywhere.

\n

If you intend for your module to produce diagnostics data for others to\nconsume it is recommended that you include documentation of what named\nchannels are used along with the shape of the message data. Channel names\nshould generally include the module name to avoid collisions with data from\nother modules.

", "modules": [ { "textRaw": "Public API", "name": "public_api", "modules": [ { "textRaw": "Overview", "name": "overview", "desc": "

Following is a simple overview of the public API.

\n
import diagnostics_channel from 'node:diagnostics_channel';\n\n// Get a reusable channel object\nconst channel = diagnostics_channel.channel('my-channel');\n\nfunction onMessage(message, name) {\n  // Received data\n}\n\n// Subscribe to the channel\ndiagnostics_channel.subscribe('my-channel', onMessage);\n\n// Check if the channel has an active subscriber\nif (channel.hasSubscribers) {\n  // Publish data to the channel\n  channel.publish({\n    some: 'data',\n  });\n}\n\n// Unsubscribe from the channel\ndiagnostics_channel.unsubscribe('my-channel', onMessage);\n
\n
const diagnostics_channel = require('node:diagnostics_channel');\n\n// Get a reusable channel object\nconst channel = diagnostics_channel.channel('my-channel');\n\nfunction onMessage(message, name) {\n  // Received data\n}\n\n// Subscribe to the channel\ndiagnostics_channel.subscribe('my-channel', onMessage);\n\n// Check if the channel has an active subscriber\nif (channel.hasSubscribers) {\n  // Publish data to the channel\n  channel.publish({\n    some: 'data',\n  });\n}\n\n// Unsubscribe from the channel\ndiagnostics_channel.unsubscribe('my-channel', onMessage);\n
", "methods": [ { "textRaw": "`diagnostics_channel.hasSubscribers(name)`", "type": "method", "name": "hasSubscribers", "meta": { "added": [ "v15.1.0", "v14.17.0" ], "changes": [] }, "signatures": [ { "return": { "textRaw": "Returns: {boolean} If there are active subscribers", "name": "return", "type": "boolean", "desc": "If there are active subscribers" }, "params": [ { "textRaw": "`name` {string|symbol} The channel name", "name": "name", "type": "string|symbol", "desc": "The channel name" } ] } ], "desc": "

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

\n

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

\n
import diagnostics_channel from 'node:diagnostics_channel';\n\nif (diagnostics_channel.hasSubscribers('my-channel')) {\n  // There are subscribers, prepare and publish message\n}\n
\n
const diagnostics_channel = require('node:diagnostics_channel');\n\nif (diagnostics_channel.hasSubscribers('my-channel')) {\n  // There are subscribers, prepare and publish message\n}\n
" }, { "textRaw": "`diagnostics_channel.channel(name)`", "type": "method", "name": "channel", "meta": { "added": [ "v15.1.0", "v14.17.0" ], "changes": [] }, "signatures": [ { "return": { "textRaw": "Returns: {Channel} The named channel object", "name": "return", "type": "Channel", "desc": "The named channel object" }, "params": [ { "textRaw": "`name` {string|symbol} The channel name", "name": "name", "type": "string|symbol", "desc": "The channel name" } ] } ], "desc": "

This is the primary entry-point for anyone wanting to publish to a named\nchannel. It produces a channel object which is optimized to reduce overhead at\npublish time as much as possible.

\n
import diagnostics_channel from 'node:diagnostics_channel';\n\nconst channel = diagnostics_channel.channel('my-channel');\n
\n
const diagnostics_channel = require('node:diagnostics_channel');\n\nconst channel = diagnostics_channel.channel('my-channel');\n
" }, { "textRaw": "`diagnostics_channel.subscribe(name, onMessage)`", "type": "method", "name": "subscribe", "meta": { "added": [ "v18.7.0" ], "changes": [] }, "signatures": [ { "params": [ { "textRaw": "`name` {string|symbol} The channel name", "name": "name", "type": "string|symbol", "desc": "The channel name" }, { "textRaw": "`onMessage` {Function} The handler to receive channel messages", "name": "onMessage", "type": "Function", "desc": "The handler to receive channel messages", "options": [ { "textRaw": "`message` {any} The message data", "name": "message", "type": "any", "desc": "The message data" }, { "textRaw": "`name` {string|symbol} The name of the channel", "name": "name", "type": "string|symbol", "desc": "The name of the channel" } ] } ] } ], "desc": "

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

\n
import diagnostics_channel from 'node:diagnostics_channel';\n\ndiagnostics_channel.subscribe('my-channel', (message, name) => {\n  // Received data\n});\n
\n
const diagnostics_channel = require('node:diagnostics_channel');\n\ndiagnostics_channel.subscribe('my-channel', (message, name) => {\n  // Received data\n});\n
" }, { "textRaw": "`diagnostics_channel.unsubscribe(name, onMessage)`", "type": "method", "name": "unsubscribe", "meta": { "added": [ "v18.7.0" ], "changes": [] }, "signatures": [ { "return": { "textRaw": "Returns: {boolean} `true` if the handler was found, `false` otherwise.", "name": "return", "type": "boolean", "desc": "`true` if the handler was found, `false` otherwise." }, "params": [ { "textRaw": "`name` {string|symbol} The channel name", "name": "name", "type": "string|symbol", "desc": "The channel name" }, { "textRaw": "`onMessage` {Function} The previous subscribed handler to remove", "name": "onMessage", "type": "Function", "desc": "The previous subscribed handler to remove" } ] } ], "desc": "

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

\n
import diagnostics_channel from 'node:diagnostics_channel';\n\nfunction onMessage(message, name) {\n  // Received data\n}\n\ndiagnostics_channel.subscribe('my-channel', onMessage);\n\ndiagnostics_channel.unsubscribe('my-channel', onMessage);\n
\n
const diagnostics_channel = require('node:diagnostics_channel');\n\nfunction onMessage(message, name) {\n  // Received data\n}\n\ndiagnostics_channel.subscribe('my-channel', onMessage);\n\ndiagnostics_channel.unsubscribe('my-channel', onMessage);\n
" }, { "textRaw": "`diagnostics_channel.tracingChannel(nameOrChannels)`", "type": "method", "name": "tracingChannel", "meta": { "added": [ "v18.19.0" ], "changes": [] }, "stability": 1, "stabilityText": "Experimental", "signatures": [ { "return": { "textRaw": "Returns: {TracingChannel} Collection of channels to trace with", "name": "return", "type": "TracingChannel", "desc": "Collection of channels to trace with" }, "params": [ { "textRaw": "`nameOrChannels` {string|TracingChannel} Channel name or object containing all the [TracingChannel Channels][]", "name": "nameOrChannels", "type": "string|TracingChannel", "desc": "Channel name or object containing all the [TracingChannel Channels][]" } ] } ], "desc": "

Creates a TracingChannel wrapper for the given\nTracingChannel Channels. If a name is given, the corresponding tracing\nchannels will be created in the form of tracing:${name}:${eventType} where\neventType corresponds to the types of TracingChannel Channels.

\n
import diagnostics_channel from 'node:diagnostics_channel';\n\nconst channelsByName = diagnostics_channel.tracingChannel('my-channel');\n\n// or...\n\nconst channelsByCollection = diagnostics_channel.tracingChannel({\n  start: diagnostics_channel.channel('tracing:my-channel:start'),\n  end: diagnostics_channel.channel('tracing:my-channel:end'),\n  asyncStart: diagnostics_channel.channel('tracing:my-channel:asyncStart'),\n  asyncEnd: diagnostics_channel.channel('tracing:my-channel:asyncEnd'),\n  error: diagnostics_channel.channel('tracing:my-channel:error'),\n});\n
\n
const diagnostics_channel = require('node:diagnostics_channel');\n\nconst channelsByName = diagnostics_channel.tracingChannel('my-channel');\n\n// or...\n\nconst channelsByCollection = diagnostics_channel.tracingChannel({\n  start: diagnostics_channel.channel('tracing:my-channel:start'),\n  end: diagnostics_channel.channel('tracing:my-channel:end'),\n  asyncStart: diagnostics_channel.channel('tracing:my-channel:asyncStart'),\n  asyncEnd: diagnostics_channel.channel('tracing:my-channel:asyncEnd'),\n  error: diagnostics_channel.channel('tracing:my-channel:error'),\n});\n
" } ], "type": "module", "displayName": "Overview" }, { "textRaw": "TracingChannel Channels", "name": "tracingchannel_channels", "desc": "

A TracingChannel is a collection of several diagnostics_channels representing\nspecific points in the execution lifecycle of a single traceable action. The\nbehaviour is split into five diagnostics_channels consisting of start,\nend, asyncStart, asyncEnd, and error. A single traceable action will\nshare the same event object between all events, this can be helpful for\nmanaging correlation through a weakmap.

\n

These event objects will be extended with result or error values when\nthe task \"completes\". In the case of a synchronous task the result will be\nthe return value and the error will be anything thrown from the function.\nWith callback-based async functions the result will be the second argument\nof the callback while the error will either be a thrown error visible in the\nend event or the first callback argument in either of the asyncStart or\nasyncEnd events.

\n

Tracing channels should follow a naming pattern of:

\n", "methods": [ { "textRaw": "`start(event)`", "type": "method", "name": "start", "signatures": [ { "params": [ { "textRaw": "Name: `tracing:${name}:start`", "name": "Name", "desc": "`tracing:${name}:start`" } ] } ], "desc": "

The start event represents the point at which a function is called. At this\npoint the event data may contain function arguments or anything else available\nat the very start of the execution of the function.

" }, { "textRaw": "`end(event)`", "type": "method", "name": "end", "signatures": [ { "params": [ { "textRaw": "Name: `tracing:${name}:end`", "name": "Name", "desc": "`tracing:${name}:end`" } ] } ], "desc": "

The end event represents the point at which a function call returns a value.\nIn the case of an async function this is when the promise returned not when the\nfunction itself makes a return statement internally. At this point, if the\ntraced function was synchronous the result field will be set to the return\nvalue of the function. Alternatively, the error field may be present to\nrepresent any thrown errors.

\n

It is recommended to listen specifically to the error event to track errors\nas it may be possible for a traceable action to produce multiple errors. For\nexample, an async task which fails may be started internally before the sync\npart of the task then throws an error.

" }, { "textRaw": "`asyncStart(event)`", "type": "method", "name": "asyncStart", "signatures": [ { "params": [ { "textRaw": "Name: `tracing:${name}:asyncStart`", "name": "Name", "desc": "`tracing:${name}:asyncStart`" } ] } ], "desc": "

The asyncStart event represents the callback or continuation of a traceable\nfunction being reached. At this point things like callback arguments may be\navailable, or anything else expressing the \"result\" of the action.

\n

For callbacks-based functions, the first argument of the callback will be\nassigned to the error field, if not undefined or null, and the second\nargument will be assigned to the result field.

\n

For promises, the argument to the resolve path will be assigned to result\nor the argument to the reject path will be assign to error.

\n

It is recommended to listen specifically to the error event to track errors\nas it may be possible for a traceable action to produce multiple errors. For\nexample, an async task which fails may be started internally before the sync\npart of the task then throws an error.

" }, { "textRaw": "`asyncEnd(event)`", "type": "method", "name": "asyncEnd", "signatures": [ { "params": [ { "textRaw": "Name: `tracing:${name}:asyncEnd`", "name": "Name", "desc": "`tracing:${name}:asyncEnd`" } ] } ], "desc": "

The asyncEnd event represents the callback of an asynchronous function\nreturning. It's not likely event data will change after the asyncStart event,\nhowever it may be useful to see the point where the callback completes.

" }, { "textRaw": "`error(event)`", "type": "method", "name": "error", "signatures": [ { "params": [ { "textRaw": "Name: `tracing:${name}:error`", "name": "Name", "desc": "`tracing:${name}:error`" } ] } ], "desc": "

The error event represents any error produced by the traceable function\neither synchronously or asynchronously. If an error is thrown in the\nsynchronous portion of the traced function the error will be assigned to the\nerror field of the event and the error event will be triggered. If an error\nis received asynchronously through a callback or promise rejection it will also\nbe assigned to the error field of the event and trigger the error event.

\n

It is possible for a single traceable function call to produce errors multiple\ntimes so this should be considered when consuming this event. For example, if\nanother async task is triggered internally which fails and then the sync part\nof the function then throws and error two error events will be emitted, one\nfor the sync error and one for the async error.

" } ], "type": "module", "displayName": "TracingChannel Channels" }, { "textRaw": "Built-in Channels", "name": "built-in_channels", "stability": 1, "stabilityText": "Experimental", "desc": "

While the diagnostics_channel API is now considered stable, the built-in\nchannels currently available are not. Each channel must be declared stable\nindependently.

", "modules": [ { "textRaw": "HTTP", "name": "http", "desc": "

http.client.request.start

\n\n

Emitted when client starts a request.

\n

http.client.response.finish

\n\n

Emitted when client receives a response.

\n

http.server.request.start

\n\n

Emitted when server receives a request.

\n

http.server.response.finish

\n\n

Emitted when server sends a response.

\n

net.client.socket

\n\n

Emitted when a new TCP or pipe client socket is created.

\n

net.server.socket

\n\n

Emitted when a new TCP or pipe connection is received.

\n

udp.socket

\n\n

Emitted when a new UDP socket is created.

", "type": "module", "displayName": "HTTP" } ], "type": "module", "displayName": "Built-in Channels" } ], "classes": [ { "textRaw": "Class: `Channel`", "type": "class", "name": "Channel", "meta": { "added": [ "v15.1.0", "v14.17.0" ], "changes": [] }, "desc": "

The class Channel represents an individual named channel within the data\npipeline. It is used to track subscribers and to publish messages when there\nare subscribers present. It exists as a separate object to avoid channel\nlookups at publish time, enabling very fast publish speeds and allowing\nfor heavy use while incurring very minimal cost. Channels are created with\ndiagnostics_channel.channel(name), constructing a channel directly\nwith new Channel(name) is not supported.

", "properties": [ { "textRaw": "`hasSubscribers` Returns: {boolean} If there are active subscribers", "type": "boolean", "name": "return", "meta": { "added": [ "v15.1.0", "v14.17.0" ], "changes": [] }, "desc": "

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

\n

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

\n
import diagnostics_channel from 'node:diagnostics_channel';\n\nconst channel = diagnostics_channel.channel('my-channel');\n\nif (channel.hasSubscribers) {\n  // There are subscribers, prepare and publish message\n}\n
\n
const diagnostics_channel = require('node:diagnostics_channel');\n\nconst channel = diagnostics_channel.channel('my-channel');\n\nif (channel.hasSubscribers) {\n  // There are subscribers, prepare and publish message\n}\n
", "shortDesc": "If there are active subscribers" } ], "methods": [ { "textRaw": "`channel.publish(message)`", "type": "method", "name": "publish", "meta": { "added": [ "v15.1.0", "v14.17.0" ], "changes": [] }, "signatures": [ { "params": [ { "textRaw": "`message` {any} The message to send to the channel subscribers", "name": "message", "type": "any", "desc": "The message to send to the channel subscribers" } ] } ], "desc": "

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

\n
import diagnostics_channel from 'node:diagnostics_channel';\n\nconst channel = diagnostics_channel.channel('my-channel');\n\nchannel.publish({\n  some: 'message',\n});\n
\n
const diagnostics_channel = require('node:diagnostics_channel');\n\nconst channel = diagnostics_channel.channel('my-channel');\n\nchannel.publish({\n  some: 'message',\n});\n
" }, { "textRaw": "`channel.subscribe(onMessage)`", "type": "method", "name": "subscribe", "meta": { "added": [ "v15.1.0", "v14.17.0" ], "deprecated": [ "v18.7.0" ], "changes": [] }, "stability": 0, "stabilityText": "Deprecated: Use [`diagnostics_channel.subscribe(name, onMessage)`][]", "signatures": [ { "params": [ { "textRaw": "`onMessage` {Function} The handler to receive channel messages", "name": "onMessage", "type": "Function", "desc": "The handler to receive channel messages", "options": [ { "textRaw": "`message` {any} The message data", "name": "message", "type": "any", "desc": "The message data" }, { "textRaw": "`name` {string|symbol} The name of the channel", "name": "name", "type": "string|symbol", "desc": "The name of the channel" } ] } ] } ], "desc": "

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

\n
import diagnostics_channel from 'node:diagnostics_channel';\n\nconst channel = diagnostics_channel.channel('my-channel');\n\nchannel.subscribe((message, name) => {\n  // Received data\n});\n
\n
const diagnostics_channel = require('node:diagnostics_channel');\n\nconst channel = diagnostics_channel.channel('my-channel');\n\nchannel.subscribe((message, name) => {\n  // Received data\n});\n
" }, { "textRaw": "`channel.unsubscribe(onMessage)`", "type": "method", "name": "unsubscribe", "meta": { "added": [ "v15.1.0", "v14.17.0" ], "deprecated": [ "v18.7.0" ], "changes": [ { "version": [ "v17.1.0", "v16.14.0", "v14.19.0" ], "pr-url": "https://github.com/nodejs/node/pull/40433", "description": "Added return value. Added to channels without subscribers." } ] }, "stability": 0, "stabilityText": "Deprecated: Use [`diagnostics_channel.unsubscribe(name, onMessage)`][]", "signatures": [ { "return": { "textRaw": "Returns: {boolean} `true` if the handler was found, `false` otherwise.", "name": "return", "type": "boolean", "desc": "`true` if the handler was found, `false` otherwise." }, "params": [ { "textRaw": "`onMessage` {Function} The previous subscribed handler to remove", "name": "onMessage", "type": "Function", "desc": "The previous subscribed handler to remove" } ] } ], "desc": "

Remove a message handler previously registered to this channel with\nchannel.subscribe(onMessage).

\n
import diagnostics_channel from 'node:diagnostics_channel';\n\nconst channel = diagnostics_channel.channel('my-channel');\n\nfunction onMessage(message, name) {\n  // Received data\n}\n\nchannel.subscribe(onMessage);\n\nchannel.unsubscribe(onMessage);\n
\n
const diagnostics_channel = require('node:diagnostics_channel');\n\nconst channel = diagnostics_channel.channel('my-channel');\n\nfunction onMessage(message, name) {\n  // Received data\n}\n\nchannel.subscribe(onMessage);\n\nchannel.unsubscribe(onMessage);\n
" }, { "textRaw": "`channel.bindStore(store[, transform])`", "type": "method", "name": "bindStore", "meta": { "added": [ "v18.19.0" ], "changes": [] }, "stability": 1, "stabilityText": "Experimental", "signatures": [ { "params": [ { "textRaw": "`store` {AsyncLocalStorage} The store to which to bind the context data", "name": "store", "type": "AsyncLocalStorage", "desc": "The store to which to bind the context data" }, { "textRaw": "`transform` {Function} Transform context data before setting the store context", "name": "transform", "type": "Function", "desc": "Transform context data before setting the store context" } ] } ], "desc": "

When channel.runStores(context, ...) is called, the given context data\nwill be applied to any store bound to the channel. If the store has already been\nbound the previous transform function will be replaced with the new one.\nThe transform function may be omitted to set the given context data as the\ncontext directly.

\n
import diagnostics_channel from 'node:diagnostics_channel';\nimport { AsyncLocalStorage } from 'node:async_hooks';\n\nconst store = new AsyncLocalStorage();\n\nconst channel = diagnostics_channel.channel('my-channel');\n\nchannel.bindStore(store, (data) => {\n  return { data };\n});\n
\n
const diagnostics_channel = require('node:diagnostics_channel');\nconst { AsyncLocalStorage } = require('node:async_hooks');\n\nconst store = new AsyncLocalStorage();\n\nconst channel = diagnostics_channel.channel('my-channel');\n\nchannel.bindStore(store, (data) => {\n  return { data };\n});\n
" }, { "textRaw": "`channel.unbindStore(store)`", "type": "method", "name": "unbindStore", "meta": { "added": [ "v18.19.0" ], "changes": [] }, "stability": 1, "stabilityText": "Experimental", "signatures": [ { "return": { "textRaw": "Returns: {boolean} `true` if the store was found, `false` otherwise.", "name": "return", "type": "boolean", "desc": "`true` if the store was found, `false` otherwise." }, "params": [ { "textRaw": "`store` {AsyncLocalStorage} The store to unbind from the channel.", "name": "store", "type": "AsyncLocalStorage", "desc": "The store to unbind from the channel." } ] } ], "desc": "

Remove a message handler previously registered to this channel with\nchannel.bindStore(store).

\n
import diagnostics_channel from 'node:diagnostics_channel';\nimport { AsyncLocalStorage } from 'node:async_hooks';\n\nconst store = new AsyncLocalStorage();\n\nconst channel = diagnostics_channel.channel('my-channel');\n\nchannel.bindStore(store);\nchannel.unbindStore(store);\n
\n
const diagnostics_channel = require('node:diagnostics_channel');\nconst { AsyncLocalStorage } = require('node:async_hooks');\n\nconst store = new AsyncLocalStorage();\n\nconst channel = diagnostics_channel.channel('my-channel');\n\nchannel.bindStore(store);\nchannel.unbindStore(store);\n
" }, { "textRaw": "`channel.runStores(context, fn[, thisArg[, ...args]])`", "type": "method", "name": "runStores", "meta": { "added": [ "v18.19.0" ], "changes": [] }, "stability": 1, "stabilityText": "Experimental", "signatures": [ { "params": [ { "textRaw": "`context` {any} Message to send to subscribers and bind to stores", "name": "context", "type": "any", "desc": "Message to send to subscribers and bind to stores" }, { "textRaw": "`fn` {Function} Handler to run within the entered storage context", "name": "fn", "type": "Function", "desc": "Handler to run within the entered storage context" }, { "textRaw": "`thisArg` {any} The receiver to be used for the function call.", "name": "thisArg", "type": "any", "desc": "The receiver to be used for the function call." }, { "textRaw": "`...args` {any} Optional arguments to pass to the function.", "name": "...args", "type": "any", "desc": "Optional arguments to pass to the function." } ] } ], "desc": "

Applies the given data to any AsyncLocalStorage instances bound to the channel\nfor the duration of the given function, then publishes to the channel within\nthe scope of that data is applied to the stores.

\n

If a transform function was given to channel.bindStore(store) it will be\napplied to transform the message data before it becomes the context value for\nthe store. The prior storage context is accessible from within the transform\nfunction in cases where context linking is required.

\n

The context applied to the store should be accesible in any async code which\ncontinues from execution which began during the given function, however\nthere are some situations in which context loss may occur.

\n
import diagnostics_channel from 'node:diagnostics_channel';\nimport { AsyncLocalStorage } from 'node:async_hooks';\n\nconst store = new AsyncLocalStorage();\n\nconst channel = diagnostics_channel.channel('my-channel');\n\nchannel.bindStore(store, (message) => {\n  const parent = store.getStore();\n  return new Span(message, parent);\n});\nchannel.runStores({ some: 'message' }, () => {\n  store.getStore(); // Span({ some: 'message' })\n});\n
\n
const diagnostics_channel = require('node:diagnostics_channel');\nconst { AsyncLocalStorage } = require('node:async_hooks');\n\nconst store = new AsyncLocalStorage();\n\nconst channel = diagnostics_channel.channel('my-channel');\n\nchannel.bindStore(store, (message) => {\n  const parent = store.getStore();\n  return new Span(message, parent);\n});\nchannel.runStores({ some: 'message' }, () => {\n  store.getStore(); // Span({ some: 'message' })\n});\n
" } ] }, { "textRaw": "Class: `TracingChannel`", "type": "class", "name": "TracingChannel", "meta": { "added": [ "v18.19.0" ], "changes": [] }, "stability": 1, "stabilityText": "Experimental", "desc": "

The class TracingChannel is a collection of TracingChannel Channels which\ntogether express a single traceable action. It is used to formalize and\nsimplify the process of producing events for tracing application flow.\ndiagnostics_channel.tracingChannel() is used to construct a\nTracingChannel. As with Channel it is recommended to create and reuse a\nsingle TracingChannel at the top-level of the file rather than creating them\ndynamically.

", "methods": [ { "textRaw": "`tracingChannel.subscribe(subscribers)`", "type": "method", "name": "subscribe", "meta": { "added": [ "v18.19.0" ], "changes": [] }, "stability": 1, "stabilityText": "Experimental", "signatures": [ { "params": [ { "textRaw": "`subscribers` {Object} Set of [TracingChannel Channels][] subscribers", "name": "subscribers", "type": "Object", "desc": "Set of [TracingChannel Channels][] subscribers", "options": [ { "textRaw": "`start` {Function} The [`start` event][] subscriber", "name": "start", "type": "Function", "desc": "The [`start` event][] subscriber" }, { "textRaw": "`end` {Function} The [`end` event][] subscriber", "name": "end", "type": "Function", "desc": "The [`end` event][] subscriber" }, { "textRaw": "`asyncStart` {Function} The [`asyncStart` event][] subscriber", "name": "asyncStart", "type": "Function", "desc": "The [`asyncStart` event][] subscriber" }, { "textRaw": "`asyncEnd` {Function} The [`asyncEnd` event][] subscriber", "name": "asyncEnd", "type": "Function", "desc": "The [`asyncEnd` event][] subscriber" }, { "textRaw": "`error` {Function} The [`error` event][] subscriber", "name": "error", "type": "Function", "desc": "The [`error` event][] subscriber" } ] } ] } ], "desc": "

Helper to subscribe a collection of functions to the corresponding channels.\nThis is the same as calling channel.subscribe(onMessage) on each channel\nindividually.

\n
import diagnostics_channel from 'node:diagnostics_channel';\n\nconst channels = diagnostics_channel.tracingChannel('my-channel');\n\nchannels.subscribe({\n  start(message) {\n    // Handle start message\n  },\n  end(message) {\n    // Handle end message\n  },\n  asyncStart(message) {\n    // Handle asyncStart message\n  },\n  asyncEnd(message) {\n    // Handle asyncEnd message\n  },\n  error(message) {\n    // Handle error message\n  },\n});\n
\n
const diagnostics_channel = require('node:diagnostics_channel');\n\nconst channels = diagnostics_channel.tracingChannel('my-channel');\n\nchannels.subscribe({\n  start(message) {\n    // Handle start message\n  },\n  end(message) {\n    // Handle end message\n  },\n  asyncStart(message) {\n    // Handle asyncStart message\n  },\n  asyncEnd(message) {\n    // Handle asyncEnd message\n  },\n  error(message) {\n    // Handle error message\n  },\n});\n
" }, { "textRaw": "`tracingChannel.unsubscribe(subscribers)`", "type": "method", "name": "unsubscribe", "meta": { "added": [ "v18.19.0" ], "changes": [] }, "stability": 1, "stabilityText": "Experimental", "signatures": [ { "return": { "textRaw": "Returns: {boolean} `true` if all handlers were successfully unsubscribed, and `false` otherwise.", "name": "return", "type": "boolean", "desc": "`true` if all handlers were successfully unsubscribed, and `false` otherwise." }, "params": [ { "textRaw": "`subscribers` {Object} Set of [TracingChannel Channels][] subscribers", "name": "subscribers", "type": "Object", "desc": "Set of [TracingChannel Channels][] subscribers", "options": [ { "textRaw": "`start` {Function} The [`start` event][] subscriber", "name": "start", "type": "Function", "desc": "The [`start` event][] subscriber" }, { "textRaw": "`end` {Function} The [`end` event][] subscriber", "name": "end", "type": "Function", "desc": "The [`end` event][] subscriber" }, { "textRaw": "`asyncStart` {Function} The [`asyncStart` event][] subscriber", "name": "asyncStart", "type": "Function", "desc": "The [`asyncStart` event][] subscriber" }, { "textRaw": "`asyncEnd` {Function} The [`asyncEnd` event][] subscriber", "name": "asyncEnd", "type": "Function", "desc": "The [`asyncEnd` event][] subscriber" }, { "textRaw": "`error` {Function} The [`error` event][] subscriber", "name": "error", "type": "Function", "desc": "The [`error` event][] subscriber" } ] } ] } ], "desc": "

Helper to unsubscribe a collection of functions from the corresponding channels.\nThis is the same as calling channel.unsubscribe(onMessage) on each channel\nindividually.

\n
import diagnostics_channel from 'node:diagnostics_channel';\n\nconst channels = diagnostics_channel.tracingChannel('my-channel');\n\nchannels.unsubscribe({\n  start(message) {\n    // Handle start message\n  },\n  end(message) {\n    // Handle end message\n  },\n  asyncStart(message) {\n    // Handle asyncStart message\n  },\n  asyncEnd(message) {\n    // Handle asyncEnd message\n  },\n  error(message) {\n    // Handle error message\n  },\n});\n
\n
const diagnostics_channel = require('node:diagnostics_channel');\n\nconst channels = diagnostics_channel.tracingChannel('my-channel');\n\nchannels.unsubscribe({\n  start(message) {\n    // Handle start message\n  },\n  end(message) {\n    // Handle end message\n  },\n  asyncStart(message) {\n    // Handle asyncStart message\n  },\n  asyncEnd(message) {\n    // Handle asyncEnd message\n  },\n  error(message) {\n    // Handle error message\n  },\n});\n
" }, { "textRaw": "`tracingChannel.traceSync(fn[, context[, thisArg[, ...args]]])`", "type": "method", "name": "traceSync", "meta": { "added": [ "v18.19.0" ], "changes": [] }, "stability": 1, "stabilityText": "Experimental", "signatures": [ { "return": { "textRaw": "Returns: {any} The return value of the given function", "name": "return", "type": "any", "desc": "The return value of the given function" }, "params": [ { "textRaw": "`fn` {Function} Function to wrap a trace around", "name": "fn", "type": "Function", "desc": "Function to wrap a trace around" }, { "textRaw": "`context` {Object} Shared object to correlate events through", "name": "context", "type": "Object", "desc": "Shared object to correlate events through" }, { "textRaw": "`thisArg` {any} The receiver to be used for the function call", "name": "thisArg", "type": "any", "desc": "The receiver to be used for the function call" }, { "textRaw": "`...args` {any} Optional arguments to pass to the function", "name": "...args", "type": "any", "desc": "Optional arguments to pass to the function" } ] } ], "desc": "

Trace a synchronous function call. This will always produce a start event\nand end event around the execution and may produce an error event\nif the given function throws an error. This will run the given function using\nchannel.runStores(context, ...) on the start channel which ensures all\nevents should have any bound stores set to match this trace context.

\n
import diagnostics_channel from 'node:diagnostics_channel';\n\nconst channels = diagnostics_channel.tracingChannel('my-channel');\n\nchannels.traceSync(() => {\n  // Do something\n}, {\n  some: 'thing',\n});\n
\n
const diagnostics_channel = require('node:diagnostics_channel');\n\nconst channels = diagnostics_channel.tracingChannel('my-channel');\n\nchannels.traceSync(() => {\n  // Do something\n}, {\n  some: 'thing',\n});\n
" }, { "textRaw": "`tracingChannel.tracePromise(fn[, context[, thisArg[, ...args]]])`", "type": "method", "name": "tracePromise", "meta": { "added": [ "v18.19.0" ], "changes": [] }, "stability": 1, "stabilityText": "Experimental", "signatures": [ { "return": { "textRaw": "Returns: {Promise} Chained from promise returned by the given function", "name": "return", "type": "Promise", "desc": "Chained from promise returned by the given function" }, "params": [ { "textRaw": "`fn` {Function} Promise-returning function to wrap a trace around", "name": "fn", "type": "Function", "desc": "Promise-returning function to wrap a trace around" }, { "textRaw": "`context` {Object} Shared object to correlate trace events through", "name": "context", "type": "Object", "desc": "Shared object to correlate trace events through" }, { "textRaw": "`thisArg` {any} The receiver to be used for the function call", "name": "thisArg", "type": "any", "desc": "The receiver to be used for the function call" }, { "textRaw": "`...args` {any} Optional arguments to pass to the function", "name": "...args", "type": "any", "desc": "Optional arguments to pass to the function" } ] } ], "desc": "

Trace a promise-returning function call. This will always produce a\nstart event and end event around the synchronous portion of the\nfunction execution, and will produce an asyncStart event and\nasyncEnd event when a promise continuation is reached. It may also\nproduce an error event if the given function throws an error or the\nreturned promise rejects. This will run the given function using\nchannel.runStores(context, ...) on the start channel which ensures all\nevents should have any bound stores set to match this trace context.

\n
import diagnostics_channel from 'node:diagnostics_channel';\n\nconst channels = diagnostics_channel.tracingChannel('my-channel');\n\nchannels.tracePromise(async () => {\n  // Do something\n}, {\n  some: 'thing',\n});\n
\n
const diagnostics_channel = require('node:diagnostics_channel');\n\nconst channels = diagnostics_channel.tracingChannel('my-channel');\n\nchannels.tracePromise(async () => {\n  // Do something\n}, {\n  some: 'thing',\n});\n
" }, { "textRaw": "`tracingChannel.traceCallback(fn[, position[, context[, thisArg[, ...args]]]])`", "type": "method", "name": "traceCallback", "meta": { "added": [ "v18.19.0" ], "changes": [] }, "stability": 1, "stabilityText": "Experimental", "signatures": [ { "return": { "textRaw": "Returns: {any} The return value of the given function", "name": "return", "type": "any", "desc": "The return value of the given function" }, "params": [ { "textRaw": "`fn` {Function} callback using function to wrap a trace around", "name": "fn", "type": "Function", "desc": "callback using function to wrap a trace around" }, { "textRaw": "`position` {number} Zero-indexed argument position of expected callback", "name": "position", "type": "number", "desc": "Zero-indexed argument position of expected callback" }, { "textRaw": "`context` {Object} Shared object to correlate trace events through", "name": "context", "type": "Object", "desc": "Shared object to correlate trace events through" }, { "textRaw": "`thisArg` {any} The receiver to be used for the function call", "name": "thisArg", "type": "any", "desc": "The receiver to be used for the function call" }, { "textRaw": "`...args` {any} Optional arguments to pass to the function", "name": "...args", "type": "any", "desc": "Optional arguments to pass to the function" } ] } ], "desc": "

Trace a callback-receiving function call. This will always produce a\nstart event and end event around the synchronous portion of the\nfunction execution, and will produce a asyncStart event and\nasyncEnd event around the callback execution. It may also produce an\nerror event if the given function throws an error or the returned\npromise rejects. This will run the given function using\nchannel.runStores(context, ...) on the start channel which ensures all\nevents should have any bound stores set to match this trace context.

\n

The position will be -1 by default to indicate the final argument should\nbe used as the callback.

\n
import diagnostics_channel from 'node:diagnostics_channel';\n\nconst channels = diagnostics_channel.tracingChannel('my-channel');\n\nchannels.traceCallback((arg1, callback) => {\n  // Do something\n  callback(null, 'result');\n}, 1, {\n  some: 'thing',\n}, thisArg, arg1, callback);\n
\n
const diagnostics_channel = require('node:diagnostics_channel');\n\nconst channels = diagnostics_channel.tracingChannel('my-channel');\n\nchannels.traceCallback((arg1, callback) => {\n  // Do something\n  callback(null, 'result');\n}, {\n  some: 'thing',\n}, thisArg, arg1, callback);\n
\n

The callback will also be run with channel.runStores(context, ...) which\nenables context loss recovery in some cases.

\n
import diagnostics_channel from 'node:diagnostics_channel';\nimport { AsyncLocalStorage } from 'node:async_hooks';\n\nconst channels = diagnostics_channel.tracingChannel('my-channel');\nconst myStore = new AsyncLocalStorage();\n\n// The start channel sets the initial store data to something\n// and stores that store data value on the trace context object\nchannels.start.bindStore(myStore, (data) => {\n  const span = new Span(data);\n  data.span = span;\n  return span;\n});\n\n// Then asyncStart can restore from that data it stored previously\nchannels.asyncStart.bindStore(myStore, (data) => {\n  return data.span;\n});\n
\n
const diagnostics_channel = require('node:diagnostics_channel');\nconst { AsyncLocalStorage } = require('node:async_hooks');\n\nconst channels = diagnostics_channel.tracingChannel('my-channel');\nconst myStore = new AsyncLocalStorage();\n\n// The start channel sets the initial store data to something\n// and stores that store data value on the trace context object\nchannels.start.bindStore(myStore, (data) => {\n  const span = new Span(data);\n  data.span = span;\n  return span;\n});\n\n// Then asyncStart can restore from that data it stored previously\nchannels.asyncStart.bindStore(myStore, (data) => {\n  return data.span;\n});\n
" } ] } ], "type": "module", "displayName": "Public API" } ], "type": "module", "displayName": "Diagnostics Channel" } ] }