诊断通道

[历史]

版本	变更
v19.2.0, v18.13.0	diagnostics_channel 现已稳定。
v15.1.0, v14.17.0	新增于：v15.1.0, v14.17.0

[稳定性：2 - 稳定]

稳定性：2 稳定性：2 - 稳定

源代码: lib/diagnostics_channel.js

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

可以使用以下方式访问：

ESM

import diagnostics_channel from 'node:diagnostics_channel'

CJS

const diagnostics_channel = require('node:diagnostics_channel')

模块编写者想要报告诊断消息时，应该创建一个或多个顶级通道来通过这些通道报告消息。也可以在运行时获取通道，但不建议这样做，因为这样做会增加额外的开销。可以导出通道以方便使用，但只要知道名称，就可以在任何地方获取它。

如果您希望您的模块生成诊断数据供其他人使用，建议您包含已使用命名通道的文档以及消息数据的结构。通道名称通常应包含模块名称，以避免与来自其他模块的数据冲突。

公共 API

概述

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

ESM

import diagnostics_channel from 'node:diagnostics_channel'

// 获取可重用的通道对象
const channel = diagnostics_channel.channel('my-channel')

function onMessage(message, name) {
  // 接收到的数据
}

// 订阅通道
diagnostics_channel.subscribe('my-channel', onMessage)

// 检查通道是否有活动的订阅者
if (channel.hasSubscribers) {
  // 将数据发布到通道
  channel.publish({
    some: 'data',
  })
}

// 取消订阅通道
diagnostics_channel.unsubscribe('my-channel', onMessage)

CJS

const diagnostics_channel = require('node:diagnostics_channel')

// 获取可重用的通道对象
const channel = diagnostics_channel.channel('my-channel')

function onMessage(message, name) {
  // 接收到的数据
}

// 订阅通道
diagnostics_channel.subscribe('my-channel', onMessage)

// 检查通道是否有活动的订阅者
if (channel.hasSubscribers) {
  // 将数据发布到通道
  channel.publish({
    some: 'data',
  })
}

// 取消订阅通道
diagnostics_channel.unsubscribe('my-channel', onMessage)

diagnostics_channel.hasSubscribers(name)

新增于：v15.1.0, v14.17.0

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

检查指定名称的通道是否有活跃的订阅者。如果您要发送的消息可能代价高昂，则此方法很有用。

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

ESM

import diagnostics_channel from 'node:diagnostics_channel'

if (diagnostics_channel.hasSubscribers('my-channel')) {
  // 有订阅者，准备并发布消息
}

CJS

const diagnostics_channel = require('node:diagnostics_channel')

if (diagnostics_channel.hasSubscribers('my-channel')) {
  // 有订阅者，准备并发布消息
}

diagnostics_channel.channel(name)

新增于: v15.1.0, v14.17.0

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

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

ESM

import diagnostics_channel from 'node:diagnostics_channel'

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

CJS

const diagnostics_channel = require('node:diagnostics_channel')

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

diagnostics_channel.subscribe(name, onMessage)

新增于: v18.7.0, v16.17.0

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

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

ESM

import diagnostics_channel from 'node:diagnostics_channel'

diagnostics_channel.subscribe('my-channel', (message, name) => {
  // 收到数据
})

CJS

const diagnostics_channel = require('node:diagnostics_channel')

diagnostics_channel.subscribe('my-channel', (message, name) => {
  // 收到数据
})

diagnostics_channel.unsubscribe(name, onMessage)

新增于：v18.7.0, v16.17.0

• name <字符串> | <符号> 通道名称
• onMessage <函数> 要移除的先前已订阅的处理程序
• 返回值: <布尔值> 如果找到处理程序则返回 true，否则返回 false。

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

ESM

import diagnostics_channel from 'node:diagnostics_channel'

function onMessage(message, name) {
  // 收到的数据
}

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

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

CJS

const diagnostics_channel = require('node:diagnostics_channel')

function onMessage(message, name) {
  // 收到的数据
}

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

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

diagnostics_channel.tracingChannel(nameOrChannels)

新增于: v19.9.0, v18.19.0

[稳定性: 1 - 实验性]

稳定性: 1 稳定性: 1 - 实验性

