Node.js v26.0.0 文档

诊断通道 (Diagnostics Channel)#

node:diagnostics_channel 模块提供了一个 API，用于创建命名通道，以便为诊断目的报告任意消息数据。

它可以通过以下方式访问

import diagnostics_channel from 'node:diagnostics_channel';
const diagnostics_channel = require('node:diagnostics_channel');
copy

其目的是让想要报告诊断消息的模块编写者创建一个或多个顶级通道来报告消息。通道也可以在运行时获取，但由于这样做会产生额外的开销，因此不建议这样做。为了方便起见，通道可以被导出，但只要名称已知，它就可以在任何地方被获取。

如果您打算让您的模块为他人生成诊断数据，建议您包含所使用的命名通道的文档，以及消息数据的格式。通道名称通常应包含模块名称，以避免与来自其他模块的数据冲突。

公共 API#

概览#

以下是公共 API 的简单概览。

import diagnostics_channel from 'node:diagnostics_channel';

// Get a reusable channel object
const channel = diagnostics_channel.channel('my-channel');

function onMessage(message, name) {
  // Received data
}

// Subscribe to the channel
diagnostics_channel.subscribe('my-channel', onMessage);

// Check if the channel has an active subscriber
if (channel.hasSubscribers) {
  // Publish data to the channel
  channel.publish({
    some: 'data',
  });
}

// Unsubscribe from the channel
diagnostics_channel.unsubscribe('my-channel', onMessage);
const diagnostics_channel = require('node:diagnostics_channel');

// Get a reusable channel object
const channel = diagnostics_channel.channel('my-channel');

function onMessage(message, name) {
  // Received data
}

// Subscribe to the channel
diagnostics_channel.subscribe('my-channel', onMessage);

// Check if the channel has an active subscriber
if (channel.hasSubscribers) {
  // Publish data to the channel
  channel.publish({
    some: 'data',
  });
}

// Unsubscribe from the channel
diagnostics_channel.unsubscribe('my-channel', onMessage);
copy

diagnostics_channel.hasSubscribers(name)#

• name <string> | <symbol> 通道名称
• 返回: <boolean> 是否有活动的订阅者

检查命名通道是否有活动的订阅者。如果您想要发送的消息准备起来可能很昂贵，这很有用。

此 API 是可选的，但在尝试从对性能高度敏感的代码发布消息时很有帮助。

import diagnostics_channel from 'node:diagnostics_channel';

if (diagnostics_channel.hasSubscribers('my-channel')) {
  // There are subscribers, prepare and publish message
}
const diagnostics_channel = require('node:diagnostics_channel');

if (diagnostics_channel.hasSubscribers('my-channel')) {
  // There are subscribers, prepare and publish message
}
copy

diagnostics_channel.channel(name)#

• name <string> | <symbol> 通道名称
• 返回: <Channel> 命名通道对象

这是任何想要发布到命名通道的人的主要入口点。它生成一个通道对象，该对象经过优化，可尽可能减少发布时的开销。

import diagnostics_channel from 'node:diagnostics_channel';

const channel = diagnostics_channel.channel('my-channel');
const diagnostics_channel = require('node:diagnostics_channel');

const channel = diagnostics_channel.channel('my-channel');
copy

diagnostics_channel.subscribe(name, onMessage)#

• name <string> | <symbol> 通道名称
• onMessage <Function> 接收通道消息的处理器
  • message <any> 消息数据
  • name <string> | <symbol> 通道名称

注册一个消息处理器以订阅此通道。每当向通道发布消息时，此消息处理器都将同步运行。在消息处理器中抛出的任何错误都会触发 'uncaughtException'。

import diagnostics_channel from 'node:diagnostics_channel';

diagnostics_channel.subscribe('my-channel', (message, name) => {
  // Received data
});
const diagnostics_channel = require('node:diagnostics_channel');

diagnostics_channel.subscribe('my-channel', (message, name) => {
  // Received data
});
copy

diagnostics_channel.unsubscribe(name, onMessage)#

• name <string> | <symbol> 通道名称
• onMessage <Function> 之前订阅的要移除的处理器
• 返回: <boolean> 如果找到处理器则返回 true，否则返回 false。

移除之前通过 diagnostics_channel.subscribe(name, onMessage) 注册到此通道的消息处理器。

import diagnostics_channel from 'node:diagnostics_channel';

function onMessage(message, name) {
  // Received data
}

