{ "type": "module", "source": "doc/api/tracing.md", "modules": [ { "textRaw": "Trace Events", "name": "trace_events", "introduced_in": "v7.7.0", "stability": 1, "stabilityText": "Experimental", "desc": "
Trace Event provides a mechanism to centralize tracing information generated by\nV8, Node.js core, and userspace code.
\nTracing can be enabled with the --trace-event-categories
command-line flag\nor by using the trace_events
module. The --trace-event-categories
flag\naccepts a list of comma-separated category names.
The available categories are:
\nnode
- An empty placeholder.node.async_hooks
- Enables capture of detailed async_hooks
trace data.\nThe async_hooks
events have a unique asyncId
and a special triggerId
\ntriggerAsyncId
property.node.bootstrap
- Enables capture of Node.js bootstrap 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\nmeasures and marks.node.perf.timerify
- Enables capture of only Performance API timerify\nmeasurements.node.promises.rejections
- Enables capture of trace data tracking the number\nof unhandled Promise rejections and handled-after-rejections.node.vm.script
- Enables capture of trace data for the vm
module's\nrunInNewContext()
, 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.
node --trace-event-categories v8,node,node.async_hooks server.js\n
\nPrior versions of Node.js required the use of the --trace-events-enabled
\nflag to enable trace events. This requirement has been removed. However, the\n--trace-events-enabled
flag may still be used and will enable the\nnode
, node.async_hooks
, and v8
trace event categories by default.
node --trace-events-enabled\n\n// is equivalent to\n\nnode --trace-event-categories v8,node,node.async_hooks\n
\nAlternatively, trace events may be enabled using the trace_events
module:
const trace_events = require('trace_events');\nconst tracing = trace_events.createTracing({ categories: ['node.perf'] });\ntracing.enable(); // Enable trace event capture for the 'node.perf' category\n\n// do work\n\ntracing.disable(); // Disable trace event capture for the 'node.perf' category\n
\nRunning Node.js with tracing enabled will produce log files that can be opened\nin the chrome://tracing
\ntab of Chrome.
The logging file is by default called node_trace.${rotation}.log
, where\n${rotation}
is an incrementing log-rotation id. The filepath pattern can\nbe specified with --trace-event-file-pattern
that accepts a template\nstring that supports ${rotation}
and ${pid}
:
node --trace-event-categories v8 --trace-event-file-pattern '${pid}-${rotation}.log' server.js\n
\nStarting with Node.js 10.0.0, the tracing system uses the same time source\nas the one used by process.hrtime()
\nhowever the trace-event timestamps are expressed in microseconds,\nunlike process.hrtime()
which returns nanoseconds.
The Tracing
object is used to enable or disable tracing for sets of\ncategories. Instances are created using the trace_events.createTracing()
\nmethod.
When created, the Tracing
object is disabled. Calling the\ntracing.enable()
method adds the categories to the set of enabled trace event\ncategories. Calling tracing.disable()
will remove the categories from the\nset of enabled trace event categories.
A comma-separated list of the trace event categories covered by this\nTracing
object.
Disables this Tracing
object.
Only trace event categories not covered by other enabled Tracing
objects\nand not specified by the --trace-event-categories
flag will be disabled.
const trace_events = require('trace_events');\nconst t1 = trace_events.createTracing({ categories: ['node', 'v8'] });\nconst t2 = trace_events.createTracing({ categories: ['node.perf', 'node'] });\nt1.enable();\nt2.enable();\n\n// Prints 'node,node.perf,v8'\nconsole.log(trace_events.getEnabledCategories());\n\nt2.disable(); // will only disable emission of the 'node.perf' category\n\n// Prints 'node,v8'\nconsole.log(trace_events.getEnabledCategories());\n
",
"type": "module",
"displayName": "`tracing.disable()`"
},
{
"textRaw": "`tracing.enable()`",
"name": "`tracing.enable()`",
"meta": {
"added": [
"v10.0.0"
],
"changes": []
},
"desc": "Enables this Tracing
object for the set of categories covered by the\nTracing
object.
true
only if the Tracing
object has been enabled.options
<Object>
categories
<string[]> An array of trace category names. Values included\nin the array are coerced to a string when possible. An error will be\nthrown if the value cannot be coerced.Creates and returns a Tracing
object for the given set of categories
.
const trace_events = require('trace_events');\nconst categories = ['node.perf', 'node.async_hooks'];\nconst tracing = trace_events.createTracing({ categories });\ntracing.enable();\n// do stuff\ntracing.disable();\n
",
"type": "module",
"displayName": "`trace_events.createTracing(options)`"
},
{
"textRaw": "`trace_events.getEnabledCategories()`",
"name": "`trace_events.getenabledcategories()`",
"meta": {
"added": [
"v10.0.0"
],
"changes": []
},
"desc": "Returns a comma-separated list of all currently-enabled trace event\ncategories. The current set of enabled trace event categories is determined\nby the union of all currently-enabled Tracing
objects and any categories\nenabled using the --trace-event-categories
flag.
Given the file test.js
below, the command\nnode --trace-event-categories node.perf test.js
will print\n'node.async_hooks,node.perf'
to the console.
const trace_events = require('trace_events');\nconst t1 = trace_events.createTracing({ categories: ['node.async_hooks'] });\nconst t2 = trace_events.createTracing({ categories: ['node.perf'] });\nconst t3 = trace_events.createTracing({ categories: ['v8'] });\n\nt1.enable();\nt2.enable();\n\nconsole.log(trace_events.getEnabledCategories());\n
",
"type": "module",
"displayName": "`trace_events.getEnabledCategories()`"
}
],
"type": "module",
"displayName": "The `trace_events` module"
}
],
"type": "module",
"displayName": "Trace Events"
}
]
}