跟踪事件

【Trace events】

稳定性： 1 - 实验性

源代码: 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.async_hooks：启用捕获详细的 async_hooks 跟踪数据。async_hooks 事件具有唯一的 asyncId 和特殊的 triggerId triggerAsyncId 属性。
  • node.bootstrap：启用捕获 Node.js 启动里程碑。
  • node.console：启用捕获 console.time() 和 console.count() 的输出。
  • node.threadpoolwork.sync：启用对线程池同步操作的跟踪数据捕获，例如 blob、zlib、crypto 和 node_api。
  • node.threadpoolwork.async：启用对线程池异步操作的追踪数据捕获，例如 blob、zlib、crypto 和 node_api。
  • node.dns.native：启用 DNS 查询的跟踪数据捕获。
  • node.net.native：启用网络跟踪数据的捕获。
  • node.environment：启用捕获 Node.js 环境里程碑。
  • node.fs.sync：启用对文件系统同步方法的跟踪数据捕获。
  • node.fs_dir.sync：启用对文件系统同步目录方法的跟踪数据捕获。
  • node.fs.async：启用对文件系统异步方法的跟踪数据捕获。
  • node.fs_dir.async：启用对文件系统异步目录方法的跟踪数据捕获。
  • node.perf：启用 性能 API 测量的捕获。
    • node.perf.usertiming：仅启用捕获性能 API 用户时间的度量和标记。
    • node.perf.timerify：只允许捕获 Performance API timerify 的测量值。
  • node.promises.rejections：启用捕获跟踪未处理的 Promise 拒绝数量以及之后处理的拒绝的跟踪数据。
  • node.vm.script：启用对 node:vm 模块的 runInNewContext()、runInContext() 和 runInThisContext() 方法的跟踪数据捕获。
  • v8：V8 事件与垃圾回收、编译和执行相关。
  • node.http：启用对 HTTP 请求/响应的跟踪数据捕获。
  • node.module_timer：启用对 CJS 模块加载的跟踪数据捕获。

默认情况下，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() 相同的时间源。 然而，trace-event 的时间戳是以微秒表示的，而 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.】