diagnostics_channel.subscribe('my-channel', onMessage);

diagnostics_channel.unsubscribe('my-channel', onMessage);
const diagnostics_channel = require('node:diagnostics_channel');

function onMessage(message, name) {
  // Received data
}

diagnostics_channel.subscribe('my-channel', onMessage);

diagnostics_channel.unsubscribe('my-channel', onMessage);
copy

diagnostics_channel.tracingChannel(nameOrChannels)#

• nameOrChannels <string> | <TracingChannel> 通道名称或包含所有 TracingChannel 通道 的对象
• 返回: <TracingChannel> 用于追踪的通道集合

为给定的 TracingChannel 通道 创建一个 TracingChannel 包装器。如果给定了名称，相应的追踪通道将以 tracing:${name}:${eventType} 的形式创建，其中 eventType 对应于 TracingChannel 通道 的类型。

import diagnostics_channel from 'node:diagnostics_channel';

const channelsByName = diagnostics_channel.tracingChannel('my-channel');

// or...

const channelsByCollection = diagnostics_channel.tracingChannel({
  start: diagnostics_channel.channel('tracing:my-channel:start'),
  end: diagnostics_channel.channel('tracing:my-channel:end'),
  asyncStart: diagnostics_channel.channel('tracing:my-channel:asyncStart'),
  asyncEnd: diagnostics_channel.channel('tracing:my-channel:asyncEnd'),
  error: diagnostics_channel.channel('tracing:my-channel:error'),
});
const diagnostics_channel = require('node:diagnostics_channel');

const channelsByName = diagnostics_channel.tracingChannel('my-channel');

// or...

const channelsByCollection = diagnostics_channel.tracingChannel({
  start: diagnostics_channel.channel('tracing:my-channel:start'),
  end: diagnostics_channel.channel('tracing:my-channel:end'),
  asyncStart: diagnostics_channel.channel('tracing:my-channel:asyncStart'),
  asyncEnd: diagnostics_channel.channel('tracing:my-channel:asyncEnd'),
  error: diagnostics_channel.channel('tracing:my-channel:error'),
});
copy

类: Channel#

类 Channel 代表数据流水线中的单个命名通道。它用于追踪订阅者，并在有订阅者存在时发布消息。它作为一个单独的对象存在，以避免在发布时进行通道查找，从而实现极快的发布速度，并允许在产生极小成本的情况下进行大量使用。通道是通过 diagnostics_channel.channel(name) 创建的，直接使用 new Channel(name) 构建通道是不受支持的。

channel.hasSubscribers#

• 返回: <boolean> 是否有活动的订阅者

检查此通道是否有活动的订阅者。如果您想要发送的消息准备起来可能很昂贵，这很有用。

此 API 是可选的，但在尝试从对性能高度敏感的代码发布消息时很有帮助。

import diagnostics_channel from 'node:diagnostics_channel';

const channel = diagnostics_channel.channel('my-channel');

if (channel.hasSubscribers) {
  // There are subscribers, prepare and publish message
}
const diagnostics_channel = require('node:diagnostics_channel');

const channel = diagnostics_channel.channel('my-channel');

if (channel.hasSubscribers) {
  // There are subscribers, prepare and publish message
}
copy

channel.publish(message)#

• message <any> 发送给通道订阅者的消息

向通道的任何订阅者发布消息。这将同步触发消息处理器，因此它们将在相同的上下文中执行。

import diagnostics_channel from 'node:diagnostics_channel';

const channel = diagnostics_channel.channel('my-channel');

channel.publish({
  some: 'message',
});
const diagnostics_channel = require('node:diagnostics_channel');

const channel = diagnostics_channel.channel('my-channel');

channel.publish({
  some: 'message',
});
copy

channel.subscribe(onMessage)#

• onMessage <Function> 接收通道消息的处理器
  • message <any> 消息数据
  • name <string> | <symbol> 通道名称

注册一个消息处理器以订阅此通道。每当向通道发布消息时，此消息处理器都将同步运行。在消息处理器中抛出的任何错误都会触发 'uncaughtException'。

import diagnostics_channel from 'node:diagnostics_channel';

const channel = diagnostics_channel.channel('my-channel');

channel.subscribe((message, name) => {
  // Received data
});
const diagnostics_channel = require('node:diagnostics_channel');

const channel = diagnostics_channel.channel('my-channel');

channel.subscribe((message, name) => {
  // Received data
});
copy

