Stability: 1 - Experimental

    The 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 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.dns.native: Enables capture of trace data for DNS queries.
    • node.environment: Enables capture of Node.js Environment milestones.
    • node.fs.sync: Enables capture of trace data for file system sync 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 vm module’s runInNewContext(), runInContext(), and runInThisContext() methods.
    • v8: The [V8][] events are GC, compiling, and execution related.

    By default the node, node.async_hooks, and v8 categories are enabled.

    1. 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.

    1. node --trace-events-enabled
    3. # is equivalent to
    5. node --trace-event-categories v8,node,node.async_hooks

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

    1. const trace_events = require('trace_events');
    2. const tracing = trace_events.createTracing({ categories: ['node.perf'] });
    3. tracing.enable();  // Enable trace event capture for the 'node.perf' category
    5. // do work
    7. tracing.disable();  // Disable trace event capture for the 'node.perf' category

    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}:

    1. node --trace-event-categories v8 --trace-event-file-pattern '${pid}-${rotation}.log' server.js

    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.