Skip to content

diagnostics_channel: specialized tracing channels #62641

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
Qard wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

diagnostics_channel: specialized tracing channels #62641

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
204 changes: 203 additions & 1 deletion doc/api/diagnostics_channel.md
View file
Open in desktop
Copy link
Copy Markdown

@jsumners-nr jsumners-nr Apr 10, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm having a bit of difficulty following these changes. I think having an example of usage for each of the methods will be very helpful.

Copy link
Copy Markdown
Member Author

@Qard Qard Apr 10, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, I'll get to documenting it better. The general idea is to split calls from continuations, and to split different forms of continuation from each other.

const syncChannel = dc.syncTracingChannel('test')
const callbackChannel = dc.callbackTracingChannel('test')
const promiseChannel = dc.promiseTracingChannel('test')

function callbackOrPromiseFn(cb) {
  if (cb) return setImmediate(cb)
  return new Promise(resolve => setImmediate(resolve))
}

// Wrap the sync portion of any call
const wrappedFoo = syncChannel.wrap(callbackOrPromiseFn, {
  // Wrap the callback to produce asyncStart/asyncEnd, if present
  wrapArgs(args) {
    if (!args.length) return []
    return [ callbackChannel.wrap(args[0]) ]
  },
  // Wrap the returned promise to produce asyncStart/asyncEnd, if present
  mapOutcome(maybePromise) {
    if (!Promise.isPromise(maybePromise)) return maybePromise
    return promiseChannel.wrap(maybePromise)
  }
})

It's a bit more verbose than what we have now, but a lot more flexible to compose different patterns user code may do. We can also build the higher-level abstractions over top of this for the cases where simpler abstractions are viable.

Copy link
Copy Markdown

@jsumners-nr jsumners-nr Apr 10, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you. That example is very helpful.

