Node.js v18.20.8 文档

公共接口#>

【Public API】

概述#>

【Overview】

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

【Following is a simple overview of the public 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);拷贝

diagnostics_channel.hasSubscribers(name)#>

• name <string> | <symbol> 通道名称
• 返回：<boolean> 如果有活跃的订阅者

检查指定通道是否有活跃订阅者。如果你要发送的消息准备起来可能很昂贵，这会很有用。

【Check if there are active subscribers to the named channel. This is helpful if the message you want to send might be expensive to prepare.】

此 API 是可选的，但在从对性能极其敏感的代码发布消息时非常有用。

【This API is optional but helpful when trying to publish messages from very performance-sensitive code.】

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
}拷贝

diagnostics_channel.channel(name)#>

• name <string> | <symbol> 通道名称
• 返回：<Channel> 指定的通道对象

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

【This is the primary entry-point for anyone wanting to publish to a named channel. It produces a channel object which is optimized to reduce overhead at publish time as much as possible.】

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');拷贝

diagnostics_channel.subscribe(name, onMessage)#>

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

注册一个消息处理程序以订阅此通道。每当有消息发布到该通道时，这个消息处理程序将同步执行。消息处理程序中抛出的任何错误都会触发 'uncaughtException'。

【Register a message handler to subscribe to this channel. This message handler will be run synchronously whenever a message is published to the channel. Any errors thrown in the message handler will trigger an '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
});拷贝

diagnostics_channel.unsubscribe(name, onMessage)#>

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

移除之前使用 diagnostics_channel.subscribe(name, onMessage) 在此通道注册的消息处理程序。

【Remove a message handler previously registered to this channel with 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);拷贝

diagnostics_channel.tracingChannel(nameOrChannels)#>

• nameOrChannels <string> | <TracingChannel> 通道名称或包含所有 TracingChannel 通道 的对象
• 返回：<TracingChannel> 要跟踪的通道集合

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

【Creates a TracingChannel wrapper for the given TracingChannel Channels. If a name is given, the corresponding tracing channels will be created in the form of tracing:${name}:${eventType} where eventType corresponds to the types of TracingChannel Channels.】

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'),
});拷贝

类：Channel#>

【Class: Channel】

类 Channel 表示数据管道中的一个名为通道的个体。它用于跟踪订阅者，并在有订阅者存在时发布消息。它作为一个独立的对象存在，以避免在发布时进行通道查找，从而实现非常快速的发布速度，并在高频使用时产生极低的成本。通道通过 diagnostics_channel.channel(name) 创建，不支持直接使用 new Channel(name) 构造通道。

【The class Channel represents an individual named channel within the data pipeline. It is used to track subscribers and to publish messages when there are subscribers present. It exists as a separate object to avoid channel lookups at publish time, enabling very fast publish speeds and allowing for heavy use while incurring very minimal cost. Channels are created with diagnostics_channel.channel(name), constructing a channel directly with new Channel(name) is not supported.】

channel.hasSubscribers#>

• 返回：<boolean> 如果有活跃的订阅者

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

【Check if there are active subscribers to this channel. This is helpful if the message you want to send might be expensive to prepare.】

此 API 是可选的，但在从对性能极其敏感的代码发布消息时非常有用。

【This API is optional but helpful when trying to publish messages from very performance-sensitive code.】

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
}拷贝

channel.publish(message)#>

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

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

【Publish a message to any subscribers to the channel. This will trigger message handlers synchronously so they will execute within the same context.】

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',
});拷贝

channel.subscribe(onMessage)#>

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

注册一个消息处理程序以订阅此通道。每当有消息发布到该通道时，这个消息处理程序将同步执行。消息处理程序中抛出的任何错误都会触发 'uncaughtException'。

【Register a message handler to subscribe to this channel. This message handler will be run synchronously whenever a message is published to the channel. Any errors thrown in the message handler will trigger an '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
});拷贝

channel.unsubscribe(onMessage)#>

• onMessage <Function> 要移除的先前订阅的处理程序
• 返回：<boolean> 如果找到处理程序，则为 true，否则为 false。

移除之前使用 channel.subscribe(onMessage) 在此通道注册的消息处理程序。

【Remove a message handler previously registered to this channel with 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);拷贝

channel.bindStore(store[, transform])#>

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

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

【When channel.runStores(context, ...) is called, the given context data will be applied to any store bound to the channel. If the store has already been bound the previous transform function will be replaced with the new one. The transform function may be omitted to set the given context data as the context directly.】

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 };
});拷贝

channel.unbindStore(store)#>

• store <AsyncLocalStorage> 要从通道解绑的商店。
• 返回：<boolean> 如果找到商店，则为 true，否则为 false。

移除之前使用 channel.bindStore(store) 在此通道注册的消息处理程序。

【Remove a message handler previously registered to this channel with 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);拷贝

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

• context <any> 发送给订阅者并绑定到商店的消息
• fn <Function> 处理程序将在输入的存储上下文中运行
• thisArg <any> 用于函数调用的接收对象。
• ...args <any> 可选参数，传递给函数。

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