channel.unsubscribe(onMessage)#

• onMessage <Function> 之前订阅的要移除的处理器
• 返回: <boolean> 如果找到处理器则返回 true，否则返回 false。

移除之前通过 channel.subscribe(onMessage) 注册到此通道的消息处理器。

import diagnostics_channel from 'node:diagnostics_channel';

const channel = diagnostics_channel.channel('my-channel');

function onMessage(message, name) {
  // Received data
}

channel.subscribe(onMessage);

channel.unsubscribe(onMessage);
const diagnostics_channel = require('node:diagnostics_channel');

const channel = diagnostics_channel.channel('my-channel');

function onMessage(message, name) {
  // Received data
}

channel.subscribe(onMessage);

channel.unsubscribe(onMessage);
copy

channel.bindStore(store[, transform])#

• store <AsyncLocalStorage> 要绑定上下文数据的存储
• transform <Function> 在设置存储上下文之前转换上下文数据

当调用 channel.runStores(context, ...) 时，给定的上下文数据将应用于绑定到该通道的任何存储。如果存储已经被绑定，之前的 transform 函数将被新的函数替换。可以省略 transform 函数，直接将给定的上下文数据设置为上下文。

import diagnostics_channel from 'node:diagnostics_channel';
import { AsyncLocalStorage } from 'node:async_hooks';

const store = new AsyncLocalStorage();

const channel = diagnostics_channel.channel('my-channel');

channel.bindStore(store, (data) => {
  return { data };
});
const diagnostics_channel = require('node:diagnostics_channel');
const { AsyncLocalStorage } = require('node:async_hooks');

const store = new AsyncLocalStorage();

const channel = diagnostics_channel.channel('my-channel');

channel.bindStore(store, (data) => {
  return { data };
});
copy

channel.unbindStore(store)#

• store <AsyncLocalStorage> 要从通道解绑的存储。
• 返回: <boolean> 如果找到存储则返回 true，否则返回 false。

移除之前通过 channel.bindStore(store) 注册到此通道的消息处理器。

import diagnostics_channel from 'node:diagnostics_channel';
import { AsyncLocalStorage } from 'node:async_hooks';

const store = new AsyncLocalStorage();

const channel = diagnostics_channel.channel('my-channel');

channel.bindStore(store);
channel.unbindStore(store);
const diagnostics_channel = require('node:diagnostics_channel');
const { AsyncLocalStorage } = require('node:async_hooks');

const store = new AsyncLocalStorage();

const channel = diagnostics_channel.channel('my-channel');

channel.bindStore(store);
channel.unbindStore(store);
copy

channel.runStores(context, fn[, thisArg[, ...args]])#

• context <any> 发送给订阅者并绑定到存储的消息
• fn <Function> 在进入的存储上下文中运行的处理器
• thisArg <any> 函数调用中要使用的接收者（receiver）。
• ...args <any> 要传递给函数的可选参数。

将给定的数据应用于绑定到该通道的任何 AsyncLocalStorage 实例，持续时间为给定函数的执行期间，然后在应用了该数据到存储的范围内向通道发布消息。

如果将 transform 函数提供给 channel.bindStore(store)，它将在消息数据成为存储的上下文值之前对其进行转换。在需要链接上下文的情况下，可以从 transform 函数内部访问之前的存储上下文。

应用于存储的上下文应该可以在从给定函数期间开始执行的任何异步代码中访问，但在某些情况下可能会发生 上下文丢失。

import diagnostics_channel from 'node:diagnostics_channel';
import { AsyncLocalStorage } from 'node:async_hooks';

const store = new AsyncLocalStorage();

const channel = diagnostics_channel.channel('my-channel');

channel.bindStore(store, (message) => {
  const parent = store.getStore();
  return new Span(message, parent);
});
channel.runStores({ some: 'message' }, () => {
  store.getStore(); // Span({ some: 'message' })
});
const diagnostics_channel = require('node:diagnostics_channel');
const { AsyncLocalStorage } = require('node:async_hooks');

const store = new AsyncLocalStorage();

const channel = diagnostics_channel.channel('my-channel');

channel.bindStore(store, (message) => {
  const parent = store.getStore();
  return new Span(message, parent);
});
channel.runStores({ some: 'message' }, () => {
  store.getStore(); // Span({ some: 'message' })
});
copy

类: TracingChannel#

