1{ 2 "type": "module", 3 "source": "doc/api/tracing.md", 4 "modules": [ 5 { 6 "textRaw": "Trace events", 7 "name": "trace_events", 8 "introduced_in": "v7.7.0", 9 "stability": 1, 10 "stabilityText": "Experimental", 11 "desc": "<p><strong>Source Code:</strong> <a href=\"https://github.com/nodejs/node/blob/v18.18.2/lib/trace_events.js\">lib/trace_events.js</a></p>\n<p>The <code>node:trace_events</code> module provides a mechanism to centralize tracing\ninformation generated by V8, Node.js core, and userspace code.</p>\n<p>Tracing can be enabled with the <code>--trace-event-categories</code> command-line flag\nor by using the <code>node:trace_events</code> module. The <code>--trace-event-categories</code> flag\naccepts a list of comma-separated category names.</p>\n<p>The available categories are:</p>\n<ul>\n<li><code>node</code>: An empty placeholder.</li>\n<li><code>node.async_hooks</code>: Enables capture of detailed <a href=\"async_hooks.html\"><code>async_hooks</code></a> trace data.\nThe <a href=\"async_hooks.html\"><code>async_hooks</code></a> events have a unique <code>asyncId</code> and a special <code>triggerId</code>\n<code>triggerAsyncId</code> property.</li>\n<li><code>node.bootstrap</code>: Enables capture of Node.js bootstrap milestones.</li>\n<li><code>node.console</code>: Enables capture of <code>console.time()</code> and <code>console.count()</code>\noutput.</li>\n<li><code>node.threadpoolwork.sync</code>: Enables capture of trace data for threadpool\nsynchronous operations, such as <code>blob</code>, <code>zlib</code>, <code>crypto</code> and <code>node_api</code>.</li>\n<li><code>node.threadpoolwork.async</code>: Enables capture of trace data for threadpool\nasynchronous operations, such as <code>blob</code>, <code>zlib</code>, <code>crypto</code> and <code>node_api</code>.</li>\n<li><code>node.dns.native</code>: Enables capture of trace data for DNS queries.</li>\n<li><code>node.net.native</code>: Enables capture of trace data for network.</li>\n<li><code>node.environment</code>: Enables capture of Node.js Environment milestones.</li>\n<li><code>node.fs.sync</code>: Enables capture of trace data for file system sync methods.</li>\n<li><code>node.fs_dir.sync</code>: Enables capture of trace data for file system sync\ndirectory methods.</li>\n<li><code>node.fs.async</code>: Enables capture of trace data for file system async methods.</li>\n<li><code>node.fs_dir.async</code>: Enables capture of trace data for file system async\ndirectory methods.</li>\n<li><code>node.perf</code>: Enables capture of <a href=\"perf_hooks.html\">Performance API</a> measurements.\n<ul>\n<li><code>node.perf.usertiming</code>: Enables capture of only Performance API User Timing\nmeasures and marks.</li>\n<li><code>node.perf.timerify</code>: Enables capture of only Performance API timerify\nmeasurements.</li>\n</ul>\n</li>\n<li><code>node.promises.rejections</code>: Enables capture of trace data tracking the number\nof unhandled Promise rejections and handled-after-rejections.</li>\n<li><code>node.vm.script</code>: Enables capture of trace data for the <code>node:vm</code> module's\n<code>runInNewContext()</code>, <code>runInContext()</code>, and <code>runInThisContext()</code> methods.</li>\n<li><code>v8</code>: The <a href=\"v8.html\">V8</a> events are GC, compiling, and execution related.</li>\n<li><code>node.http</code>: Enables capture of trace data for http request / response.</li>\n</ul>\n<p>By default the <code>node</code>, <code>node.async_hooks</code>, and <code>v8</code> categories are enabled.</p>\n<pre><code class=\"language-bash\">node --trace-event-categories v8,node,node.async_hooks server.js\n</code></pre>\n<p>Prior versions of Node.js required the use of the <code>--trace-events-enabled</code>\nflag to enable trace events. This requirement has been removed. However, the\n<code>--trace-events-enabled</code> flag <em>may</em> still be used and will enable the\n<code>node</code>, <code>node.async_hooks</code>, and <code>v8</code> trace event categories by default.</p>\n<pre><code class=\"language-bash\">node --trace-events-enabled\n\n# is equivalent to\n\nnode --trace-event-categories v8,node,node.async_hooks\n</code></pre>\n<p>Alternatively, trace events may be enabled using the <code>node:trace_events</code> module:</p>\n<pre><code class=\"language-js\">const trace_events = require('node: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</code></pre>\n<p>Running Node.js with tracing enabled will produce log files that can be opened\nin the <a href=\"https://www.chromium.org/developers/how-tos/trace-event-profiling-tool\"><code>chrome://tracing</code></a>\ntab of Chrome.</p>\n<p>The logging file is by default called <code>node_trace.${rotation}.log</code>, where\n<code>${rotation}</code> is an incrementing log-rotation id. The filepath pattern can\nbe specified with <code>--trace-event-file-pattern</code> that accepts a template\nstring that supports <code>${rotation}</code> and <code>${pid}</code>:</p>\n<pre><code class=\"language-bash\">node --trace-event-categories v8 --trace-event-file-pattern '${pid}-${rotation}.log' server.js\n</code></pre>\n<p>To guarantee that the log file is properly generated after signal events like\n<code>SIGINT</code>, <code>SIGTERM</code>, or <code>SIGBREAK</code>, make sure to have the appropriate handlers\nin your code, such as:</p>\n<pre><code class=\"language-js\">process.on('SIGINT', function onSigint() {\n console.info('Received SIGINT.');\n process.exit(130); // Or applicable exit code depending on OS and signal\n});\n</code></pre>\n<p>The tracing system uses the same time source\nas the one used by <code>process.hrtime()</code>.\nHowever the trace-event timestamps are expressed in microseconds,\nunlike <code>process.hrtime()</code> which returns nanoseconds.</p>\n<p>The features from this module are not available in <a href=\"worker_threads.html#class-worker\"><code>Worker</code></a> threads.</p>", 12 "modules": [ 13 { 14 "textRaw": "The `node:trace_events` module", 15 "name": "the_`node:trace_events`_module", 16 "meta": { 17 "added": [ 18 "v10.0.0" 19 ], 20 "changes": [] 21 }, 22 "modules": [ 23 { 24 "textRaw": "`Tracing` object", 25 "name": "`tracing`_object", 26 "meta": { 27 "added": [ 28 "v10.0.0" 29 ], 30 "changes": [] 31 }, 32 "desc": "<p>The <code>Tracing</code> object is used to enable or disable tracing for sets of\ncategories. Instances are created using the <code>trace_events.createTracing()</code>\nmethod.</p>\n<p>When created, the <code>Tracing</code> object is disabled. Calling the\n<code>tracing.enable()</code> method adds the categories to the set of enabled trace event\ncategories. Calling <code>tracing.disable()</code> will remove the categories from the\nset of enabled trace event categories.</p>", 33 "properties": [ 34 { 35 "textRaw": "`categories` {string}", 36 "type": "string", 37 "name": "categories", 38 "meta": { 39 "added": [ 40 "v10.0.0" 41 ], 42 "changes": [] 43 }, 44 "desc": "<p>A comma-separated list of the trace event categories covered by this\n<code>Tracing</code> object.</p>" 45 }, 46 { 47 "textRaw": "`enabled` {boolean} `true` only if the `Tracing` object has been enabled.", 48 "type": "boolean", 49 "name": "enabled", 50 "meta": { 51 "added": [ 52 "v10.0.0" 53 ], 54 "changes": [] 55 }, 56 "desc": "`true` only if the `Tracing` object has been enabled." 57 } 58 ], 59 "methods": [ 60 { 61 "textRaw": "`tracing.disable()`", 62 "type": "method", 63 "name": "disable", 64 "meta": { 65 "added": [ 66 "v10.0.0" 67 ], 68 "changes": [] 69 }, 70 "signatures": [ 71 { 72 "params": [] 73 } 74 ], 75 "desc": "<p>Disables this <code>Tracing</code> object.</p>\n<p>Only trace event categories <em>not</em> covered by other enabled <code>Tracing</code> objects\nand <em>not</em> specified by the <code>--trace-event-categories</code> flag will be disabled.</p>\n<pre><code class=\"language-js\">const trace_events = require('node: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</code></pre>" 76 }, 77 { 78 "textRaw": "`tracing.enable()`", 79 "type": "method", 80 "name": "enable", 81 "meta": { 82 "added": [ 83 "v10.0.0" 84 ], 85 "changes": [] 86 }, 87 "signatures": [ 88 { 89 "params": [] 90 } 91 ], 92 "desc": "<p>Enables this <code>Tracing</code> object for the set of categories covered by the\n<code>Tracing</code> object.</p>" 93 } 94 ], 95 "type": "module", 96 "displayName": "`Tracing` object" 97 }, 98 { 99 "textRaw": "Collect trace events data by inspector", 100 "name": "collect_trace_events_data_by_inspector", 101 "desc": "<pre><code class=\"language-js\">'use strict';\n\nconst { Session } = require('inspector');\nconst session = new Session();\nsession.connect();\n\nfunction post(message, data) {\n return new Promise((resolve, reject) => {\n session.post(message, data, (err, result) => {\n if (err)\n reject(new Error(JSON.stringify(err)));\n else\n resolve(result);\n });\n });\n}\n\nasync function collect() {\n const data = [];\n session.on('NodeTracing.dataCollected', (chunk) => data.push(chunk));\n session.on('NodeTracing.tracingComplete', () => {\n // done\n });\n const traceConfig = { includedCategories: ['v8'] };\n await post('NodeTracing.start', { traceConfig });\n // do something\n setTimeout(() => {\n post('NodeTracing.stop').then(() => {\n session.disconnect();\n console.log(data);\n });\n }, 1000);\n}\n\ncollect();\n</code></pre>", 102 "type": "module", 103 "displayName": "Collect trace events data by inspector" 104 } 105 ], 106 "methods": [ 107 { 108 "textRaw": "`trace_events.createTracing(options)`", 109 "type": "method", 110 "name": "createTracing", 111 "meta": { 112 "added": [ 113 "v10.0.0" 114 ], 115 "changes": [] 116 }, 117 "signatures": [ 118 { 119 "return": { 120 "textRaw": "Returns: {Tracing}.", 121 "name": "return", 122 "type": "Tracing", 123 "desc": "." 124 }, 125 "params": [ 126 { 127 "textRaw": "`options` {Object}", 128 "name": "options", 129 "type": "Object", 130 "options": [ 131 { 132 "textRaw": "`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.", 133 "name": "categories", 134 "type": "string\\[]", 135 "desc": "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." 136 } 137 ] 138 } 139 ] 140 } 141 ], 142 "desc": "<p>Creates and returns a <code>Tracing</code> object for the given set of <code>categories</code>.</p>\n<pre><code class=\"language-js\">const trace_events = require('node:trace_events');\nconst categories = ['node.perf', 'node.async_hooks'];\nconst tracing = trace_events.createTracing({ categories });\ntracing.enable();\n// do stuff\ntracing.disable();\n</code></pre>" 143 }, 144 { 145 "textRaw": "`trace_events.getEnabledCategories()`", 146 "type": "method", 147 "name": "getEnabledCategories", 148 "meta": { 149 "added": [ 150 "v10.0.0" 151 ], 152 "changes": [] 153 }, 154 "signatures": [ 155 { 156 "return": { 157 "textRaw": "Returns: {string}", 158 "name": "return", 159 "type": "string" 160 }, 161 "params": [] 162 } 163 ], 164 "desc": "<p>Returns a comma-separated list of all currently-enabled trace event\ncategories. The current set of enabled trace event categories is determined\nby the <em>union</em> of all currently-enabled <code>Tracing</code> objects and any categories\nenabled using the <code>--trace-event-categories</code> flag.</p>\n<p>Given the file <code>test.js</code> below, the command\n<code>node --trace-event-categories node.perf test.js</code> will print\n<code>'node.async_hooks,node.perf'</code> to the console.</p>\n<pre><code class=\"language-js\">const trace_events = require('node: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</code></pre>\n<h2>Examples</h2>" 165 } 166 ], 167 "type": "module", 168 "displayName": "The `node:trace_events` module" 169 } 170 ], 171 "type": "module", 172 "displayName": "Trace events" 173 } 174 ] 175}