• nameOrChannels <字符串> | <TracingChannel> 通道名称或包含所有TracingChannel 通道的对象
• 返回值: <TracingChannel> 用于跟踪的通道集合

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

ESM

import diagnostics_channel from 'node:diagnostics_channel'

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

// 或者...

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

CJS

const diagnostics_channel = require('node:diagnostics_channel')

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

// 或者...

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

新增于: v15.1.0, v14.17.0

Channel 类代表数据管道中一个命名的单个通道。它用于跟踪订阅者并在存在订阅者时发布消息。它作为一个单独的对象存在，以避免在发布时查找通道，从而实现非常快的发布速度，并允许在付出极少成本的情况下进行大量使用。通道由 diagnostics_channel.channel(name) 创建，不支持直接使用 new Channel(name) 构造通道。

channel.hasSubscribers

新增于: v15.1.0, v14.17.0

• 返回值: <boolean> 是否存在活动订阅者

检查此通道是否存在活动订阅者。如果您要发送的消息可能需要大量准备工作，这将非常有用。

此 API 是可选的，但在尝试从非常注重性能的代码发布消息时很有帮助。

ESM

import diagnostics_channel from 'node:diagnostics_channel'

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

if (channel.hasSubscribers) {
  // 存在订阅者，准备并发布消息
}

CJS

const diagnostics_channel = require('node:diagnostics_channel')

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

if (channel.hasSubscribers) {
  // 存在订阅者，准备并发布消息
}

channel.publish(message)

新增于: v15.1.0, v14.17.0

• message <any> 发送到频道订阅者的消息

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

ESM

import diagnostics_channel from 'node:diagnostics_channel'

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

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

CJS

const diagnostics_channel = require('node:diagnostics_channel')

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

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

channel.subscribe(onMessage)

新增于: v15.1.0, v14.17.0

自 v18.7.0, v16.17.0 起已弃用

[稳定性: 0 - 已弃用]

稳定性: 0 稳定性: 0 - 已弃用: 使用 diagnostics_channel.subscribe(name, onMessage)

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

注册一个消息处理程序来订阅此频道。每当向频道发布消息时，都会同步运行此消息处理程序。消息处理程序中抛出的任何错误都将触发 'uncaughtException' 事件。

ESM

import diagnostics_channel from 'node:diagnostics_channel'

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

channel.subscribe((message, name) => {
  // 收到的数据
})

CJS

const diagnostics_channel = require('node:diagnostics_channel')

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

channel.subscribe((message, name) => {
  // 收到的数据
})

channel.unsubscribe(onMessage)

[历史]

版本	变更
v18.7.0, v16.17.0	已弃用：v18.7.0, v16.17.0
v17.1.0, v16.14.0, v14.19.0	新增返回值。添加到没有订阅者的通道。
v15.1.0, v14.17.0	新增：v15.1.0, v14.17.0

[稳定性：0 - 已弃用]

稳定性：0 稳定性：0 - 已弃用：请使用 diagnostics_channel.unsubscribe(name, onMessage)

• onMessage <函数> 要移除的先前已注册的处理程序
• 返回值: <布尔值> 如果找到处理程序，则返回 true，否则返回 false。

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

ESM

import diagnostics_channel from 'node:diagnostics_channel'

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

function onMessage(message, name) {
  // 接收到的数据
}

channel.subscribe(onMessage)

channel.unsubscribe(onMessage)

CJS

const diagnostics_channel = require('node:diagnostics_channel')

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

function onMessage(message, name) {
  // 接收到的数据
}

channel.subscribe(onMessage)

channel.unsubscribe(onMessage)

channel.bindStore(store[, transform])

新增于：v19.9.0, v18.19.0

[稳定性：1 - 实验性]

稳定性：1 稳定性：1 - 实验性

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

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

ESM

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 }
})

CJS

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)

新增于：v19.9.0, v18.19.0

[稳定性：1 - 实验性]

稳定性：1 稳定性：1 - 实验性

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

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

ESM

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)

CJS

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]])

新增于：v19.9.0, v18.19.0

[稳定性：1 - 实验性]

稳定性：1 稳定性：1 - 实验性

