/** | |
* The `node:trace_events` module 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 `node: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.threadpoolwork.sync`: Enables capture of trace data for threadpool | |
* synchronous operations, such as `blob`, `zlib`, `crypto` and `node_api`. | |
* * `node.threadpoolwork.async`: Enables capture of trace data for threadpool | |
* asynchronous operations, such as `blob`, `zlib`, `crypto` and `node_api`. | |
* * `node.dns.native`: Enables capture of trace data for DNS queries. | |
* * `node.net.native`: Enables capture of trace data for network. | |
* * `node.environment`: Enables capture of Node.js Environment milestones. | |
* * `node.fs.sync`: Enables capture of trace data for file system sync methods. | |
* * `node.fs_dir.sync`: Enables capture of trace data for file system sync | |
* directory methods. | |
* * `node.fs.async`: Enables capture of trace data for file system async methods. | |
* * `node.fs_dir.async`: Enables capture of trace data for file system async | |
* directory 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 `node:vm` module's`runInNewContext()`, `runInContext()`, and `runInThisContext()` methods. | |
* * `v8`: The `V8` events are GC, compiling, and execution related. | |
* * `node.http`: Enables capture of trace data for http request / response. | |
* | |
* By default the `node`, `node.async_hooks`, and `v8` categories are enabled. | |
* | |
* ```bash | |
* 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. | |
* | |
* ```bash | |
* node --trace-events-enabled | |
* | |
* # is equivalent to | |
* | |
* node --trace-event-categories v8,node,node.async_hooks | |
* ``` | |
* | |
* Alternatively, trace events may be enabled using the `node:trace_events` module: | |
* | |
* ```js | |
* const trace_events = require('node: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}`: | |
* | |
* ```bash | |
* node --trace-event-categories v8 --trace-event-file-pattern '${pid}-${rotation}.log' server.js | |
* ``` | |
* | |
* To guarantee that the log file is properly generated after signal events like`SIGINT`, `SIGTERM`, or `SIGBREAK`, make sure to have the appropriate handlers | |
* in your code, such as: | |
* | |
* ```js | |
* process.on('SIGINT', function onSigint() { | |
* console.info('Received SIGINT.'); | |
* process.exit(130); // Or applicable exit code depending on OS and signal | |
* }); | |
* ``` | |
* | |
* 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. | |
* @experimental | |
* @see [source](https://github.com/nodejs/node/blob/v20.2.0/lib/trace_events.js) | |
*/ | |
declare module "trace_events" { | |
/** | |
* 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. | |
*/ | |
interface Tracing { | |
/** | |
* A comma-separated list of the trace event categories covered by this | |
* `Tracing` object. | |
*/ | |
readonly categories: string; | |
/** | |
* 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. | |
*/ | |
disable(): void; | |
/** | |
* Enables this `Tracing` object for the set of categories covered by | |
* the `Tracing` object. | |
*/ | |
enable(): void; | |
/** | |
* `true` only if the `Tracing` object has been enabled. | |
*/ | |
readonly enabled: boolean; | |
} | |
interface CreateTracingOptions { | |
/** | |
* 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. | |
*/ | |
categories: string[]; | |
} | |
/** | |
* Creates and returns a `Tracing` object for the given set of `categories`. | |
* | |
* ```js | |
* const trace_events = require('node:trace_events'); | |
* const categories = ['node.perf', 'node.async_hooks']; | |
* const tracing = trace_events.createTracing({ categories }); | |
* tracing.enable(); | |
* // do stuff | |
* tracing.disable(); | |
* ``` | |
* @since v10.0.0 | |
* @return . | |
*/ | |
function createTracing(options: CreateTracingOptions): Tracing; | |
/** | |
* 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('node: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()); | |
* ``` | |
* @since v10.0.0 | |
*/ | |
function getEnabledCategories(): string | undefined; | |
} | |
declare module "node:trace_events" { | |
export * from "trace_events"; | |
} | |