mirror of
https://github.com/nodejs/node.git
synced 2024-12-01 16:10:02 +01:00
10040500da
The use of dashes -- in general, but especially in our docs -- can be problematic. It is used inconsistently and there is always another form of punctuation that is as good or better for the situation. In an effort to reduce the number of variations we use to display the same types of information, remove the various uses of dashes from the documentation. PR-URL: https://github.com/nodejs/node/pull/30101 Reviewed-By: Gireesh Punathil <gpunathi@in.ibm.com> Reviewed-By: Richard Lau <riclau@uk.ibm.com> Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com>
212 lines
6.6 KiB
Markdown
212 lines
6.6 KiB
Markdown
# Trace Events
|
|
|
|
<!--introduced_in=v7.7.0-->
|
|
|
|
> Stability: 1 - Experimental
|
|
|
|
Trace Event 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.
|
|
|
|
```txt
|
|
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.
|
|
|
|
```txt
|
|
node --trace-events-enabled
|
|
|
|
// is equivalent to
|
|
|
|
node --trace-event-categories v8,node,node.async_hooks
|
|
```
|
|
|
|
Alternatively, trace events may be enabled using the `trace_events` module:
|
|
|
|
```js
|
|
const trace_events = require('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}`:
|
|
|
|
```txt
|
|
node --trace-event-categories v8 --trace-event-file-pattern '${pid}-${rotation}.log' server.js
|
|
```
|
|
|
|
Starting with Node.js 10.0.0, 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 `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('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('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('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());
|
|
```
|
|
|
|
[Performance API]: perf_hooks.html
|
|
[V8]: v8.html
|
|
[`Worker`]: worker_threads.html#worker_threads_class_worker
|
|
[`async_hooks`]: async_hooks.html
|