Node.js v20.20.6 文档

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

• <string>

此 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.】

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

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

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

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

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

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

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

tracing.enable()#>

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

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

tracing.enabled#>

• <boolean> 仅当 Tracing 对象已启用时为 true。

trace_events.createTracing(options)#>

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

为给定的 categories 创建并返回一个 Tracing 对象。

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

import { createTracing } from 'node:trace_events';
const categories = ['node.perf', 'node.async_hooks'];
const tracing = createTracing({ categories });
tracing.enable();
// do stuff
tracing.disable();const { createTracing } = require('node:trace_events');
const categories = ['node.perf', 'node.async_hooks'];
const tracing = createTracing({ categories });
tracing.enable();
// do stuff
tracing.disable();拷贝

trace_events.getEnabledCategories()#>

• 返回：<string>

返回所有当前启用的跟踪事件类别的逗号分隔列表。当前启用的跟踪事件类别集合由所有当前启用的 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.】

import { createTracing, getEnabledCategories } from 'node:trace_events';
const t1 = createTracing({ categories: ['node.async_hooks'] });
const t2 = createTracing({ categories: ['node.perf'] });
const t3 = createTracing({ categories: ['v8'] });

t1.enable();
t2.enable();

console.log(getEnabledCategories());const { createTracing, getEnabledCategories } = require('node:trace_events');
const t1 = createTracing({ categories: ['node.async_hooks'] });
const t2 = createTracing({ categories: ['node.perf'] });
const t3 = createTracing({ categories: ['v8'] });

t1.enable();
t2.enable();

console.log(getEnabledCategories());拷贝

示例#>

【Examples】

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

【Collect trace events data by inspector】

import { Session } from 'node: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();'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();拷贝