• context <any> 发送给订阅者并绑定到存储区的讯息
• fn <Function> 在已进入的存储区上下文内运行的处理器
• thisArg <any> 用于函数调用的接收器。
• ...args <any> 传递给函数的可选参数。

在给定函数的持续时间内，将给定数据应用于绑定到通道的任何 AsyncLocalStorage 实例，然后在将数据应用于存储区的范围内发布到通道。

如果为channel.bindStore(store) 提供了转换函数，则会在其成为存储区的上下文值之前应用它来转换消息数据。在需要上下文链接的情况下，可以从转换函数中访问之前的存储上下文。

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

ESM

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' })
})

CJS

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

新增于: v19.9.0, v18.19.0

[稳定性: 1 - 实验性]

稳定性: 1 稳定性: 1 - 实验性

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

tracingChannel.subscribe(subscribers)

新增于: v19.9.0, v18.19.0

[稳定性: 1 - 实验性]

稳定性: 1 稳定性: 1 - 实验性

• subscribers <对象> TracingChannel 通道 订阅者的集合
  • start <函数> start 事件 订阅者
  • end <函数> end 事件 订阅者
  • asyncStart <函数> asyncStart 事件 订阅者
  • asyncEnd <函数> asyncEnd 事件 订阅者
  • error <函数> error 事件 订阅者

帮助将一系列函数订阅到相应的通道。这与分别对每个通道调用 channel.subscribe(onMessage) 相同。

ESM

import diagnostics_channel from 'node:diagnostics_channel'

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

channels.subscribe({
  start(message) {
    // 处理开始消息
  },
  end(message) {
    // 处理结束消息
  },
  asyncStart(message) {
    // 处理 asyncStart 消息
  },
  asyncEnd(message) {
    // 处理 asyncEnd 消息
  },
  error(message) {
    // 处理错误消息
  },
})

CJS

const diagnostics_channel = require('node:diagnostics_channel')

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

channels.subscribe({
  start(message) {
    // 处理开始消息
  },
  end(message) {
    // 处理结束消息
  },
  asyncStart(message) {
    // 处理 asyncStart 消息
  },
  asyncEnd(message) {
    // 处理 asyncEnd 消息
  },
  error(message) {
    // 处理错误消息
  },
})

tracingChannel.unsubscribe(subscribers)

新增于：v19.9.0, v18.19.0

[稳定性：1 - 实验性]

稳定性：1 稳定性：1 - 实验性

• subscribers <对象> 一组 TracingChannel 通道 订阅者

  • start <函数> start 事件 订阅者
  • end <函数> end 事件 订阅者
  • asyncStart <函数> asyncStart 事件 订阅者
  • asyncEnd <函数> asyncEnd 事件 订阅者
  • error <函数> error 事件 订阅者

• 返回值: <布尔值> 如果所有处理程序都成功取消订阅，则返回 true，否则返回 false。

帮助程序从相应的通道取消订阅函数集合。这与对每个通道分别调用 channel.unsubscribe(onMessage) 相同。

ESM

import diagnostics_channel from 'node:diagnostics_channel'

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

channels.unsubscribe({
  start(message) {
    // 处理 start 消息
  },
  end(message) {
    // 处理 end 消息
  },
  asyncStart(message) {
    // 处理 asyncStart 消息
  },
  asyncEnd(message) {
    // 处理 asyncEnd 消息
  },
  error(message) {
    // 处理 error 消息
  },
})

CJS

const diagnostics_channel = require('node:diagnostics_channel')

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

channels.unsubscribe({
  start(message) {
    // 处理 start 消息
  },
  end(message) {
    // 处理 end 消息
  },
  asyncStart(message) {
    // 处理 asyncStart 消息
  },
  asyncEnd(message) {
    // 处理 asyncEnd 消息
  },
  error(message) {
    // 处理 error 消息
  },
})

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

新增于：v19.9.0, v18.19.0

[稳定性：1 - 实验性]

稳定性：1 稳定性：1 - 实验性

• fn <函数> 用于包裹跟踪的函数
• context <对象> 用于关联事件的共享对象
• thisArg <任意> 用于函数调用的接收者
• ...args <任意> 传递给函数的可选参数
• 返回值: <任意> 给定函数的返回值

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

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

