Trace events#
Source Code: lib/trace_events.js
The node:trace_events module provides a mechanism to centralize tracing
information generated by V8, Node.js core, and userspace code.
Tracing can be enabled with the --trace-event-categories command-line flag
or by using the node:trace_events module. The --trace-event-categories flag
accepts a list of comma-separated category names.
The available categories are:
node: An empty placeholder.
node.async_hooks: Enables capture of detailed async_hooks trace data.
The async_hooks events have a unique asyncId and a special triggerId
triggerAsyncId property.
node.bootstrap: Enables capture of Node.js bootstrap milestones.
node.console: Enables capture of console.time() and console.count()
output.
node.threadpoolwork.sync: Enables capture of trace data for threadpool
synchronous operations, such as blob, zlib, crypto and node_api.
node.threadpoolwork.async: Enables capture of trace data for threadpool
asynchronous operations, such as blob, zlib, crypto and node_api.
node.dns.native: Enables capture of trace data for DNS queries.
node.net.native: Enables capture of trace data for network.
node.environment: Enables capture of Node.js Environment milestones.
node.fs.sync: Enables capture of trace data for file system sync methods.
node.fs_dir.sync: Enables capture of trace data for file system sync
directory methods.
node.fs.async: Enables capture of trace data for file system async methods.
node.fs_dir.async: Enables capture of trace data for file system async
directory methods.
node.perf: Enables capture of Performance API measurements.
node.perf.usertiming: Enables capture of only Performance API User Timing
measures and marks.
node.perf.timerify: Enables capture of only Performance API timerify
measurements.
node.promises.rejections: Enables capture of trace data tracking the number
of unhandled Promise rejections and handled-after-rejections.
node.vm.script: Enables capture of trace data for the node:vm module's
runInNewContext(), runInContext(), and runInThisContext() methods.
v8: The V8 events are GC, compiling, and execution related.
node.http: Enables capture of trace data for http request / response.
node.module_timer: Enables capture of trace data for CJS Module loading.
By default the node, node.async_hooks, and v8 categories are enabled.
node --trace-event-categories v8,node,node.async_hooks server.js
Prior versions of Node.js required the use of the --trace-events-enabled
flag to enable trace events. This requirement has been removed. However, the
--trace-events-enabled flag may still be used and will enable the
node, node.async_hooks, and v8 trace event categories by default.
node --trace-events-enabled
node --trace-event-categories v8,node,node.async_hooks
Alternatively, trace events may be enabled using the node:trace_events module:
import { createTracing } from 'node:trace_events';
const tracing = createTracing({ categories: ['node.perf'] });
tracing.enable();
tracing.disable(); const { createTracing } = require('node:trace_events');
const tracing = createTracing({ categories: ['node.perf'] });
tracing.enable();
tracing.disable();
Running Node.js with tracing enabled will produce log files that can be opened
in the chrome://tracing
tab of Chrome.
The logging file is by default called node_trace.${rotation}.log, where
${rotation} is an incrementing log-rotation id. The filepath pattern can
be specified with --trace-event-file-pattern that accepts a template
string that supports ${rotation} and ${pid}:
node --trace-event-categories v8 --trace-event-file-pattern '${pid}-${rotation}.log' server.js
To guarantee that the log file is properly generated after signal events like
SIGINT, SIGTERM, or SIGBREAK, make sure to have the appropriate handlers
in your code, such as:
process.on('SIGINT', function onSigint() {
console.info('Received SIGINT.');
process.exit(130);
});
The tracing system uses the same time source
as the one used by process.hrtime().
However the trace-event timestamps are expressed in microseconds,
unlike process.hrtime() which returns nanoseconds.
The features from this module are not available in Worker threads.
The node:trace_events module#
Added in: v10.0.0
Tracing object#
Added in: v10.0.0
The Tracing object is used to enable or disable tracing for sets of
categories. Instances are created using the trace_events.createTracing()
method.
When created, the Tracing object is disabled. Calling the
tracing.enable() method adds the categories to the set of enabled trace event
categories. Calling tracing.disable() will remove the categories from the
set of enabled trace event categories.
tracing.categories#
Added in: v10.0.0
A comma-separated list of the trace event categories covered by this
Tracing object.
tracing.disable()#
Added in: v10.0.0
Disables this Tracing object.
Only trace event categories not covered by other enabled Tracing objects
and not specified by the --trace-event-categories flag will be disabled.
import { createTracing, getEnabledCategories } from 'node:trace_events';
const t1 = createTracing({ categories: ['node', 'v8'] });
const t2 = createTracing({ categories: ['node.perf', 'node'] });
t1.enable();
t2.enable();
console.log(getEnabledCategories());
t2.disable();
console.log(getEnabledCategories());const { createTracing, getEnabledCategories } = require('node:trace_events');
const t1 = createTracing({ categories: ['node', 'v8'] });
const t2 = createTracing({ categories: ['node.perf', 'node'] });
t1.enable();
t2.enable();
console.log(getEnabledCategories());
t2.disable();
console.log(getEnabledCategories());
tracing.enable()#
Added in: v10.0.0
Enables this Tracing object for the set of categories covered by the
Tracing object.
tracing.enabled#
Added in: v10.0.0
- Type: <boolean>
true only if the Tracing object has been enabled.
trace_events.getEnabledCategories()#
Added in: v10.0.0
Returns a comma-separated list of all currently-enabled trace event
categories. The current set of enabled trace event categories is determined
by the union of all currently-enabled Tracing objects and any categories
enabled using the --trace-event-categories flag.
Given the file test.js below, the command
node --trace-event-categories node.perf test.js will print
'node.async_hooks,node.perf' to the console.
import { createTracing, getEnabledCategories } from 'node:trace_events';
const t1 = createTracing({ categories: ['node.async_hooks'] });
const t2 = createTracing({ categories: ['node.perf'] });
const t3 = createTracing({ categories: ['v8'] });
t1.enable();
t2.enable();
console.log(getEnabledCategories());const { createTracing, getEnabledCategories } = require('node:trace_events');
const t1 = createTracing({ categories: ['node.async_hooks'] });
const t2 = createTracing({ categories: ['node.perf'] });
const t3 = createTracing({ categories: ['v8'] });
t1.enable();
t2.enable();
console.log(getEnabledCategories());
Examples#
Collect trace events data by inspector#
import { Session } from 'node:inspector';
const session = new Session();
session.connect();
function post(message, data) {
return new Promise((resolve, reject) => {
session.post(message, data, (err, result) => {
if (err)
reject(new Error(JSON.stringify(err)));
else
resolve(result);
});
});
}
async function collect() {
const data = [];
session.on('NodeTracing.dataCollected', (chunk) => data.push(chunk));
session.on('NodeTracing.tracingComplete', () => {
});
const traceConfig = { includedCategories: ['v8'] };
await post('NodeTracing.start', { traceConfig });
setTimeout(() => {
post('NodeTracing.stop').then(() => {
session.disconnect();
console.log(data);
});
}, 1000);
}
collect();'use strict';
const { Session } = require('node:inspector');
const session = new Session();
session.connect();
function post(message, data) {
return new Promise((resolve, reject) => {
session.post(message, data, (err, result) => {
if (err)
reject(new Error(JSON.stringify(err)));
else
resolve(result);
});
});
}
async function collect() {
const data = [];
session.on('NodeTracing.dataCollected', (chunk) => data.push(chunk));
session.on('NodeTracing.tracingComplete', () => {
});
const traceConfig = { includedCategories: ['v8'] };
await post('NodeTracing.start', { traceConfig });
setTimeout(() => {
post('NodeTracing.stop').then(() => {
session.disconnect();
console.log(data);
});
}, 1000);
}
collect();