1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
|
# 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.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
|