类 TracingChannel 是多个 TracingChannel 通道 的集合，它们共同表达了一个单一的可追踪操作。它用于形式化和简化为追踪应用程序流程生成事件的过程。diagnostics_channel.tracingChannel() 用于构造 TracingChannel。与 Channel 一样，建议在文件顶层创建并重用单个 TracingChannel，而不是动态创建它们。

tracingChannel.subscribe(subscribers)#

• subscribers <Object> TracingChannel 通道 订阅者集合
  • start <Function> start 事件 订阅者
  • end <Function> end 事件 订阅者
  • asyncStart <Function> asyncStart 事件 订阅者
  • asyncEnd <Function> asyncEnd 事件 订阅者
  • error <Function> error 事件 订阅者

将函数集合订阅到相应通道的辅助方法。这与在每个通道上单独调用 channel.subscribe(onMessage) 相同。

import diagnostics_channel from 'node:diagnostics_channel';

const channels = diagnostics_channel.tracingChannel('my-channel');

channels.subscribe({
  start(message) {
    // Handle start message
  },
  end(message) {
    // Handle end message
  },
  asyncStart(message) {
    // Handle asyncStart message
  },
  asyncEnd(message) {
    // Handle asyncEnd message
  },
  error(message) {
    // Handle error message
  },
});
const diagnostics_channel = require('node:diagnostics_channel');

const channels = diagnostics_channel.tracingChannel('my-channel');

channels.subscribe({
  start(message) {
    // Handle start message
  },
  end(message) {
    // Handle end message
  },
  asyncStart(message) {
    // Handle asyncStart message
  },
  asyncEnd(message) {
    // Handle asyncEnd message
  },
  error(message) {
    // Handle error message
  },
});
copy

tracingChannel.unsubscribe(subscribers)#

• subscribers <Object> TracingChannel 通道 订阅者集合
  • start <Function> start 事件 订阅者
  • end <Function> end 事件 订阅者
  • asyncStart <Function> asyncStart 事件 订阅者
  • asyncEnd <Function> asyncEnd 事件 订阅者
  • error <Function> error 事件 订阅者
• 返回: <boolean> 如果所有处理器都成功取消订阅则返回 true，否则返回 false。

从相应通道取消订阅函数集合的辅助方法。这与在每个通道上单独调用 channel.unsubscribe(onMessage) 相同。

import diagnostics_channel from 'node:diagnostics_channel';

const channels = diagnostics_channel.tracingChannel('my-channel');

channels.unsubscribe({
  start(message) {
    // Handle start message
  },
  end(message) {
    // Handle end message
  },
  asyncStart(message) {
    // Handle asyncStart message
  },
  asyncEnd(message) {
    // Handle asyncEnd message
  },
  error(message) {
    // Handle error message
  },
});
const diagnostics_channel = require('node:diagnostics_channel');

const channels = diagnostics_channel.tracingChannel('my-channel');

channels.unsubscribe({
  start(message) {
    // Handle start message
  },
  end(message) {
    // Handle end message
  },
  asyncStart(message) {
    // Handle asyncStart message
  },
  asyncEnd(message) {
    // Handle asyncEnd message
  },
  error(message) {
    // Handle error message
  },
});
copy

tracingChannel.traceSync(fn[, context[, thisArg[, ...args]]])#

• fn <Function> 要包装追踪的函数
• context <Object> 用于关联事件的共享对象
• thisArg <any> 函数调用使用的接收者
• ...args <any> 传递给函数的可选参数
• 返回: <any> 给定函数的返回值

追踪同步函数调用。这将始终在执行周围产生一个 start 事件 和 end 事件，如果给定的函数抛出错误，可能会产生一个 error 事件。这将使用 channel.runStores(context, ...) 在 start 通道上运行给定的函数，这确保所有事件都应设置任何绑定的存储以匹配此追踪上下文。

为确保仅形成正确的追踪图，仅在追踪开始前存在订阅者时才会发布事件。在追踪开始后添加的订阅将不会收到来自该追踪的未来事件，只会看到未来的追踪。

import diagnostics_channel from 'node:diagnostics_channel';

const channels = diagnostics_channel.tracingChannel('my-channel');

channels.traceSync(() => {
  // Do something
}, {
  some: 'thing',
});
const diagnostics_channel = require('node:diagnostics_channel');

const channels = diagnostics_channel.tracingChannel('my-channel');

channels.traceSync(() => {
  // Do something
}, {
  some: 'thing',
});
copy

