跟踪事件

¥Trace events

稳定性: 1 - 实验性的

¥Stability: 1 - Experimental

源代码: lib/trace_events.js

node:trace_events 模块提供了一种机制来集中 V8、Node.js 核心和用户空间代码生成的跟踪信息。

¥The node:trace_events module provides a mechanism to centralize tracing information generated by V8, Node.js core, and userspace code.

可以使用 --trace-event-categories 命令行标志或使用 node:trace_events 模块启用跟踪。--trace-event-categories 标志接受以逗号分隔的类别名称列表。

¥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：一个空的占位符。

    ¥node: An empty placeholder.

  • node.async_hooks：启用详细的 async_hooks 跟踪数据的捕获。async_hooks 事件具有独特的 asyncId 和特殊的 triggerId triggerAsyncId 属性。

    ¥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：启用 Node.js 引导程序里程碑的捕获。

    ¥node.bootstrap: Enables capture of Node.js bootstrap milestones.

  • node.console：启用 console.time() 和 console.count() 输出的捕获。

    ¥node.console: Enables capture of console.time() and console.count() output.

  • node.threadpoolwork.sync：启用线程池同步操作的跟踪数据捕获，例如 blob、zlib、crypto 和 node_api。

    ¥node.threadpoolwork.sync: Enables capture of trace data for threadpool synchronous operations, such as blob, zlib, crypto and node_api.

  • node.threadpoolwork.async：启用线程池异步操作的跟踪数据捕获，例如 blob、zlib、crypto 和 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：启用 DNS 查询的跟踪数据捕获。

    ¥node.dns.native: Enables capture of trace data for DNS queries.

  • node.net.native：启用网络跟踪数据的捕获。

    ¥node.net.native: Enables capture of trace data for network.

  • node.environment：启用 Node.js 环境里程碑的捕获。

    ¥node.environment: Enables capture of Node.js Environment milestones.

  • node.fs.sync：启用文件系统同步方法的跟踪数据捕获。

    ¥node.fs.sync: Enables capture of trace data for file system sync methods.

  • node.fs_dir.sync：启用文件系统同步目录方法的跟踪数据捕获。

    ¥node.fs_dir.sync: Enables capture of trace data for file system sync directory methods.

  • node.fs.async：启用文件系统异步方法的跟踪数据捕获。

    ¥node.fs.async: Enables capture of trace data for file system async methods.

  • node.fs_dir.async：启用文件系统异步目录方法的跟踪数据捕获。

    ¥node.fs_dir.async: Enables capture of trace data for file system async directory methods.

  • node.perf：启用 性能接口 测量的捕获。

    ¥node.perf: Enables capture of Performance API measurements.

    • node.perf.usertiming：仅允许捕获 Performance API User Timing 度量和标记。

      ¥node.perf.usertiming: Enables capture of only Performance API User Timing measures and marks.

    • node.perf.timerify：启用仅捕获性能 API timerify 测量。

      ¥node.perf.timerify: Enables capture of only Performance API timerify measurements.

  • node.promises.rejections：启用跟踪数据的捕获，跟踪未处理的 Promise 拒绝和处理后拒绝的数量。

    ¥node.promises.rejections: Enables capture of trace data tracking the number of unhandled Promise rejections and handled-after-rejections.

  • node.vm.script：启用 node:vm 模块的 runInNewContext()、runInContext() 和 runInThisContext() 方法的跟踪数据捕获。

    ¥node.vm.script: Enables capture of trace data for the node:vm module's runInNewContext(), runInContext(), and runInThisContext() methods.

  • v8：V8 事件与 GC、编译和执行相关。

    ¥v8: The V8 events are GC, compiling, and execution related.

  • node.http：启用对 http 请求/响应的跟踪数据的捕获。

    ¥node.http: Enables capture of trace data for http request / response.

  • node.module_timer：启用跟踪数据捕获以进行 CJS 模块加载。

    ¥node.module_timer: Enables capture of trace data for CJS Module loading.

默认情况下，启用 node、node.async_hooks 和 v8 类别。

¥By default the node, node.async_hooks, and v8 categories are enabled.

node --trace-event-categories v8,node,node.async_hooks server.js

早期版本的 Node.js 需要使用 --trace-events-enabled 标志来启用跟踪事件。此要求已被删除。但是，--trace-events-enabled 标志仍可使用，默认情况下将启用 node、node.async_hooks 和 v8 跟踪事件类别。

¥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.

node --trace-events-enabled

# is equivalent to

node --trace-event-categories v8,node,node.async_hooks

或者，可以使用 node:trace_events 模块启用跟踪事件：

¥Alternatively, trace events may be enabled using the node:trace_events module:

import { createTracing } from 'node:trace_events';
const tracing = 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' categoryconst { createTracing } = require('node:trace_events');
const tracing = 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

在启用跟踪的情况下运行 Node.js 将生成可以在 Chrome 的 chrome://tracing 选项卡中打开的日志文件。

¥Running Node.js with tracing enabled will produce log files that can be opened in the chrome://tracing tab of Chrome.

日志文件默认名为 node_trace.${rotation}.log，其中 ${rotation} 是一个递增的日志循环 ID。文件路径模式可以用 --trace-event-file-pattern 指定，它接受支持 ${rotation} 和 ${pid} 的模板字符串：

¥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}:

node --trace-event-categories v8 --trace-event-file-pattern '${pid}-${rotation}.log' server.js

为保证在 SIGINT、SIGTERM 或 SIGBREAK 等信号事件后正确生成日志文件，请确保代码中有适当的处理程序，例如：

¥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:

process.on('SIGINT', function onSigint() {
  console.info('Received SIGINT.');
  process.exit(130);  // Or applicable exit code depending on OS and signal
});

跟踪系统使用与 process.hrtime() 使用的时间源相同的时间源。然而，跟踪事件时间戳以微秒表示，与返回纳秒的 process.hrtime() 不同。

¥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.

此模块的功能在 Worker 线程中不可用。

¥The features from this module are not available in Worker threads.