# Trace events
<!--introduced_in=v7.7.0-->
> Stability: 1 - Experimental
<!-- source_link=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.
By default the `node`, `node.async_hooks`, and `v8` categories are enabled.
```bash
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.
```bash
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:
```js
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`](https://www.chromium.org/developers/how-tos/trace-event-profiling-tool)
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}`:
```bash
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:
```js
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.
## The `node:trace_events` module
<!-- YAML
added: v10.0.0
-->
### `Tracing` object
<!-- YAML
added: 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`
<!-- YAML
added: v10.0.0
-->
* {string}
A comma-separated list of the trace event categories covered by this
`Tracing` object.
#### `tracing.disable()`
<!-- YAML
added: 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.
```js
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());
```
#### `tracing.enable()`
<!-- YAML
added: v10.0.0
-->
Enables this `Tracing` object for the set of categories covered by the
`Tracing` object.
#### `tracing.enabled`
<!-- YAML
added: v10.0.0
-->
* {boolean} `true` only if the `Tracing` object has been enabled.
### `trace_events.createTracing(options)`
<!-- YAML
added: v10.0.0
-->
* `options` {Object}
* `categories` {string\[]} An array of trace category names. Values included
in the array are coerced to a string when possible. An error will be
thrown if the value cannot be coerced.
* Returns: {Tracing}.
Creates and returns a `Tracing` object for the given set of `categories`.
```js
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();
```
### `trace_events.getEnabledCategories()`
<!-- YAML
added: v10.0.0
-->
* Returns: {string}
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.
```js
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());
```
## Examples
### Collect trace events data by inspector
```js
'use strict';
const { Session } = require('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();
```
[Performance API]: perf_hooks.md
[V8]: v8.md
[`Worker`]: worker_threads.md#class-worker
[`async_hooks`]: async_hooks.md
Generated by dwww version 1.15 on Sun Jun 30 09:30:20 CEST 2024.