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.
import dc from 'node:diagnostics_channel'; const tc = dc.tracingChannel('app:query'); tc.traceSync(() => 42, { sql: 'select 1' });
Try it
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.
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
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
endis not the end of async work. For promises and callbacks,endmarks the moment the function returned; the completion events areasyncStartandasyncEnd.- Errors are rethrown. The
errorchannel is only a notification; the caller still sees the exception or rejection. For a synchronous throw the order isstart,error,end. - Match events with the context. Add your own fields (timestamps, span ids) to
ctxinstartand read them later. Do not assume events from different calls interleave in order. - Use
hasSubscribersto stay cheap. When there are no subscribers, thetrace*methods callfndirectly with almost no overhead. traceCallback()wraps the callback atpositionso that calling it firesasyncStartandasyncEnd, and a first argument that is truthy is reported as an error.- Add context stores with
bindStoreon thestartchannel (tc.start.bindStore(...)) when tracing should also set anAsyncLocalStorage. - 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.