Node.js v18.16.0 文档


目录

诊断通道#

稳定性: 2 - 稳定

源代码: lib/diagnostics_channel.js

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

可以使用以下方式访问它:

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

希望报告诊断消息的模块编写者将创建一个或多个顶层通道来报告消息。 也可以在运行时获取通道,但由于这样做会产生额外的开销,因此不鼓励这样做。 为方便起见,可以导出通道,但只要知道名称,就可以在任何地方获取。

如果您打算让您的模块生成诊断数据以供其他人使用,建议您包含使用哪些命名通道的文档以及消息数据的形状。 通道名称通常应包括模块名称,以避免与其他模块的数据发生冲突。

公共接口#

概述#

以下是公共 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)#

检查指定通道是否有活跃订阅者。 如果您要发送的消息的准备成本可能很高,这将很有帮助。

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

diagnostics_channel.channel(name)#

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

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

注册消息处理程序以订阅此通道。 每当消息发布到通道时,此消息处理程序将同步运行。 消息处理程序中抛出的任何错误都将触发 '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) 注册到此通道的消息处理程序。

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

类: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
}

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

channel.subscribe(onMessage)#

注册消息处理程序以订阅此通道。 每当消息发布到通道时,此消息处理程序将同步运行。 消息处理程序中抛出的任何错误都将触发 '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) 注册到此通道的消息处理程序。

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

内置通道#

稳定性: 1 - 实验

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

HTTP#

http.client.request.start

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

http.client.response.finish

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

http.server.request.start

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

http.server.response.finish

服务器发送响应时触发。

net.client.socket

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

net.server.socket

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

udp.socket

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