Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท node:sqlite and Runtime Services

Node.js TracingChannel class

Reference for diagnostics_channel.tracingChannel(): the start, end, asyncStart, asyncEnd and error channels, and traceSync, tracePromise and traceCallback.

A TracingChannel is a bundle of five related diagnostic channels that describe the life of one operation: start, end, asyncStart, asyncEnd and error. A library wraps its work in traceSync(), tracePromise() or traceCallback(), and tools subscribe once to follow every call from beginning to end, with durations and errors.

All five events for one call receive the same context object, so a subscriber can store a start time on it in start and read it again in end. This is how tracing tools match events that belong together.

NODE
import dc from 'node:diagnostics_channel';

const tc = dc.tracingChannel('app:query');
tc.traceSync(() => 42, { sql: 'select 1' });

Try it

Node.js Tracing a synchronous call

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Node.js Tracing a promise

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Syntax

NODE
const tc = diagnostics_channel.tracingChannel(nameOrChannels);

tc.subscribe({ start, end, asyncStart, asyncEnd, error });
tc.unsubscribe(handlers);
tc.traceSync(fn, context, thisArg, ...args);
tc.tracePromise(fn, context, thisArg, ...args);
tc.traceCallback(fn, position, context, thisArg, ...args);
tc.hasSubscribers;
Name Description
nameOrChannels A name such as 'app:query', which creates channels called tracing:app:query:start, :end, :asyncStart, :asyncEnd and :error, or an object holding the five Channel objects.
handlers An object with any of the five handler functions. Each receives (context, name).
fn The function to run and trace.
context An object shared by all events of this call. Defaults to {}.
thisArg, ...args The this value and arguments for fn.
position For traceCallback(): index of the callback argument. Default -1 (the last).

Events in order: start before fn runs; end when fn returns or throws; asyncStart when the promise settles or the callback is invoked; asyncEnd after that settlement is handled; error whenever it fails, with context.error set. On success context.result holds the return or fulfilled value.

Returns: the return value of fn (traceSync), a promise for the same outcome (tracePromise), or whatever fn returns (traceCallback).

Usage notes

  • end is not the end of async work. For promises and callbacks, end marks the moment the function returned; the completion events are asyncStart and asyncEnd.
  • Errors are rethrown. The error channel is only a notification; the caller still sees the exception or rejection. For a synchronous throw the order is start, error, end.
  • Match events with the context. Add your own fields (timestamps, span ids) to ctx in start and read them later. Do not assume events from different calls interleave in order.
  • Use hasSubscribers to stay cheap. When there are no subscribers, the trace* methods call fn directly with almost no overhead.
  • traceCallback() wraps the callback at position so that calling it fires asyncStart and asyncEnd, and a first argument that is truthy is reported as an error.
  • Add context stores with bindStore on the start channel (tc.start.bindStore(...)) when tracing should also set an AsyncLocalStorage.
  • Available in Node.js 19.9 / 18.19 and later; the API was marked experimental for a long time, so check the docs for your version.