tracingChannel.tracePromise(fn[, context[, thisArg[, ...args]]])#

• fn <Function> 要包装追踪的函数
• context <Object> 用于关联追踪事件的共享对象
• thisArg <any> 函数调用使用的接收者
• ...args <any> 传递给函数的可选参数
• 返回: <any> 给定函数的返回值，或者如果追踪通道有活跃的订阅者，则为在返回值上调用 .then(...) 的结果。如果返回值不是 Promise 或 thenable，则按原样返回并发出警告。

追踪返回 <Promise> 或 thenable 对象 的异步函数调用。这将始终在函数执行的同步部分周围产生一个 start 事件 和 end 事件，并当返回的 promise 被解析或拒绝时产生一个 asyncStart 事件 和 asyncEnd 事件。如果给定的函数抛出错误或返回的 promise 被拒绝，它也可能产生一个 error 事件。这将使用 channel.runStores(context, ...) 在 start 通道上运行给定的函数，这确保所有事件都应设置任何绑定的存储以匹配此追踪上下文。

如果 fn 返回的值不是 Promise 或 thenable，则它将被返回并伴随警告，并且不会产生 asyncStart 或 asyncEnd 事件。

为确保仅形成正确的追踪图，仅在追踪开始前存在订阅者时才会发布事件。在追踪开始后添加的订阅将不会收到来自该追踪的未来事件，只会看到未来的追踪。

import diagnostics_channel from 'node:diagnostics_channel';

const channels = diagnostics_channel.tracingChannel('my-channel');

channels.tracePromise(async () => {
  // Do something
}, {
  some: 'thing',
});
const diagnostics_channel = require('node:diagnostics_channel');

const channels = diagnostics_channel.tracingChannel('my-channel');

channels.tracePromise(async () => {
  // Do something
}, {
  some: 'thing',
});
copy

tracingChannel.traceCallback(fn[, position[, context[, thisArg[, ...args]]]])#

• fn <Function> 使用包装追踪的回调函数
• position <number> 预期回调的零索引参数位置（如果传入 undefined，则默认为最后一个参数）
• context <Object> 用于关联追踪事件的共享对象（如果传入 undefined，则默认为 {}）
• thisArg <any> 函数调用使用的接收者
• ...args <any> 传递给函数的参数（必须包含回调）
• 返回: <any> 给定函数的返回值

追踪接收回调的函数调用。回调预期遵循通常使用的错误作为第一个参数的约定。这将始终在函数执行的同步部分周围产生一个 start 事件 和 end 事件，并围绕回调执行产生一个 asyncStart 事件 和 asyncEnd 事件。如果给定的函数抛出错误或传递给回调的第一个参数被设置，它也可能产生一个 error 事件。这将使用 channel.runStores(context, ...) 在 start 通道上运行给定的函数，这确保所有事件都应设置任何绑定的存储以匹配此追踪上下文。

为确保仅形成正确的追踪图，仅在追踪开始前存在订阅者时才会发布事件。在追踪开始后添加的订阅将不会收到来自该追踪的未来事件，只会看到未来的追踪。

import diagnostics_channel from 'node:diagnostics_channel';

const channels = diagnostics_channel.tracingChannel('my-channel');

channels.traceCallback((arg1, callback) => {
  // Do something
  callback(null, 'result');
}, 1, {
  some: 'thing',
}, thisArg, arg1, callback);
const diagnostics_channel = require('node:diagnostics_channel');

const channels = diagnostics_channel.tracingChannel('my-channel');

channels.traceCallback((arg1, callback) => {
  // Do something
  callback(null, 'result');
}, 1, {
  some: 'thing',
}, thisArg, arg1, callback);
copy

回调也将使用 channel.runStores(context, ...) 运行，这在某些情况下能够实现上下文丢失恢复。

import diagnostics_channel from 'node:diagnostics_channel';
import { AsyncLocalStorage } from 'node:async_hooks';

const channels = diagnostics_channel.tracingChannel('my-channel');
const myStore = new AsyncLocalStorage();

// The start channel sets the initial store data to something
// and stores that store data value on the trace context object
channels.start.bindStore(myStore, (data) => {
  const span = new Span(data);
  data.span = span;
  return span;
});

// Then asyncStart can restore from that data it stored previously
channels.asyncStart.bindStore(myStore, (data) => {
  return data.span;
});
const diagnostics_channel = require('node:diagnostics_channel');
const { AsyncLocalStorage } = require('node:async_hooks');

