Node.js v25.0.0 文档

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.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> 用于函数调用的接收者。
• ...args <any> 传递给函数的可选参数。

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

如果向 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, (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.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> 返回 Promise 的函数，用于进行跟踪包装
• context <Object> 用于关联跟踪事件的共享对象
• thisArg <any> 用于函数调用的接收者
• ...args <any> 传递给函数的可选参数
• 返回: <Promise> 从给定函数返回的 promise 链接而来

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

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

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

start(event)#

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

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

end(event)#

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

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

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

asyncStart(event)#

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

asyncStart 事件代表到达可跟踪函数的回调或延续。此时，像回调参数这样的东西可能是可用的，或者任何其他表达操作“结果”的东西。

对于基于回调的函数，回调的第一个参数将被分配给 error 字段（如果不是 undefined 或 null），第二个参数将被分配给 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 事件，一个用于同步错误，一个用于异步错误。

控制台#

HTTP#

HTTP/2#

模块#

NET#

UDP#

进程#

工作线程#