【Applies the given data to any AsyncLocalStorage instances bound to the channel for the duration of the given function, then publishes to the channel within the scope of that data is applied to the stores.】

如果向 channel.bindStore(store) 提供了一个转换函数，它将在消息数据成为存储的上下文值之前被应用以进行转换。在需要上下文关联的情况下，先前的存储上下文可以在转换函数中访问。

【If a transform function was given to channel.bindStore(store) it will be applied to transform the message data before it becomes the context value for the store. The prior storage context is accessible from within the transform function in cases where context linking is required.】

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

【The context applied to the store should be accesible in any async code which continues from execution which began during the given function, however there are some situations in which context loss may occur.】

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' })
});拷贝

类：TracingChannel#>

【Class: TracingChannel】

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

【The class TracingChannel is a collection of TracingChannel Channels which together express a single traceable action. It is used to formalize and simplify the process of producing events for tracing application flow. diagnostics_channel.tracingChannel() is used to construct a TracingChannel. As with Channel it is recommended to create and reuse a single TracingChannel at the top-level of the file rather than creating them dynamically.】

tracingChannel.subscribe(subscribers)#>

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

用于将一组函数订阅到相应通道的助手。
这与在每个通道上单独调用 channel.subscribe(onMessage) 是一样的。

【Helper to subscribe a collection of functions to the corresponding channels. This is the same as calling channel.subscribe(onMessage) on each channel individually.】

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
  },
});拷贝

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) 相同。

【Helper to unsubscribe a collection of functions from the corresponding channels. This is the same as calling channel.unsubscribe(onMessage) on each channel individually.】

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
  },
});拷贝

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

• fn <Function> 用于封装跟踪的函数
• context <Object> 共享对象，用于关联事件
• thisArg <any> 用于函数调用的接收对象
• ...args <any> 可选参数，传递给函数
• 返回值：<any> 给定函数的返回值

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

【Trace a synchronous function call. This will always produce a start event and end event around the execution and may produce an error event if the given function throws an error. This will run the given function using channel.runStores(context, ...) on the start channel which ensures all events should have any bound stores set to match this trace context.】

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',
});拷贝

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

• fn <Function> 返回 Promise 的函数，用于在其周围封装跟踪
• context <Object> 共享对象，用于关联跟踪事件
• thisArg <any> 用于函数调用的接收对象
• ...args <any> 可选参数，传递给函数
• 返回：<Promise> 链式来自给定函数返回的 Promise

跟踪返回 Promise 的函数调用。这将在函数执行的同步部分始终产生 start 事件 和 end 事件，并且在到达 Promise 延续时会产生 asyncStart 事件 和 asyncEnd 事件。如果给定的函数抛出错误或返回的 Promise 被拒绝，它也可能产生 error 事件。这将使用 start 通道上的 channel.runStores(context, ...) 运行给定函数，这确保所有事件的任何绑定存储都设置为匹配此跟踪上下文。

【Trace a promise-returning function call. This will always produce a start event and end event around the synchronous portion of the function execution, and will produce an asyncStart event and asyncEnd event when a promise continuation is reached. It may also produce an error event if the given function throws an error or the returned promise rejects. This will run the given function using channel.runStores(context, ...) on the start channel which ensures all events should have any bound stores set to match this trace context.】

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',
});拷贝

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

• fn <Function> 回调，使用函数来封装追踪
• position <number> 期望回调的从零开始索引的位置
• context <Object> 共享对象，用于关联跟踪事件
• thisArg <any> 用于函数调用的接收对象
• ...args <any> 可选参数，传递给函数
• 返回值：<any> 给定函数的返回值

跟踪一个接收回调的函数调用。这将始终在函数执行的同步部分产生 start 事件 和 end 事件，并且会在回调执行时产生 asyncStart 事件 和 asyncEnd 事件。如果给定函数抛出错误或返回的 promise 被拒绝，它也可能产生 error 事件。这将使用 start 通道上的 channel.runStores(context, ...) 运行给定函数，这确保所有事件的任何绑定存储都设置为匹配此跟踪上下文。

【Trace a callback-receiving function call. This will always produce a start event and end event around the synchronous portion of the function execution, and will produce a asyncStart event and asyncEnd event around the callback execution. It may also produce an error event if the given function throws an error or the returned promise rejects. This will run the given function using channel.runStores(context, ...) on the start channel which ensures all events should have any bound stores set to match this trace context.】

position 默认值为 -1，表示最后一个参数将用作回调函数。

【The position will be -1 by default to indicate the final argument should be used as the callback.】

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');
}, {
  some: 'thing',
}, thisArg, arg1, callback);拷贝

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

【The callback will also be run with channel.runStores(context, ...) which enables context loss recovery in some cases.】

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;
});拷贝

TracingChannel 通道#>

【TracingChannel Channels】

TracingChannel 是多个 diagnostics_channel 的集合，表示单个可跟踪操作执行生命周期中的特定点。其行为分为五个 diagnostics_channel，包括 start、end、asyncStart、asyncEnd 和 error。单个可跟踪操作将在所有事件之间共享相同的事件对象，这对于通过 weakmap 管理关联非常有用。