const channels = diagnostics_channel.tracingChannel('my-channel');
const myStore = new AsyncLocalStorage();

// The start channel sets the initial store data to something
// and stores that store data value on the trace context object
channels.start.bindStore(myStore, (data) => {
  const span = new Span(data);
  data.span = span;
  return span;
});

// Then asyncStart can restore from that data it stored previously
channels.asyncStart.bindStore(myStore, (data) => {
  return data.span;
});
copy

tracingChannel.hasSubscribers#

• 返回: <boolean> 如果任何单个通道有订阅者则返回 true，否则返回 false。

这是在 TracingChannel 实例上可用的辅助方法，用于检查任何 TracingChannel 通道 是否有订阅者。如果其中任何一个至少有一个订阅者，则返回 true，否则返回 false。

import diagnostics_channel from 'node:diagnostics_channel';

const channels = diagnostics_channel.tracingChannel('my-channel');

if (channels.hasSubscribers) {
  // Do something
}
const diagnostics_channel = require('node:diagnostics_channel');

const channels = diagnostics_channel.tracingChannel('my-channel');

if (channels.hasSubscribers) {
  // Do something
}
copy

TracingChannel 通道#

TracingChannel 是多个 diagnostics_channels 的集合，代表单个可追踪操作执行生命周期中的特定点。该行为分为五个 diagnostics_channels，包括 start、end、asyncStart、asyncEnd 和 error。单个可追踪操作将在所有事件之间共享同一个事件对象，这对于通过 WeakMap 管理关联很有帮助。

当任务“完成”时，这些事件对象将使用 result 或 error 值进行扩展。在同步任务的情况下，result 将是返回值，而 error 将是函数抛出的任何内容。对于基于回调的异步函数，result 将是回调的第二个参数，而 error 将是 end 事件中可见的抛出错误，或者是 asyncStart 或 asyncEnd 事件中回调的第一个参数。

为确保仅形成正确的追踪图，仅在追踪开始前存在订阅者时才应发布事件。在追踪开始后添加的订阅不应收到来自该追踪的未来事件，只会看到未来的追踪。

追踪通道应遵循如下命名模式

• tracing:module.class.method:start 或 tracing:module.function:start
• tracing:module.class.method:end 或 tracing:module.function:end
• tracing:module.class.method:asyncStart 或 tracing:module.function:asyncStart
• tracing:module.class.method:asyncEnd 或 tracing:module.function:asyncEnd
• tracing:module.class.method:error 或 tracing:module.function:error

start(event)#

• 名称: tracing:${name}:start

start 事件代表函数被调用的点。此时，事件数据可能包含函数参数或函数执行开始时可用的任何其他内容。

end(event)#

• 名称: tracing:${name}:end

end 事件代表函数调用返回值的点。对于异步函数，这是指 promise 被返回时，而不是函数本身在内部执行 return 语句时。此时，如果追踪的函数是同步的，result 字段将被设置为函数的返回值。或者，可能存在 error 字段以表示任何抛出的错误。

建议专门监听 error 事件以追踪错误，因为可追踪操作可能会产生多个错误。例如，在任务的同步部分抛出错误之前，可能会在内部启动一个失败的异步任务。

asyncStart(event)#

• 名称: tracing:${name}:asyncStart

asyncStart 事件代表已达到可追踪函数的回调或延续。此时，可能可以使用回调参数，或表达操作“结果”的任何其他内容。

对于基于回调的函数，如果不是 undefined 或 null，回调的第一个参数将被分配给 error 字段，第二个参数将被分配给 result 字段。

对于 promise，resolve 路径的参数将被分配给 result，或者 reject 路径的参数将被分配给 error。

建议专门监听 error 事件以追踪错误，因为可追踪操作可能会产生多个错误。例如，在任务的同步部分抛出错误之前，可能会在内部启动一个失败的异步任务。

asyncEnd(event)#

• 名称: tracing:${name}:asyncEnd

asyncEnd 事件代表异步函数的回调返回。事件数据在 asyncStart 事件之后不太可能发生变化，但查看回调完成的点可能很有用。

error(event)#

• 名称: tracing:${name}:error

error 事件代表由可追踪函数产生的任何同步或异步错误。如果在追踪函数的同步部分抛出错误，该错误将被分配给事件的 error 字段并触发 error 事件。如果通过回调或 promise 拒绝异步接收到错误，它也将被分配给事件的 error 字段并触发 error 事件。