Original file line number Diff line number Diff line change
Expand Up @@ -266,6 +266,91 @@ const channelsByCollection = diagnostics_channel.tracingChannel({
});
```

#### `diagnostics_channel.syncTracingChannel(nameOrChannels)`

<!-- YAML
added:
- REPLACEME
-->

> Stability: 1 - Experimental

* `nameOrChannels` {string|SyncTracingChannel|Object} Channel name or
object containing the `start`, `end`, and `error` channels
* Returns: {SyncTracingChannel}

Creates a [`SyncTracingChannel`][] wrapper. Named construction creates channels
using `tracing:${name}:start`, `tracing:${name}:end`, and
`tracing:${name}:error`.

#### `diagnostics_channel.callbackTracingChannel(nameOrChannels)`

<!-- YAML
added:
- REPLACEME
-->

> Stability: 1 - Experimental

* `nameOrChannels` {string|CallbackTracingChannel|Object} Channel name or
object containing the `asyncStart`, `asyncEnd`, and `error` channels
* Returns: {CallbackTracingChannel}

Creates a [`CallbackTracingChannel`][] wrapper. Named construction creates
channels using `tracing:${name}:asyncStart`, `tracing:${name}:asyncEnd`, and
`tracing:${name}:error`.

#### `diagnostics_channel.promiseTracingChannel(nameOrChannels)`

<!-- YAML
added:
- REPLACEME
-->

> Stability: 1 - Experimental

* `nameOrChannels` {string|PromiseTracingChannel|Object} Channel name or object
containing the `asyncStart`, `asyncEnd`, and `error` channels
* Returns: {PromiseTracingChannel}

Creates a [`PromiseTracingChannel`][] wrapper. Named construction creates
channels using `tracing:${name}:asyncStart`, `tracing:${name}:asyncEnd`, and
`tracing:${name}:error`.

#### `diagnostics_channel.syncIteratorTracingChannel(nameOrChannels)`

<!-- YAML
added:
- REPLACEME
-->

> Stability: 1 - Experimental

* `nameOrChannels` {string|SyncIteratorTracingChannel|Object} Channel name or
object containing the `yield`, `return`, and `error` channels
* Returns: {SyncIteratorTracingChannel}

Creates a [`SyncIteratorTracingChannel`][] wrapper. Named construction creates
channels using `tracing:${name}:syncYield`, `tracing:${name}:return`, and
`tracing:${name}:error`.

#### `diagnostics_channel.asyncIteratorTracingChannel(nameOrChannels)`

<!-- YAML
added:
- REPLACEME
-->

> Stability: 1 - Experimental

* `nameOrChannels` {string|AsyncIteratorTracingChannel|Object} Channel name or
object containing the `yield`, `return`, and `error` channels
* Returns: {AsyncIteratorTracingChannel}

Creates an [`AsyncIteratorTracingChannel`][] wrapper. Named construction creates
channels using `tracing:${name}:asyncYield`, `tracing:${name}:return`, and
`tracing:${name}:error`.

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

Expand Down Expand Up @@ -754,7 +839,34 @@ simplify the process of producing events for tracing application flow.
[`diagnostics_channel.tracingChannel()`][] is used to construct a
`TracingChannel`. As with `Channel` it is recommended to create and reuse a
single `TracingChannel` at the top-level of the file rather than creating them
dynamically.
dynamically. `TracingChannel` remains the aggregate compatibility wrapper for
the original tracing channels.

#### `tracingChannel.wrap(fn[, options])`

<!-- YAML
added:
- REPLACEME
-->

* `fn` {Function} Function to wrap
* `options` {Object}
* `context` {Object|Function} Context object or per-call context builder
* `wrapArgs` {Function} Rewrite arguments before the call
* `mapResult` {Function} Transform the immediate return value
* Returns: {Function} Wrapped function

Wrap a function once and reuse the wrapped callable across multiple invocations.
This is the recommended API for composing tracing behavior. The `context`
option may be either a plain object or a builder function. If `context` is an
object, that same object is published for each operation. If `context` is a
function, it is called once per invocation with the wrapped receiver as `this`
and the original arguments. `wrapArgs` and `mapResult` run inside the
synchronous trace, so errors thrown from either are treated as call errors.

This method is intended to compose the specialized tracers. For example,
`wrapArgs` can use `callbackTracingChannel.wrapArgs()` and `mapResult` can use
`promiseTracingChannel.wrap()` or one of the iterator wrappers.

#### `tracingChannel.subscribe(subscribers)`

Expand Down Expand Up @@ -1419,6 +1531,91 @@ is automatically published when disposal occurs at the end of the block. All
events share the same context object, which can be extended with additional
properties like `result` during scope execution.

### Class: `SyncTracingChannel`

> Stability: 1 - Experimental

`SyncTracingChannel` publishes `start`, `end`, and `error` events around the
synchronous call boundary of a wrapped function.

#### `syncTracingChannel.wrap(fn[, options])`

* `fn` {Function} Function to wrap
* `options` {Object}
* `context` {Object|Function} Context object or per-call context builder
* `wrapArgs` {Function} Rewrite arguments before the call
* `mapResult` {Function} Transform the immediate return value
* Returns: {Function} Wrapped function

### Class: `CallbackTracingChannel`

> Stability: 1 - Experimental

`CallbackTracingChannel` wraps callback functions and callback arguments using
`asyncStart`, `asyncEnd`, and `error`.

#### `callbackTracingChannel.wrap(callback[, options])`

* `callback` {Function} Callback to wrap
* `options` {Object}
* `context` {Object|Function} Context object or callback-time context builder
* `mapOutcome` {Function} Map callback arguments to `{ error, result }`
* Returns: {Function} Wrapped callback

#### `callbackTracingChannel.wrapArgs(args, index[, options])`

* `args` {Array} Arguments array
* `index` {number} Index of the callback argument
* `options` {Object}
* `context` {Object|Function} Context object or callback-time context builder
* `mapOutcome` {Function} Map callback arguments to `{ error, result }`
* Returns: {Array} A shallow copy of `args` with the callback replaced

### Class: `PromiseTracingChannel`

> Stability: 1 - Experimental

`PromiseTracingChannel` instruments a thenable or promise that has already been
produced and publishes `asyncStart`, `asyncEnd`, and `error` on settlement.

#### `promiseTracingChannel.wrap(value[, options])`

* `value` {any} Promise or thenable to wrap
* `options` {Object}
* `context` {Object|Function} Context object or context builder
* `mapResult` {Function} Transform the fulfilled value
* Returns: {any} The original value, or the result of calling `.then(...)`

### Class: `SyncIteratorTracingChannel`

> Stability: 1 - Experimental

`SyncIteratorTracingChannel` instruments a synchronous iterator and publishes
`yield`, `return`, and `error` events for `next()`, `return()`, and `throw()`.

#### `syncIteratorTracingChannel.wrap(iterator[, options])`

* `iterator` {Object} Iterator to wrap
* `options` {Object}
* `context` {Object|Function} Context object or context builder
* `mapResult` {Function} Transform the produced `IteratorResult`
* Returns: {Object} Wrapped iterator

### Class: `AsyncIteratorTracingChannel`

> Stability: 1 - Experimental

`AsyncIteratorTracingChannel` instruments an asynchronous iterator and publishes
`yield`, `return`, and `error` events for `next()`, `return()`, and `throw()`.

#### `asyncIteratorTracingChannel.wrap(iterator[, options])`

* `iterator` {Object} Async iterator to wrap
* `options` {Object}
* `context` {Object|Function} Context object or context builder
* `mapResult` {Function} Transform the produced `IteratorResult`
* Returns: {Object} Wrapped iterator

### TracingChannel Channels

A TracingChannel is a collection of several diagnostics\_channels representing
Expand Down Expand Up @@ -1914,8 +2111,13 @@ Emitted when a new thread is created.
[BoundedChannel Channels]: #boundedchannel-channels
[TracingChannel Channels]: #tracingchannel-channels
[`'uncaughtException'`]: process.md#event-uncaughtexception
[`AsyncIteratorTracingChannel`]: #class-asynciteratortracingchannel
[`BoundedChannel`]: #class-boundedchannel
[`TracingChannel`]: #class-tracingchannel
[`CallbackTracingChannel`]: #class-callbacktracingchannel
[`PromiseTracingChannel`]: #class-promisetracingchannel
[`SyncIteratorTracingChannel`]: #class-synciteratortracingchannel
[`SyncTracingChannel`]: #class-synctracingchannel
[`asyncEnd` event]: #asyncendevent
[`asyncStart` event]: #asyncstartevent
[`boundedChannel.withScope(context)`]: #boundedchannelwithscopecontext
Expand Down
5 changes: 5 additions & 0 deletions doc/type-map.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@
"AsyncHook": "async_hooks.html#async_hookscreatehookoptions",
"AsyncLocalStorage": "async_context.html#class-asynclocalstorage",
"AsyncResource": "async_hooks.html#class-asyncresource",
"AsyncIteratorTracingChannel": "diagnostics_channel.html#class-asynciteratortracingchannel",
"AesCbcParams": "webcrypto.html#class-aescbcparams",
"AesCtrParams": "webcrypto.html#class-aesctrparams",
"AesGcmParams": "webcrypto.html#class-aesgcmparams",
Expand All @@ -16,6 +17,7 @@
"BroadcastChannel": "worker_threads.html#class-broadcastchannel-extends-eventtarget",
"Buffer": "buffer.html#class-buffer",
"ByteLengthQueuingStrategy": "webstreams.html#class-bytelengthqueuingstrategy",
"CallbackTracingChannel": "diagnostics_channel.html#class-callbacktracingchannel",
"Channel": "diagnostics_channel.html#class-channel",
"ChildProcess": "child_process.html#class-childprocess",
"Cipher": "crypto.html#class-cipher",
Expand Down Expand Up @@ -72,6 +74,7 @@
"PerformanceNodeTiming": "perf_hooks.html#class-performancenodetiming",
"PerformanceObserver": "perf_hooks.html#class-performanceobserver",
"PerformanceObserverEntryList": "perf_hooks.html#class-performanceobserverentrylist",
"PromiseTracingChannel": "diagnostics_channel.html#class-promisetracingchannel",
"Readable": "stream.html#class-streamreadable",
"ReadableByteStreamController": "webstreams.html#class-readablebytestreamcontroller",
"ReadableStream": "webstreams.html#class-readablestream",
Expand All @@ -92,6 +95,8 @@
"Sign": "crypto.html#class-sign",
"Disposable": "https://tc39.es/proposal-explicit-resource-management/#sec-disposable-interface",
"Session": "sqlite.html#class-session",
"SyncIteratorTracingChannel": "diagnostics_channel.html#class-synciteratortracingchannel",
"SyncTracingChannel": "diagnostics_channel.html#class-synctracingchannel",
"StatementSync": "sqlite.html#class-statementsync",
"Stream": "stream.html#stream",
"SubtleCrypto": "webcrypto.html#class-subtlecrypto",
Expand Down
Loading
Loading