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#

程序#

工作執行緒#