单个可追踪函数调用多次产生错误是可能的，因此在使用此事件时应考虑这一点。例如，如果内部触发了另一个失败的异步任务，随后函数的同步部分抛出了错误，则会发出两个 error 事件，一个用于同步错误，一个用于异步错误。

内置通道#

控制台 (Console)#

事件: 'console.log'#

• args <any[]>

当调用 console.log() 时发出。接收传递给 console.log() 的参数数组。

事件: 'console.info'#

• args <any[]>

当调用 console.info() 时发出。接收传递给 console.info() 的参数数组。

事件: 'console.debug'#

• args <any[]>

当调用 console.debug() 时发出。接收传递给 console.debug() 的参数数组。

事件: 'console.warn'#

• args <any[]>

当调用 console.warn() 时发出。接收传递给 console.warn() 的参数数组。

事件: 'console.error'#

• args <any[]>

当调用 console.error() 时发出。接收传递给 console.error() 的参数数组。

HTTP#

事件: 'http.client.request.created'#

• request <http.ClientRequest>

当客户端创建请求对象时发出。与 http.client.request.start 不同，此事件在请求发送前发出。

事件: 'http.client.request.start'#

• request <http.ClientRequest>

当客户端开始请求时发出。

事件: 'http.client.request.error'#

• request <http.ClientRequest>
• error <Error>

当客户端请求期间发生错误时发出。

事件: 'http.client.response.finish'#

• request <http.ClientRequest>
• response <http.IncomingMessage>

当客户端收到响应时发出。

事件: 'http.server.request.start'#

• request <http.IncomingMessage>
• response <http.ServerResponse>
• socket <net.Socket>
• server <http.Server>

当服务器收到请求时发出。

事件: 'http.server.response.created'#

• request <http.IncomingMessage>
• response <http.ServerResponse>

当服务器创建响应时发出。此事件在响应发送前发出。

事件: 'http.server.response.finish'#

• request <http.IncomingMessage>
• response <http.ServerResponse>
• socket <net.Socket>
• server <http.Server>

当服务器发送响应时发出。

HTTP/2#

事件: 'http2.client.stream.created'#

• stream <ClientHttp2Stream>
• headers <HTTP/2 Headers Object>

当在客户端上创建流时发出。

事件: 'http2.client.stream.start'#

• stream <ClientHttp2Stream>
• headers <HTTP/2 Headers Object>

当在客户端上启动流时发出。

事件: 'http2.client.stream.error'#

• stream <ClientHttp2Stream>
• error <Error>

当在客户端上处理流期间发生错误时发出。

事件: 'http2.client.stream.finish'#

• stream <ClientHttp2Stream>
• headers <HTTP/2 Headers Object>
• flags <number>

当在客户端上接收到流时发出。

事件: 'http2.client.stream.bodyChunkSent'#

• stream <ClientHttp2Stream>
• writev <boolean>
• data <Buffer> | <string> | <Buffer[]> | <Object[]>
  • chunk <Buffer> | <string>
  • encoding <string>
• encoding <string>

当客户端流主体的块正在发送时发出。

事件: 'http2.client.stream.bodySent'#

• stream <ClientHttp2Stream>

在客户端流主体已完全发送后发出。

事件: 'http2.client.stream.close'#

• stream <ClientHttp2Stream>

当在客户端上关闭流时发出。关闭流时使用的 HTTP/2 错误代码可以使用 stream.rstCode 属性获取。

事件: 'http2.server.stream.created'#

• stream <ServerHttp2Stream>
• headers <HTTP/2 Headers Object>

当在服务器上创建流时发出。

事件: 'http2.server.stream.start'#

• stream <ServerHttp2Stream>
• headers <HTTP/2 Headers Object>

当在服务器上启动流时发出。

事件: 'http2.server.stream.error'#

• stream <ServerHttp2Stream>
• error <Error>

当在服务器上处理流期间发生错误时发出。

事件: 'http2.server.stream.finish'#

• stream <ServerHttp2Stream>
• headers <HTTP/2 Headers Object>
• flags <number>

当在服务器上发送流时发出。

事件: 'http2.server.stream.close'#

• stream <ServerHttp2Stream>

当在服务器上关闭流时发出。关闭流时使用的 HTTP/2 错误代码可以使用 stream.rstCode 属性获取。

模块#

