Node.js v20.2.0 文档

目录

跟踪事件#

稳定性: 1 - 实验

源代码: lib/trace_events.js

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

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

可用的类别是：

  • 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 类别。

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

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

node --trace-events-enabled

# is equivalent to

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

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

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 选项卡中打开的日志文件。

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

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

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

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() 不同。

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

node:trace_events 模块#

新增于: v10.0.0

Tracing 对象#

新增于: v10.0.0

Tracing 对象用于启用或禁用类别集的跟踪。 使用 trace_events.createTracing() 方法创建实例。

创建时，Tracing 对象被禁用。 调用 tracing.enable() 方法将类别添加到启用的跟踪事件类别集中。 调用 tracing.disable() 将从启用的跟踪事件类别集中删除类别。

tracing.categories#
新增于: v10.0.0

此 Tracing 对象涵盖的跟踪事件类别的逗号分隔列表。

tracing.disable()#
新增于: v10.0.0

禁用此 Tracing 对象。

只有未被其他启用的 Tracing 对象涵盖且未由 --trace-event-categories 标志指定的跟踪事件类别将被禁用。

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

tracing.enable()#
新增于: v10.0.0

为 Tracing 对象涵盖的类别集启用此 Tracing 对象。

tracing.enabled#
新增于: v10.0.0
  • <boolean> true 仅当 Tracing 对象已启用时。

trace_events.createTracing(options)#

新增于: v10.0.0
  • options <Object>
    • categories <string[]> 一组跟踪类别名称。 在可能的情况下，数组中包含的值会被强制转换为字符串。 如果无法强制转换该值，则会抛出错误。
  • 返回： <Tracing>.

为给定的 categories 集合创建并返回 Tracing 对象。

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

trace_events.getEnabledCategories()#

新增于: v10.0.0

返回所有当前启用的跟踪事件类别的逗号分隔列表。 当前启用的跟踪事件类别集由所有当前启用的 Tracing 对象和使用 --trace-event-categories 标志启用的任何类别的联合确定。

给定下面的文件 test.js，命令 node --trace-event-categories node.perf test.js 会将 'node.async_hooks,node.perf' 打印到控制台。

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