Node.js v25.0.0 ドキュメンテーション

diagnostics_channel.hasSubscribers(name)#

• name <string> | <symbol> チャネル名
• 戻り値: <boolean> アクティブなサブスクライバがいる場合は true

指定された名前のチャネルにアクティブなサブスクライバがいるかどうかを確認します。これは、送信したいメッセージの準備にコストがかかる場合に役立ちます。

この 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> アクティブなサブスクライバがいる場合は true

このチャネルにアクティブなサブスクライバがいるかどうかを確認します。これは、送信したいメッセージの準備にコストがかかる場合に役立ちます。

この 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 イベント を生成することがあります。これは、start チャネルで channel.runStores(context, ...) を使用して指定された関数を実行します。これにより、すべてのイベントでバインドされたストアがこのトレースコンテキストに一致するように設定されます。

正しいトレースグラフのみが形成されるようにするため、イベントはトレースを開始する前にサブスクライバが存在する場合にのみ公開されます。トレースが開始された後に追加されたサブスクリプションは、そのトレースからの将来のイベントを受け取らず、将来のトレースのみが表示されます。

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

Promise を返す関数呼び出しをトレースします。これは常に、関数の同期部分の実行前後に start イベント と end イベント を生成し、Promise の継続に達したときに asyncStart イベント と asyncEnd イベント を生成します。また、指定された関数がエラーをスローしたり、返された Promise が拒否されたりした場合は、error イベント を生成することもあります。これは、start チャネルで channel.runStores(context, ...) を使用して指定された関数を実行します。これにより、すべてのイベントでバインドされたストアがこのトレースコンテキストに一致するように設定されます。

正しいトレースグラフのみが形成されるようにするため、イベントはトレースを開始する前にサブスクライバが存在する場合にのみ公開されます。トレースが開始された後に追加されたサブスクリプションは、そのトレースからの将来のイベントを受け取らず、将来のトレースのみが表示されます。

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 イベント を生成することもあります。これは、start チャネルで channel.runStores(context, ...) を使用して指定された関数を実行します。これにより、すべてのイベントでバインドされたストアがこのトレースコンテキストに一致するように設定されます。

正しいトレースグラフのみが形成されるようにするため、イベントはトレースを開始する前にサブスクライバが存在する場合にのみ公開されます。トレースが開始された後に追加されたサブスクリプションは、そのトレースからの将来のイベントを受け取らず、将来のトレースのみが表示されます。

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 のチャネル のいずれかにサブスクライバがいるかどうかを確認します。いずれかに少なくとも1つのサブスクライバがいる場合は 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 イベントは、関数呼び出しが値を返した時点を表します。非同期関数の場合、これは関数自体が内部で return 文を実行したときではなく、返された Promise が返されたときです。この時点で、トレースされた関数が同期的であった場合、result フィールドは関数の戻り値に設定されます。あるいは、error フィールドが存在して、スローされたエラーを表すことがあります。

トレース可能なアクションが複数のエラーを生成する可能性があるため、エラーを追跡するには特に error イベントをリッスンすることが推奨されます。例えば、失敗した非同期タスクが内部で開始された後、タスクの同期部分がエラーをスローする場合があります。

asyncStart(event)#

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

asyncStart イベントは、トレース可能な関数のコールバックまたは継続に到達した時点を表します。この時点では、コールバック引数や、アクションの「結果」を表すものが利用可能になる場合があります。

コールバックベースの関数の場合、コールバックの最初の引数は undefined または null でない場合 error フィールドに割り当てられ、2番目の引数は 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 イベントがトリガーされます。

単一のトレース可能な関数呼び出しが複数回エラーを生成する可能性があるため、このイベントを利用する際にはこの点を考慮する必要があります。例えば、内部でトリガーされた別の非同期タスクが失敗し、その後関数の同期部分がエラーをスローした場合、同期エラーと非同期エラーのために2つの error イベントが発行されます。

コンソール#

HTTP#

HTTP/2#

モジュール#

NET#

UDP#

プロセス#

ワーカースレッド#