事件: 'module.require.start'#

• event <Object> 包含以下属性
  • id 传递给 require() 的参数。模块名称。
  • parentFilename 尝试 require(id) 的模块名称。

当执行 require() 时发出。参见 start 事件。

事件: 'module.require.end'#

• event <Object> 包含以下属性
  • id 传递给 require() 的参数。模块名称。
  • parentFilename 尝试 require(id) 的模块名称。

当 require() 调用返回时发出。参见 end 事件。

事件: 'module.require.error'#

• event <Object> 包含以下属性
  • id 传递给 require() 的参数。模块名称。
  • parentFilename 尝试 require(id) 的模块名称。
• error <Error>

当 require() 抛出错误时发出。参见 error 事件。

事件: 'module.import.asyncStart'#

• event <Object> 包含以下属性
  • id 传递给 import() 的参数。模块名称。
  • parentURL 尝试 import(id) 的模块的 URL 对象。

当调用 import() 时发出。参见 asyncStart 事件。

事件: 'module.import.asyncEnd'#

• event <Object> 包含以下属性
  • id 传递给 import() 的参数。模块名称。
  • parentURL 尝试 import(id) 的模块的 URL 对象。

当 import() 完成时发出。参见 asyncEnd 事件。

事件: 'module.import.error'#

• event <Object> 包含以下属性
  • id 传递给 import() 的参数。模块名称。
  • parentURL 尝试 import(id) 的模块的 URL 对象。
• error <Error>

当 import() 抛出错误时发出。参见 error 事件。

NET#

事件: 'net.client.socket'#

• socket <net.Socket> | <tls.TLSSocket>

当创建新的 TCP 或管道客户端套接字连接时发出。

事件: 'net.server.socket'#

• socket <net.Socket>

当收到新的 TCP 或管道连接时发出。

事件: 'tracing:net.server.listen:asyncStart'#

• server <net.Server>
• options <Object>

当调用 net.Server.listen() 时，在实际设置端口或管道之前发出。

事件: 'tracing:net.server.listen:asyncEnd'#

• server <net.Server>

当 net.Server.listen() 完成且服务器准备好接受连接时发出。

事件: 'tracing:net.server.listen:error'#

• server <net.Server>
• error <Error>

当 net.Server.listen() 返回错误时发出。

UDP#

事件: 'udp.socket'#

• socket <dgram.Socket>

当创建新的 UDP 套接字时发出。

进程 (Process)#

事件: 'child_process'#

• process <ChildProcess>

当创建新进程时发出。

tracing:child_process.spawn:start

• process <ChildProcess>
• options <Object>

当调用 child_process.spawn() 时，在实际生成进程之前发出。

tracing:child_process.spawn:end

• process <ChildProcess>

当 child_process.spawn() 成功完成且进程已创建时发出。

tracing:child_process.spawn:error

• process <ChildProcess>
• error <Error>

当 child_process.spawn() 遇到错误时发出。

事件: 'execve'#

• execPath <string>
• args <string[]>
• env <string[]>

当调用 process.execve() 时发出。

Web Locks#

这些通道针对每个 locks.request() 调用发出。有关 Web Locks 的详细信息，请参见 worker_threads.locks。

事件: 'locks.request.start'#

• name <string> 请求锁资源的名称。
• mode <string> 锁模式：'exclusive' 或 'shared'。

当启动锁请求时，在授予锁之前发出。

事件: 'locks.request.grant'#

• name <string> 请求锁资源的名称。
• mode <string> 锁模式：'exclusive' 或 'shared'。

当成功授予锁且回调即将运行时发出。

事件: 'locks.request.miss'#

• name <string> 请求锁资源的名称。
• mode <string> 锁模式：'exclusive' 或 'shared'。

当 ifAvailable 为 true 且锁不立即可用，并且请求回调以 null 而不是 Lock 对象调用时发出。

事件: 'locks.request.end'#

• name <string> 请求锁资源的名称。
• mode <string> 锁模式：'exclusive' 或 'shared'。
• steal <boolean> 请求是否使用抢占语义。
• ifAvailable <boolean> 请求是否使用 ifAvailable 语义。
• error <Error> | <undefined> 回调抛出的错误（如果有）。

当锁请求完成时发出，无论是回调成功、抛出错误，还是锁被抢占。

工作线程 (Worker Thread)#

事件: 'worker_threads'#

• worker <Worker>

当创建新线程时发出。