ESM

import diagnostics_channel from 'node:diagnostics_channel'

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

channels.traceSync(
  () => {
    // 执行某些操作
  },
  {
    some: 'thing',
  }
)

CJS

const diagnostics_channel = require('node:diagnostics_channel')

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

channels.traceSync(
  () => {
    // 执行某些操作
  },
  {
    some: 'thing',
  }
)

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

新增于：v19.9.0, v18.19.0

[稳定性：1 - 实验性]

稳定性：1 稳定性：1 - 实验性

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

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

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

ESM

import diagnostics_channel from 'node:diagnostics_channel'

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

channels.tracePromise(
  async () => {
    // 执行某些操作
  },
  {
    some: 'thing',
  }
)

CJS

const diagnostics_channel = require('node:diagnostics_channel')

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

channels.tracePromise(
  async () => {
    // 执行某些操作
  },
  {
    some: 'thing',
  }
)

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

新增于：v19.9.0, v18.19.0

[稳定性：1 - 实验性]

稳定性：1 稳定性：1 - 实验性

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

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

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

ESM

import diagnostics_channel from 'node:diagnostics_channel'

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

channels.traceCallback(
  (arg1, callback) => {
    // 执行某些操作
    callback(null, 'result')
  },
  1,
  {
    some: 'thing',
  },
  thisArg,
  arg1,
  callback
)

CJS

const diagnostics_channel = require('node:diagnostics_channel')

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

channels.traceCallback(
  (arg1, callback) => {
    // 执行某些操作
    callback(null, 'result')
  },
  1,
  {
    some: 'thing',
  },
  thisArg,
  arg1,
  callback
)

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

ESM

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

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

// start 通道将初始存储数据设置为某个值
// 并将该存储数据值存储在跟踪上下文对象上
channels.start.bindStore(myStore, data => {
  const span = new Span(data)
  data.span = span
  return span
})

// 然后 asyncStart 可以从之前存储的数据中恢复
channels.asyncStart.bindStore(myStore, data => {
  return data.span
})

CJS

const diagnostics_channel = require('node:diagnostics_channel')
const { AsyncLocalStorage } = require('node:async_hooks')

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

// start 通道将初始存储数据设置为某个值
// 并将该存储数据值存储在跟踪上下文对象上
channels.start.bindStore(myStore, data => {
  const span = new Span(data)
  data.span = span
  return span
})

// 然后 asyncStart 可以从之前存储的数据中恢复
channels.asyncStart.bindStore(myStore, data => {
  return data.span
})

tracingChannel.hasSubscribers

新增于: v22.0.0, v20.13.0

[稳定性: 1 - 实验性]

稳定性: 1 稳定性: 1 - 实验性

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

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

ESM

import diagnostics_channel from 'node:diagnostics_channel'

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

if (channels.hasSubscribers) {
  // 执行某些操作
}

CJS

const diagnostics_channel = require('node:diagnostics_channel')

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

if (channels.hasSubscribers) {
  // 执行某些操作
}

追踪通道 Channels

追踪通道 (TracingChannel) 是几个 diagnostics_channels 的集合，代表单个可追踪操作执行生命周期中的特定点。其行为分为五个 diagnostics_channels，分别为 start、end、asyncStart、asyncEnd 和 error。单个可追踪操作将在所有事件之间共享相同的事件对象，这对于通过弱映射管理关联很有帮助。

当任务“完成”时，这些事件对象将扩展 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)

• Name: tracing:${name}:start

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

end(event)

• Name: 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 事件，一个用于同步错误，一个用于异步错误。

内置通道

[稳定版: 1 - 实验性]

稳定版: 1 稳定性: 1 - 实验性

虽然 diagnostics_channel API 现在被认为是稳定的，但当前可用的内置通道并非如此。每个通道必须单独声明为稳定。

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>

服务器发送响应时发出。

模块

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.client.socket

• socket <net.Socket>

创建新的 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 套接字时发出。

进程

新增于：v16.18.0

child_process

• process <ChildProcess>

当创建新的进程时发出。

工作线程

新增于：v16.18.0

worker_threads

• worker Worker

当创建新的线程时发出。