- Assertion testing
- Asynchronous context tracking
- Async hooks
- Buffer
- C++ addons
- C/C++ addons with Node-API
- C++ embedder API
- Child processes
- Cluster
- Command-line options
- Console
- Corepack
- Crypto
- Debugger
- Deprecated APIs
- Diagnostics Channel
- DNS
- Domain
- Errors
- Events
- File system
- Globals
- HTTP
- HTTP/2
- HTTPS
- Inspector
- Internationalization
- Modules: CommonJS modules
- Modules: ECMAScript modules
- Modules:
node:module
API - Modules: Packages
- Net
- OS
- Path
- Performance hooks
- Permissions
- Process
- Punycode
- Query strings
- Readline
- REPL
- Report
- Stream
- String decoder
- Test runner
- Timers
- TLS/SSL
- Trace events
- TTY
- UDP/datagram
- URL
- Utilities
- V8
- VM
- WASI
- Web Crypto API
- Web Streams API
- Worker threads
- Zlib
Node.js v18.12.1 documentation
- Node.js v18.12.1
- ► Table of contents
-
► Index
- Assertion testing
- Asynchronous context tracking
- Async hooks
- Buffer
- C++ addons
- C/C++ addons with Node-API
- C++ embedder API
- Child processes
- Cluster
- Command-line options
- Console
- Corepack
- Crypto
- Debugger
- Deprecated APIs
- Diagnostics Channel
- DNS
- Domain
- Errors
- Events
- File system
- Globals
- HTTP
- HTTP/2
- HTTPS
- Inspector
- Internationalization
- Modules: CommonJS modules
- Modules: ECMAScript modules
- Modules:
node:module
API - Modules: Packages
- Net
- OS
- Path
- Performance hooks
- Permissions
- Process
- Punycode
- Query strings
- Readline
- REPL
- Report
- Stream
- String decoder
- Test runner
- Timers
- TLS/SSL
- Trace events
- TTY
- UDP/datagram
- URL
- Utilities
- V8
- VM
- WASI
- Web Crypto API
- Web Streams API
- Worker threads
- Zlib
- ► Other versions
- ► Options
Table of contents
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 detailedasync_hooks
trace data. Theasync_hooks
events have a uniqueasyncId
and a specialtriggerId
triggerAsyncId
property.node.bootstrap
: Enables capture of Node.js bootstrap milestones.node.console
: Enables capture ofconsole.time()
andconsole.count()
output.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 thenode:vm
module'srunInNewContext()
,runInContext()
, andrunInThisContext()
methods.v8
: The V8 events are GC, compiling, and execution related.node.http
: Enables capture of trace data for http request / response.
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
# is equivalent to
node --trace-event-categories v8,node,node.async_hooks
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
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); // Or applicable exit code depending on OS and signal
});
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.