Node.js v22.3.0 文档


跟踪事件#

¥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:启用线程池同步操作的跟踪数据捕获,例如 blobzlibcryptonode_api

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

  • node.threadpoolwork.async:启用线程池异步操作的跟踪数据捕获,例如 blobzlibcryptonode_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.

  • v8V8 事件与 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.

默认情况下,启用 nodenode.async_hooksv8 类别。

¥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 标志仍可使用,默认情况下将启用 nodenode.async_hooksv8 跟踪事件类别。

¥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 

为保证在 SIGINTSIGTERMSIGBREAK 等信号事件后正确生成日志文件,请确保代码中有适当的处理程序,例如:

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

node:trace_events 模块#

¥The node:trace_events module

Tracing 对象#

¥Tracing object

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

¥The Tracing object is used to enable or disable tracing for sets of categories. Instances are created using the trace_events.createTracing() method.

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

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

tracing.categories#

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

¥A comma-separated list of the trace event categories covered by this Tracing object.

tracing.disable()#

禁用此 Tracing 对象。

¥Disables this Tracing object.

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

¥Only trace event categories not covered by other enabled Tracing objects and not specified by the --trace-event-categories flag will be disabled.

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

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

¥Enables this Tracing object for the set of categories covered by the Tracing object.

tracing.enabled#
  • <boolean> 仅当 Tracing 对象已启用时才为 true

    ¥<boolean> true only if the Tracing object has been enabled.

trace_events.createTracing(options)#

  • options <Object>

    • categories <string[]> 一组跟踪类别名称。在可能的情况下,数组中包含的值会被强制转换为字符串。如果无法强制转换该值,则会抛出错误。

      ¥categories <string[]> 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.

  • 返回:<Tracing>

    ¥Returns: <Tracing>.

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

¥Creates and returns a Tracing object for the given set of categories.

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

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

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

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

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

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

示例#

¥Examples

通过检查器收集跟踪事件数据#

¥Collect trace events data by inspector

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