【A TracingChannel is a collection of several diagnostics_channels representing specific points in the execution lifecycle of a single traceable action. The behaviour is split into five diagnostics_channels consisting of start, end, asyncStart, asyncEnd, and error. A single traceable action will share the same event object between all events, this can be helpful for managing correlation through a weakmap.】

当任务“完成”时，这些事件对象将会扩展包含 result 或 error 的值。对于同步任务，result 将是返回值，而 error 则是函数中抛出的任何异常。对于基于回调的异步函数，result 将是回调的第二个参数，而 error 要么是在 end 事件中可见的抛出错误，要么是在 asyncStart 或 asyncEnd 事件中的第一个回调参数。

【These event objects will be extended with result or error values when the task "completes". In the case of a synchronous task the result will be the return value and the error will be anything thrown from the function. With callback-based async functions the result will be the second argument of the callback while the error will either be a thrown error visible in the end event or the first callback argument in either of the asyncStart or asyncEnd events.】

跟踪通道应遵循以下命名模式：

【Tracing channels should follow a naming pattern of:】

• tracing:模块.类.方法:start 或 tracing:模块.函数:start
• tracing:模块.类.方法:end 或 tracing:模块.函数:end
• tracing:模块.类.方法:asyncStart 或 tracing:模块.函数:asyncStart
• tracing:模块.类.方法:asyncEnd 或 tracing:模块.函数:asyncEnd
• tracing:模块.类.方法:错误 或 tracing:模块.函数:错误

start(event)#>

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

start 事件表示函数被调用的时刻。在这一点上，事件数据可能包含函数的参数或函数执行开始时可用的其他任何信息。

【The start event represents the point at which a function is called. At this point the event data may contain function arguments or anything else available at the very start of the execution of the function.】

end(event)#>

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

end 事件表示函数调用返回值的时刻。对于异步函数来说，这是指返回的 Promise 被解析的时候，而不是函数内部执行 return 语句的时候。此时，如果被跟踪的函数是同步的，result 字段将被设置为函数的返回值。或者，error 字段可能存在，用于表示任何抛出的错误。

【The end event represents the point at which a function call returns a value. In the case of an async function this is when the promise returned not when the function itself makes a return statement internally. At this point, if the traced function was synchronous the result field will be set to the return value of the function. Alternatively, the error field may be present to represent any thrown errors.】

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

【It is recommended to listen specifically to the error event to track errors as it may be possible for a traceable action to produce multiple errors. For example, an async task which fails may be started internally before the sync part of the task then throws an error.】

asyncStart(event)#>

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

asyncStart 事件表示可追踪函数的回调或后续操作已被触发。在这一点上，回调参数或任何其他表示该操作“结果”的内容可能可用。

【The asyncStart event represents the callback or continuation of a traceable function being reached. At this point things like callback arguments may be available, or anything else expressing the "result" of the action.】

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

【For callbacks-based functions, the first argument of the callback will be assigned to the error field, if not undefined or null, and the second argument will be assigned to the result field.】

对于 Promise，传给 resolve 路径的参数将被赋值给 result，或传给 reject 路径的参数将被赋值给 error。

【For promises, the argument to the resolve path will be assigned to result or the argument to the reject path will be assign to error.】

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

【It is recommended to listen specifically to the error event to track errors as it may be possible for a traceable action to produce multiple errors. For example, an async task which fails may be started internally before the sync part of the task then throws an error.】

asyncEnd(event)#>

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

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

【The asyncEnd event represents the callback of an asynchronous function returning. It's not likely event data will change after the asyncStart event, however it may be useful to see the point where the callback completes.】

error(event)#>

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

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

【The error event represents any error produced by the traceable function either synchronously or asynchronously. If an error is thrown in the synchronous portion of the traced function the error will be assigned to the error field of the event and the error event will be triggered. If an error is received asynchronously through a callback or promise rejection it will also be assigned to the error field of the event and trigger the error event.】

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

【It is possible for a single traceable function call to produce errors multiple times so this should be considered when consuming this event. For example, if another async task is triggered internally which fails and then the sync part of the function then throws and error two error events will be emitted, one for the sync error and one for the async error.】

内置通道#>

【Built-in Channels】

虽然 diagnostics_channel API 现在被认为是稳定的，但当前可用的内置通道尚不稳定。每个通道必须独立声明为稳定。

【While the diagnostics_channel API is now considered stable, the built-in channels currently available are not. Each channel must be declared stable independently.】

超文本传输协议#>

【HTTP】

http.client.request.start

• request <http.ClientRequest>

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

【Emitted when client starts a request.】

http.client.response.finish

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

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

【Emitted when client receives a response.】

http.server.request.start

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

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

【Emitted when server receives a request.】

http.server.response.finish

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

服务器发送响应时触发。

【Emitted when server sends a response.】

net.client.socket

• socket <net.Socket>

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

【Emitted when a new TCP or pipe client socket is created.】

net.server.socket

• socket <net.Socket>

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

【Emitted when a new TCP or pipe connection is received.】

udp.socket

• socket <dgram.Socket>

创建新的 UDP 套接字时触发。

【Emitted when a new UDP socket is created.】