1# Trace events 2 3<!--introduced_in=v7.7.0--> 4 5> Stability: 1 - Experimental 6 7<!-- source_link=lib/trace_events.js --> 8 9The `trace_events` module provides a mechanism to centralize tracing information 10generated by V8, Node.js core, and userspace code. 11 12Tracing can be enabled with the `--trace-event-categories` command-line flag 13or by using the `trace_events` module. The `--trace-event-categories` flag 14accepts a list of comma-separated category names. 15 16The available categories are: 17 18* `node`: An empty placeholder. 19* `node.async_hooks`: Enables capture of detailed [`async_hooks`][] trace data. 20 The [`async_hooks`][] events have a unique `asyncId` and a special `triggerId` 21 `triggerAsyncId` property. 22* `node.bootstrap`: Enables capture of Node.js bootstrap milestones. 23* `node.console`: Enables capture of `console.time()` and `console.count()` 24 output. 25* `node.dns.native`: Enables capture of trace data for DNS queries. 26* `node.environment`: Enables capture of Node.js Environment milestones. 27* `node.fs.sync`: Enables capture of trace data for file system sync methods. 28* `node.perf`: Enables capture of [Performance API][] measurements. 29 * `node.perf.usertiming`: Enables capture of only Performance API User Timing 30 measures and marks. 31 * `node.perf.timerify`: Enables capture of only Performance API timerify 32 measurements. 33* `node.promises.rejections`: Enables capture of trace data tracking the number 34 of unhandled Promise rejections and handled-after-rejections. 35* `node.vm.script`: Enables capture of trace data for the `vm` module's 36 `runInNewContext()`, `runInContext()`, and `runInThisContext()` methods. 37* `v8`: The [V8][] events are GC, compiling, and execution related. 38 39By default the `node`, `node.async_hooks`, and `v8` categories are enabled. 40 41```bash 42node --trace-event-categories v8,node,node.async_hooks server.js 43``` 44 45Prior versions of Node.js required the use of the `--trace-events-enabled` 46flag to enable trace events. This requirement has been removed. However, the 47`--trace-events-enabled` flag *may* still be used and will enable the 48`node`, `node.async_hooks`, and `v8` trace event categories by default. 49 50```bash 51node --trace-events-enabled 52 53# is equivalent to 54 55node --trace-event-categories v8,node,node.async_hooks 56``` 57 58Alternatively, trace events may be enabled using the `trace_events` module: 59 60```js 61const trace_events = require('trace_events'); 62const tracing = trace_events.createTracing({ categories: ['node.perf'] }); 63tracing.enable(); // Enable trace event capture for the 'node.perf' category 64 65// do work 66 67tracing.disable(); // Disable trace event capture for the 'node.perf' category 68``` 69 70Running Node.js with tracing enabled will produce log files that can be opened 71in the [`chrome://tracing`](https://www.chromium.org/developers/how-tos/trace-event-profiling-tool) 72tab of Chrome. 73 74The logging file is by default called `node_trace.${rotation}.log`, where 75`${rotation}` is an incrementing log-rotation id. The filepath pattern can 76be specified with `--trace-event-file-pattern` that accepts a template 77string that supports `${rotation}` and `${pid}`: 78 79```bash 80node --trace-event-categories v8 --trace-event-file-pattern '${pid}-${rotation}.log' server.js 81``` 82 83The tracing system uses the same time source 84as the one used by `process.hrtime()`. 85However the trace-event timestamps are expressed in microseconds, 86unlike `process.hrtime()` which returns nanoseconds. 87 88The features from this module are not available in [`Worker`][] threads. 89 90## The `trace_events` module 91<!-- YAML 92added: v10.0.0 93--> 94 95### `Tracing` object 96<!-- YAML 97added: v10.0.0 98--> 99 100The `Tracing` object is used to enable or disable tracing for sets of 101categories. Instances are created using the `trace_events.createTracing()` 102method. 103 104When created, the `Tracing` object is disabled. Calling the 105`tracing.enable()` method adds the categories to the set of enabled trace event 106categories. Calling `tracing.disable()` will remove the categories from the 107set of enabled trace event categories. 108 109#### `tracing.categories` 110<!-- YAML 111added: v10.0.0 112--> 113 114* {string} 115 116A comma-separated list of the trace event categories covered by this 117`Tracing` object. 118 119#### `tracing.disable()` 120<!-- YAML 121added: v10.0.0 122--> 123 124Disables this `Tracing` object. 125 126Only trace event categories *not* covered by other enabled `Tracing` objects 127and *not* specified by the `--trace-event-categories` flag will be disabled. 128 129```js 130const trace_events = require('trace_events'); 131const t1 = trace_events.createTracing({ categories: ['node', 'v8'] }); 132const t2 = trace_events.createTracing({ categories: ['node.perf', 'node'] }); 133t1.enable(); 134t2.enable(); 135 136// Prints 'node,node.perf,v8' 137console.log(trace_events.getEnabledCategories()); 138 139t2.disable(); // Will only disable emission of the 'node.perf' category 140 141// Prints 'node,v8' 142console.log(trace_events.getEnabledCategories()); 143``` 144 145#### `tracing.enable()` 146<!-- YAML 147added: v10.0.0 148--> 149 150Enables this `Tracing` object for the set of categories covered by the 151`Tracing` object. 152 153#### `tracing.enabled` 154<!-- YAML 155added: v10.0.0 156--> 157 158* {boolean} `true` only if the `Tracing` object has been enabled. 159 160### `trace_events.createTracing(options)` 161<!-- YAML 162added: v10.0.0 163--> 164 165* `options` {Object} 166 * `categories` {string[]} An array of trace category names. Values included 167 in the array are coerced to a string when possible. An error will be 168 thrown if the value cannot be coerced. 169* Returns: {Tracing}. 170 171Creates and returns a `Tracing` object for the given set of `categories`. 172 173```js 174const trace_events = require('trace_events'); 175const categories = ['node.perf', 'node.async_hooks']; 176const tracing = trace_events.createTracing({ categories }); 177tracing.enable(); 178// do stuff 179tracing.disable(); 180``` 181 182### `trace_events.getEnabledCategories()` 183<!-- YAML 184added: v10.0.0 185--> 186 187* Returns: {string} 188 189Returns a comma-separated list of all currently-enabled trace event 190categories. The current set of enabled trace event categories is determined 191by the *union* of all currently-enabled `Tracing` objects and any categories 192enabled using the `--trace-event-categories` flag. 193 194Given the file `test.js` below, the command 195`node --trace-event-categories node.perf test.js` will print 196`'node.async_hooks,node.perf'` to the console. 197 198```js 199const trace_events = require('trace_events'); 200const t1 = trace_events.createTracing({ categories: ['node.async_hooks'] }); 201const t2 = trace_events.createTracing({ categories: ['node.perf'] }); 202const t3 = trace_events.createTracing({ categories: ['v8'] }); 203 204t1.enable(); 205t2.enable(); 206 207console.log(trace_events.getEnabledCategories()); 208``` 209 210[Performance API]: perf_hooks.md 211[V8]: v8.md 212[`Worker`]: worker_threads.md#worker_threads_class_worker 213[`async_hooks`]: async_hooks.md 214