22

✏️ Editing: tracing.json

{
 "type": "module",
 "source": "doc/api/tracing.md",
 "modules": [
 {
 "textRaw": "Trace events",
 "name": "trace_events",
 "introduced_in": "v7.7.0",
 "stability": 1,
 "stabilityText": "Experimental",
 "desc": "Source Code: <a href=\"https://github.com/nodejs/node/blob/v12.22.12/lib/trace_events.js\">lib/trace_events.js</a>\nThe <code>trace_events</code> module provides a mechanism to centralize tracing information\ngenerated by V8, Node.js core, and userspace code.\nTracing can be enabled with the <code>--trace-event-categories</code> command-line flag\nor by using the <code>trace_events</code> module. The <code>--trace-event-categories</code> flag\naccepts a list of comma-separated category names.\nThe available categories are:\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.dns.native</code>: Enables capture of trace data for DNS queries.</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.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>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</ul>\nBy default the <code>node</code>, <code>node.async_hooks</code>, and <code>v8</code> categories are enabled.\n<pre><code class=\"language-bash\">node --trace-event-categories v8,node,node.async_hooks server.js\n</code></pre>\nPrior 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 may 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.\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>\nAlternatively, trace events may be enabled using the <code>trace_events</code> module:\n<pre><code class=\"language-js\">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</code></pre>\nRunning 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.\nThe 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>:\n<pre><code class=\"language-bash\">node --trace-event-categories v8 --trace-event-file-pattern '${pid}-${rotation}.log' server.js\n</code></pre>\nThe 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.\nThe features from this module are not available in <a href=\"worker_threads.html#worker_threads_class_worker\"><code>Worker</code></a> threads.",
 "modules": [
 {
 "textRaw": "The `trace_events` module",
 "name": "the_`trace_events`_module",
 "meta": {
 "added": [
 "v10.0.0"
 ],
 "changes": []
 },
 "modules": [
 {
 "textRaw": "`Tracing` object",
 "name": "`tracing`_object",
 "meta": {
 "added": [
 "v10.0.0"
 ],
 "changes": []
 },
 "desc": "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.\nWhen 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.",
 "properties": [
 {
 "textRaw": "`categories` {string}",
 "type": "string",
 "name": "categories",
 "meta": {
 "added": [
 "v10.0.0"
 ],
 "changes": []
 },
 "desc": "A comma-separated list of the trace event categories covered by this\n<code>Tracing</code> object."
 },
 {
 "textRaw": "`enabled` {boolean} `true` only if the `Tracing` object has been enabled.",
 "type": "boolean",
 "name": "enabled",
 "meta": {
 "added": [
 "v10.0.0"
 ],
 "changes": []
 },
 "desc": "`true` only if the `Tracing` object has been enabled."
 }
 ],
 "methods": [
 {
 "textRaw": "`tracing.disable()`",
 "type": "method",
 "name": "disable",
 "meta": {
 "added": [
 "v10.0.0"
 ],
 "changes": []
 },
 "signatures": [
 {
 "params": []
 }
 ],
 "desc": "Disables this <code>Tracing</code> object.\nOnly trace event categories not covered by other enabled <code>Tracing</code> objects\nand not specified by the <code>--trace-event-categories</code> flag will be disabled.\n<pre><code class=\"language-js\">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</code></pre>"
 },
 {
 "textRaw": "`tracing.enable()`",
 "type": "method",
 "name": "enable",
 "meta": {
 "added": [
 "v10.0.0"
 ],
 "changes": []
 },
 "signatures": [
 {
 "params": []
 }
 ],
 "desc": "Enables this <code>Tracing</code> object for the set of categories covered by the\n<code>Tracing</code> object."
 }
 ],
 "type": "module",
 "displayName": "`Tracing` object"
 }
 ],
 "methods": [
 {
 "textRaw": "`trace_events.createTracing(options)`",
 "type": "method",
 "name": "createTracing",
 "meta": {
 "added": [
 "v10.0.0"
 ],
 "changes": []
 },
 "signatures": [
 {
 "return": {
 "textRaw": "Returns: {Tracing}.",
 "name": "return",
 "type": "Tracing",
 "desc": "."
 },
 "params": [
 {
 "textRaw": "`options` {Object}",
 "name": "options",
 "type": "Object",
 "options": [
 {
 "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.",
 "name": "categories",
 "type": "string[]",
 "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."
 }
 ]
 }
 ]
 }
 ],
 "desc": "Creates and returns a <code>Tracing</code> object for the given set of <code>categories</code>.\n<pre><code class=\"language-js\">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</code></pre>"
 },
 {
 "textRaw": "`trace_events.getEnabledCategories()`",
 "type": "method",
 "name": "getEnabledCategories",
 "meta": {
 "added": [
 "v10.0.0"
 ],
 "changes": []
 },
 "signatures": [
 {
 "return": {
 "textRaw": "Returns: {string}",
 "name": "return",
 "type": "string"
 },
 "params": []
 }
 ],
 "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 <code>Tracing</code> objects and any categories\nenabled using the <code>--trace-event-categories</code> flag.\nGiven 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.\n<pre><code class=\"language-js\">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</code></pre>"
 }
 ],
 "type": "module",
 "displayName": "The `trace_events` module"
 }
 ],
 "type": "module",
 "displayName": "Trace events"
 }
 ]
}

MR SKB