Node.js v20.10.0 文档

跟踪事件#

源代码: 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: 启用 性能接口 测量的捕获。
  • node.perf.usertiming: 仅允许捕获 Performance API User Timing 度量和标记。
  • node.perf.timerify: 启用仅捕获性能 API timerify 测量。
• node.promises.rejections: 启用跟踪数据的捕获，跟踪未处理的 Promise 拒绝和处理后拒绝的数量。
• node.vm.script: 启用 node:vm 模块的 runInNewContext()、runInContext() 和 runInThisContext() 方法的跟踪数据捕获。
• v8: V8 事件与 GC、编译和执行相关。
• node.http: 启用对 http 请求/响应的跟踪数据的捕获。

默认情况下，启用 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:

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 拷贝

在启用跟踪的情况下运行 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.

const trace_events = require('node:trace_events');
const t1 = trace_events.createTracing({ categories: ['node', 'v8'] });
const t2 = trace_events.createTracing({ categories: ['node.perf', 'node'] });
t1.enable();
t2.enable();

// Prints 'node,node.perf,v8'
console.log(trace_events.getEnabledCategories());

t2.disable(); // Will only disable emission of the 'node.perf' category

// Prints 'node,v8'
console.log(trace_events.getEnabledCategories()); 拷贝

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(); 拷贝

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()); 拷贝

'use strict';

const { Session } = require('inspector');
const session = new Session();
session.connect();

function post(message, data) {
  return new Promise((resolve, reject) => {
    session.post(message, data, (err, result) => {
      if (err)
        reject(new Error(JSON.stringify(err)));
      else
        resolve(result);
    });
  });
}

async function collect() {
  const data = [];
  session.on('NodeTracing.dataCollected', (chunk) => data.push(chunk));
  session.on('NodeTracing.tracingComplete', () => {
    // done
  });
  const traceConfig = { includedCategories: ['v8'] };
  await post('NodeTracing.start', { traceConfig });
  // do something
  setTimeout(() => {
    post('NodeTracing.stop').then(() => {
      session.disconnect();
      console.log(data);
    });
  }, 1000);
}

collect(); 拷贝