Node.js v16.20.0 文档


诊断通道#

¥Diagnostics Channel

稳定性: 1 - 实验性的

¥Stability: 1 - Experimental

源代码: lib/diagnostics_channel.js

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

¥The node:diagnostics_channel module provides an API to create named channels to report arbitrary message data for diagnostics purposes.

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

¥It can be accessed using:

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

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

¥It is intended that a module writer wanting to report diagnostics messages will create one or many top-level channels to report messages through. Channels may also be acquired at runtime but it is not encouraged due to the additional overhead of doing so. Channels may be exported for convenience, but as long as the name is known it can be acquired anywhere.

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

¥If you intend for your module to produce diagnostics data for others to consume it is recommended that you include documentation of what named channels are used along with the shape of the message data. Channel names should generally include the module name to avoid collisions with data from other modules.

公共接口#

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

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

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

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

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

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

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

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

diagnostics_channel.unsubscribe(name, onMessage)#
  • name <string> | <symbol> 通道名称

    ¥name <string> | <symbol> The channel name

  • onMessage <Function> 要删除的先前订阅的处理程序

    ¥onMessage <Function> The previous subscribed handler to remove

  • 返回:<boolean> 如果找到处理程序则为 true,否则为 false

    ¥Returns: <boolean> true if the handler was found, false otherwise.

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

¥Remove a message handler previously registered to this channel with diagnostics_channel.subscribe(name, onMessage).

import diagnostics_channel from 'diagnostics_channel';

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

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

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

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

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

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

类: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> 如果有活跃订阅者

    ¥Returns: <boolean> If there are active subscribers

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

¥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> 要发送给通道订阅者的消息

    ¥message <any> The message to send to the channel subscribers

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

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

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

    ¥onMessage <Function> The previous subscribed handler to remove

  • 返回:<boolean> 如果找到处理程序则为 true,否则为 false

    ¥Returns: <boolean> true if the handler was found, false otherwise.

删除以前使用 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);

内置通道#

¥Built-in Channels

HTTP#

http.client.request.start

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

¥Emitted when client starts a request.

http.client.response.finish

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

¥Emitted when client receives a response.

http.server.request.start

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

¥Emitted when server receives a request.

http.server.response.finish

服务器发送响应时触发。

¥Emitted when server sends a response.

NET#

net.client.socket

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

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

net.server.socket

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

¥Emitted when a new TCP or pipe connection is received.

UDP#

udp.socket

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

¥Emitted when a new UDP socket is created.

进程#

¥Process

child_process

创建新进程时触发。

¥Emitted when a new process is created.

工作线程#

¥Worker Thread

worker_threads

创建新线程时触发。

¥Emitted when a new thread is created.

Node.js 中文网 - 粤ICP备13048890号