- assert 断言
- async_hooks 异步钩子
- async_hooks/context 异步上下文
- buffer 缓冲区
- C++插件
- C/C++插件(使用Node-API)
- C++嵌入器
- child_process 子进程
- cluster 集群
- CLI 命令行
- console 控制台
- Corepack 核心包
- crypto 加密
- crypto/webcrypto 网络加密
- debugger 调试器
- deprecation 弃用
- dgram 数据报
- diagnostics_channel 诊断通道
- dns 域名服务器
- domain 域
- Error 错误
- events 事件触发器
- fs 文件系统
- global 全局变量
- http 超文本传输协议
- http2 超文本传输协议2.0
- https 安全超文本传输协议
- inspector 检查器
- Intl 国际化
- module 模块
- module/cjs CommonJS模块
- module/esm ECMAScript模块
- module/package 包模块
- net 网络
- os 操作系统
- path 路径
- perf_hooks 性能钩子
- permission 权限
- process 进程
- punycode 域名代码
- querystring 查询字符串
- readline 逐行读取
- repl 交互式解释器
- report 诊断报告
- sea 单个可执行应用程序
- stream 流
- stream/web 网络流
- string_decoder 字符串解码器
- test 测试
- timers 定时器
- tls 安全传输层
- trace_events 跟踪事件
- tty 终端
- url 网址
- util 实用工具
- v8 引擎
- vm 虚拟机
- wasi 网络汇编系统接口
- worker_threads 工作线程
- zlib 压缩
Node.js v20.2.0 文档
- Node.js v20.2.0
- ► 目录
-
►
导航
- assert 断言
- async_hooks 异步钩子
- async_hooks/context 异步上下文
- buffer 缓冲区
- C++插件
- C/C++插件(使用Node-API)
- C++嵌入器
- child_process 子进程
- cluster 集群
- CLI 命令行
- console 控制台
- Corepack 核心包
- crypto 加密
- crypto/webcrypto 网络加密
- debugger 调试器
- deprecation 弃用
- dgram 数据报
- diagnostics_channel 诊断通道
- dns 域名服务器
- domain 域
- Error 错误
- events 事件触发器
- fs 文件系统
- global 全局变量
- http 超文本传输协议
- http2 超文本传输协议2.0
- https 安全超文本传输协议
- inspector 检查器
- Intl 国际化
- module 模块
- module/cjs CommonJS模块
- module/esm ECMAScript模块
- module/package 包模块
- net 网络
- os 操作系统
- path 路径
- perf_hooks 性能钩子
- permission 权限
- process 进程
- punycode 域名代码
- querystring 查询字符串
- readline 逐行读取
- repl 交互式解释器
- report 诊断报告
- sea 单个可执行应用程序
- stream 流
- stream/web 网络流
- string_decoder 字符串解码器
- test 测试
- timers 定时器
- tls 安全传输层
- trace_events 跟踪事件
- tty 终端
- url 网址
- util 实用工具
- v8 引擎
- vm 虚拟机
- wasi 网络汇编系统接口
- worker_threads 工作线程
- zlib 压缩
- ► 其他版本
- 云服务器
目录
跟踪事件#
源代码: 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
模块#
Tracing
对象#
Tracing
对象用于启用或禁用类别集的跟踪。 使用 trace_events.createTracing()
方法创建实例。
创建时,Tracing
对象被禁用。 调用 tracing.enable()
方法将类别添加到启用的跟踪事件类别集中。 调用 tracing.disable()
将从启用的跟踪事件类别集中删除类别。
tracing.categories
#
此 Tracing
对象涵盖的跟踪事件类别的逗号分隔列表。
tracing.disable()
#
禁用此 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()
#
为 Tracing
对象涵盖的类别集启用此 Tracing
对象。
tracing.enabled
#
- <boolean>
true
仅当Tracing
对象已启用时。
trace_events.createTracing(options)
#
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()
#
- 返回: <string>
返回所有当前启用的跟踪事件类别的逗号分隔列表。 当前启用的跟踪事件类别集由所有当前启用的 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();