Node.js v24.0.0-nightly20241211fd9a79df7d documentation

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 copy

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

# is equivalent to

node --trace-event-categories v8,node,node.async_hooks copy

Alternatively, trace events may be enabled using the node:trace_events module:

const trace_events = require('node:trace_events');
const tracing = trace_events.createTracing({ categories: ['node.perf'] });
tracing.enable();  // Enable trace event capture for the 'node.perf' category

// do work

tracing.disable();  // Disable trace event capture for the 'node.perf' category copy

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 copy

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);  // Or applicable exit code depending on OS and signal
}); copy

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.

const trace_events = require('node:trace_events');
const t1 = trace_events.createTracing({ categories: ['node', 'v8'] });
const t2 = trace_events.createTracing({ categories: ['node.perf', 'node'] });
t1.enable();
t2.enable();

// Prints 'node,node.perf,v8'
console.log(trace_events.getEnabledCategories());

t2.disable(); // Will only disable emission of the 'node.perf' category

// Prints 'node,v8'
console.log(trace_events.getEnabledCategories()); copy

const trace_events = require('node:trace_events');
const categories = ['node.perf', 'node.async_hooks'];
const tracing = trace_events.createTracing({ categories });
tracing.enable();
// do stuff
tracing.disable(); copy

const trace_events = require('node:trace_events');
const t1 = trace_events.createTracing({ categories: ['node.async_hooks'] });
const t2 = trace_events.createTracing({ categories: ['node.perf'] });
const t3 = trace_events.createTracing({ categories: ['v8'] });

t1.enable();
t2.enable();

console.log(trace_events.getEnabledCategories()); copy

'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', () => {
    // done
  });
  const traceConfig = { includedCategories: ['v8'] };
  await post('NodeTracing.start', { traceConfig });
  // do something
  setTimeout(() => {
    post('NodeTracing.stop').then(() => {
      session.disconnect();
      console.log(data);
    });
  }, 1000);
}

collect(); copy