Diagnostics Channel

[履歴]

バージョン	変更点
v19.2.0, v18.13.0	diagnostics_channel が Stable になりました。
v15.1.0, v14.17.0	追加: v15.1.0, v14.17.0

[安定版: 2 - 安定]

安定版: 2 安定版: 2 - 安定

ソースコード: lib/diagnostics_channel.js

node:diagnostics_channel モジュールは、診断目的で任意のメッセージデータを報告するための名前付きチャネルを作成する API を提供します。

これは以下を使用してアクセスできます:

ESMCJS

import diagnostics_channel from 'node:diagnostics_channel';

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

診断メッセージを報告したいモジュール作成者は、メッセージを報告するために 1 つまたは複数のトップレベルチャネルを作成することを目的としています。チャネルは実行時に取得することもできますが、それを行うと追加のオーバーヘッドが発生するため、推奨されません。チャネルは便宜上エクスポートできますが、名前がわかっている限り、どこでも取得できます。

モジュールが他の人が使用する診断データを生成することを意図している場合は、どの名前付きチャネルが使用されているか、およびメッセージデータの形状に関するドキュメントを含めることをお勧めします。チャネル名には、他のモジュールからのデータとの衝突を避けるために、通常、モジュール名を含める必要があります。

公開 API

概要

以下は、公開 API の簡単な概要です。

ESMCJS

import diagnostics_channel from 'node:diagnostics_channel';

// 再利用可能なチャネルオブジェクトを取得
const channel = diagnostics_channel.channel('my-channel');

function onMessage(message, name) {
  // データを受信
}

// チャネルをサブスクライブ
diagnostics_channel.subscribe('my-channel', onMessage);

// チャネルにアクティブなサブスクライバーがいるかどうかを確認
if (channel.hasSubscribers) {
  // チャネルにデータを公開
  channel.publish({
    some: 'data',
  });
}

// チャネルのサブスクライブを解除
diagnostics_channel.unsubscribe('my-channel', onMessage);

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

// 再利用可能なチャネルオブジェクトを取得
const channel = diagnostics_channel.channel('my-channel');

function onMessage(message, name) {
  // データを受信
}

// チャネルをサブスクライブ
diagnostics_channel.subscribe('my-channel', onMessage);

// チャネルにアクティブなサブスクライバーがいるかどうかを確認
if (channel.hasSubscribers) {
  // チャネルにデータを公開
  channel.publish({
    some: 'data',
  });
}

// チャネルのサブスクライブを解除
diagnostics_channel.unsubscribe('my-channel', onMessage);

`diagnostics_channel.hasSubscribers(name)`

追加: v15.1.0, v14.17.0

name <string> | <symbol> チャネル名
戻り値: <boolean> アクティブなサブスクライバーがいるかどうか

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

このAPIはオプションですが、非常にパフォーマンスが重要なコードからメッセージを公開しようとする場合に役立ちます。

ESMCJS

import diagnostics_channel from 'node:diagnostics_channel';

if (diagnostics_channel.hasSubscribers('my-channel')) {
  // サブスクライバーがいるため、メッセージを準備して公開します
}

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

if (diagnostics_channel.hasSubscribers('my-channel')) {
  // サブスクライバーがいるため、メッセージを準備して公開します
}

`diagnostics_channel.channel(name)`

追加: v15.1.0, v14.17.0

name <string> | <symbol> チャネル名
戻り値: <Channel> 指定されたチャネルオブジェクト

これは、名前付きチャネルに公開したい人にとっての主要なエントリポイントです。可能な限りパブリッシュ時のオーバーヘッドを削減するように最適化されたチャネルオブジェクトを生成します。

ESMCJS

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

追加: v18.7.0, v16.17.0

name <string> | <symbol> チャネル名
onMessage <Function> チャネルメッセージを受信するハンドラー
- message <any> メッセージデータ
- name <string> | <symbol> チャネルの名前

このチャネルをサブスクライブするためのメッセージハンドラーを登録します。このメッセージハンドラーは、メッセージがチャネルに公開されるたびに同期的に実行されます。メッセージハンドラーでスローされたエラーは、'uncaughtException' をトリガーします。

ESMCJS

import diagnostics_channel from 'node:diagnostics_channel';

diagnostics_channel.subscribe('my-channel', (message, name) => {
  // データを受信しました
});

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

diagnostics_channel.subscribe('my-channel', (message, name) => {
  // データを受信しました
});

`diagnostics_channel.unsubscribe(name, onMessage)`

追加: v18.7.0, v16.17.0

name <string> | <symbol> チャネル名
onMessage <Function> 削除する以前にサブスクライブしたハンドラー
戻り値: <boolean> ハンドラーが見つかった場合はtrue、そうでない場合はfalse。

diagnostics_channel.subscribe(name, onMessage)で以前にこのチャネルに登録されたメッセージハンドラーを削除します。

ESMCJS

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

`diagnostics_channel.tracingChannel(nameOrChannels)`

追加: v19.9.0, v18.19.0

[安定版: 1 - 試験的]

安定版: 1 安定性: 1 - 試験的

nameOrChannels <string> | <TracingChannel> チャネル名またはすべてのTracingChannel Channelsを含むオブジェクト
戻り値: <TracingChannel> トレースするチャネルのコレクション

指定されたTracingChannel ChannelsのTracingChannelラッパーを作成します。名前が与えられた場合、対応するトレースチャネルはtracing:${name}:${eventType}の形式で作成されます。ここで、eventTypeはTracingChannel Channelsのタイプに対応します。

ESMCJS

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:end'),
  error: diagnostics_channel.channel('tracing:my-channel:error'),
});

クラス: `Channel`

追加: v15.1.0, v14.17.0

クラス Channel は、データパイプライン内の個々の名前付きチャネルを表します。これは、サブスクライバーを追跡し、サブスクライバーが存在する場合にメッセージを公開するために使用されます。公開時のチャネル検索を回避するために、個別のオブジェクトとして存在し、非常に高速な公開速度を可能にし、非常に最小限のコストで大量の使用を可能にします。チャネルはdiagnostics_channel.channel(name)で作成され、new Channel(name) でチャネルを直接構築することはサポートされていません。

`channel.hasSubscribers`

追加: v15.1.0, v14.17.0

戻り値: <boolean> アクティブなサブスクライバーがいるかどうか

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

この API はオプションですが、パフォーマンスが非常に重要なコードからメッセージを公開しようとする場合に役立ちます。

ESMCJS

import diagnostics_channel from 'node:diagnostics_channel';

const channel = diagnostics_channel.channel('my-channel');

if (channel.hasSubscribers) {
  // サブスクライバーがいるため、メッセージを準備して公開します
}

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

const channel = diagnostics_channel.channel('my-channel');

if (channel.hasSubscribers) {
  // サブスクライバーがいるため、メッセージを準備して公開します
}

`channel.publish(message)`

追加: v15.1.0, v14.17.0

message <any> チャネルサブスクライバーに送信するメッセージ

チャネルのサブスクライバーにメッセージを公開します。これにより、メッセージハンドラーが同期的にトリガーされ、同じコンテキスト内で実行されます。

ESMCJS

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

追加: v15.1.0, v14.17.0

非推奨: v18.7.0, v16.17.0以降

[安定版: 0 - 非推奨]

安定版: 0 安定版: 0 - 非推奨: diagnostics_channel.subscribe(name, onMessage) を使用してください

onMessage <Function> チャネルメッセージを受信するハンドラー
- message <any> メッセージデータ
- name <string> | <symbol> チャネルの名前

このチャネルを購読するために、メッセージハンドラーを登録します。このメッセージハンドラーは、メッセージがチャネルに公開されるたびに同期的に実行されます。メッセージハンドラーでスローされたエラーは、'uncaughtException'をトリガーします。

ESMCJS

import diagnostics_channel from 'node:diagnostics_channel';

const channel = diagnostics_channel.channel('my-channel');

channel.subscribe((message, name) => {
  // 受信したデータ
});

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

const channel = diagnostics_channel.channel('my-channel');

channel.subscribe((message, name) => {
  // 受信したデータ
});

`channel.unsubscribe(onMessage)`

[履歴]

バージョン	変更
v18.7.0, v16.17.0	非推奨: v18.7.0, v16.17.0以降
v17.1.0, v16.14.0, v14.19.0	戻り値を追加しました。サブスクライバーのいないチャネルに追加しました。
v15.1.0, v14.17.0	追加: v15.1.0, v14.17.0

[安定版: 0 - 非推奨]

安定版: 0 安定版: 0 - 非推奨: diagnostics_channel.unsubscribe(name, onMessage) を使用してください

onMessage <Function> 削除する、以前にサブスクライブしたハンドラー
戻り値: <boolean> ハンドラーが見つかった場合は true、それ以外の場合は false。

channel.subscribe(onMessage)を使用して、以前にこのチャネルに登録されたメッセージハンドラーを削除します。

ESMCJS

import diagnostics_channel from 'node:diagnostics_channel';

const channel = diagnostics_channel.channel('my-channel');

function onMessage(message, name) {
  // 受信したデータ
}

channel.subscribe(onMessage);

channel.unsubscribe(onMessage);

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

const channel = diagnostics_channel.channel('my-channel');

function onMessage(message, name) {
  // 受信したデータ
}

channel.subscribe(onMessage);

channel.unsubscribe(onMessage);

`channel.bindStore(store[, transform])`

Added in: v19.9.0, v18.19.0

[Stable: 1 - Experimental]

Stable: 1 Stability: 1 - 実験的

store <AsyncLocalStorage> コンテキストデータをバインドするストア
transform <Function> ストアコンテキストを設定する前にコンテキストデータを変換します。

channel.runStores(context, ...) が呼び出されると、指定されたコンテキストデータは、チャネルにバインドされているすべてのストアに適用されます。ストアがすでにバインドされている場合、以前の transform 関数は新しい関数に置き換えられます。指定されたコンテキストデータをコンテキストとして直接設定するために、transform 関数は省略できます。

ESMCJS

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

`channel.unbindStore(store)`

Added in: v19.9.0, v18.19.0

[Stable: 1 - Experimental]

Stable: 1 Stability: 1 - 実験的

store <AsyncLocalStorage> チャネルからバインド解除するストア。
戻り値: <boolean> ストアが見つかった場合は true、それ以外の場合は false。

channel.bindStore(store) で以前にこのチャネルに登録されたメッセージハンドラーを削除します。

ESMCJS

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

`channel.runStores(context, fn[, thisArg[, ...args]])`

追加: v19.9.0, v18.19.0

[安定版: 1 - 試験的]

安定版: 1 安定版: 1 - 試験的

context <any> サブスクライバーに送信し、ストアにバインドするメッセージ
fn <Function> 入力されたストレージコンテキスト内で実行するハンドラー
thisArg <any> 関数呼び出しに使用されるレシーバー。
...args <any> 関数に渡すオプションの引数。

指定された関数の期間中、チャネルにバインドされたAsyncLocalStorageインスタンスに指定されたデータを適用し、そのデータがストアに適用される範囲内でチャネルに公開します。

channel.bindStore(store) に変換関数が与えられた場合、メッセージデータがストアのコンテキスト値になる前に、メッセージデータを変換するために適用されます。コンテキストのリンクが必要な場合、変換関数内から前のストレージコンテキストにアクセスできます。

ストアに適用されたコンテキストは、指定された関数中に開始された実行から継続する非同期コードでアクセスできるはずですが、コンテキストの喪失が発生する状況もあります。

ESMCJS

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

クラス: `TracingChannel`

追加: v19.9.0, v18.19.0

[Stable: 1 - 実験的]

Stable: 1 Stability: 1 - 実験的

クラス TracingChannel は、単一の追跡可能なアクションをまとめて表現する TracingChannel Channels のコレクションです。これは、アプリケーションフローを追跡するためのイベントを生成するプロセスを形式化し、簡素化するために使用されます。diagnostics_channel.tracingChannel() は、TracingChannel を構築するために使用されます。Channel と同様に、TracingChannel を動的に作成するのではなく、ファイルのトップレベルで単一の TracingChannel を作成して再利用することをお勧めします。

`tracingChannel.subscribe(subscribers)`

追加: v19.9.0, v18.19.0

[Stable: 1 - 実験的]

Stable: 1 Stability: 1 - 実験的

subscribers <Object> TracingChannel Channels のサブスクライバーのセット
- start <Function> start イベントサブスクライバー
- end <Function> end イベントサブスクライバー
- asyncStart <Function> asyncStart イベントサブスクライバー
- asyncEnd <Function> asyncEnd イベントサブスクライバー
- error <Function> error イベントサブスクライバー

対応するチャネルに関数のコレクションをサブスクライブするためのヘルパー。これは、各チャネルで channel.subscribe(onMessage) を個別に呼び出すのと同じです。

ESMCJS

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

`tracingChannel.unsubscribe(subscribers)`

追加: v19.9.0, v18.19.0

[Stable: 1 - 実験的]

Stable: 1 Stability: 1 - 実験的

subscribers <Object> TracingChannel Channels サブスクライバーのセット
- start <Function> start イベントサブスクライバー
- end <Function> end イベントサブスクライバー
- asyncStart <Function> asyncStart イベントサブスクライバー
- asyncEnd <Function> asyncEnd イベントサブスクライバー
- error <Function> error イベントサブスクライバー
戻り値: <boolean> すべてのハンドラーが正常に登録解除された場合は true、それ以外の場合は false。

対応するチャネルから関数のコレクションを登録解除するためのヘルパーです。これは、各チャネルで個別に channel.unsubscribe(onMessage) を呼び出すのと同じです。

ESMCJS

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

`tracingChannel.traceSync(fn[, context[, thisArg[, ...args]]])`

Added in: v19.9.0, v18.19.0

[Stable: 1 - Experimental]

Stable: 1 安定度: 1 - 試験的

fn <Function> トレースでラップする関数
context <Object> イベントを関連付けるための共有オブジェクト
thisArg <any> 関数呼び出しで使用されるレシーバー
...args <any> 関数に渡すオプションの引数
戻り値: <any> 指定された関数の戻り値

同期関数呼び出しをトレースします。これは常に実行の前後でstart イベントとend イベントを生成し、指定された関数がエラーをスローした場合はerror イベントを生成することがあります。これは、channel.runStores(context, ...)をstartチャンネルで使って指定された関数を実行します。これにより、すべてのイベントがこのトレースコンテキストと一致するようにバインドされたストアを持つことが保証されます。

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

ESMCJS

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

`tracingChannel.tracePromise(fn[, context[, thisArg[, ...args]]])`

Added in: v19.9.0, v18.19.0

[Stable: 1 - Experimental]

Stable: 1 安定性: 1 - 試験的

fn <Function> トレースをラップする Promise を返す関数
context <Object> トレースイベントを関連付けるための共有オブジェクト
thisArg <any> 関数呼び出しで使用されるレシーバー
...args <any> 関数に渡すオプションの引数
戻り値: <Promise> 指定された関数から返された Promise からチェーンされたもの

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

ESMCJS

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

`tracingChannel.traceCallback(fn[, position[, context[, thisArg[, ...args]]]])`

Added in: v19.9.0, v18.19.0

[Stable: 1 - Experimental]

Stable: 1 安定版: 1 - 試験的

fn <Function> トレースをラップする関数を使用したコールバック
position <number> 期待されるコールバックのゼロから始まる引数の位置（undefined が渡された場合は最後の引数がデフォルト）
context <Object> トレースイベントを関連付ける共有オブジェクト（undefined が渡された場合は {} がデフォルト）
thisArg <any> 関数呼び出しに使用されるレシーバー
...args <any> 関数に渡す引数（コールバックを含む必要があります）
戻り値: <any> 指定された関数の戻り値

コールバックを受け取る関数呼び出しをトレースします。コールバックは通常使用されるエラーを最初の引数とする規約に従うことが期待されます。これは常に、関数実行の同期部分の周囲に start イベントおよび end イベントを生成し、コールバック実行の周囲に asyncStart イベントおよび asyncEnd イベントを生成します。指定された関数が例外をスローするか、コールバックに渡された最初の引数が設定されている場合は、error イベントを生成することもできます。これは、start チャネルで channel.runStores(context, ...) を使用して指定された関数を実行します。これにより、すべてのイベントに、このトレースコンテキストと一致するように設定されたバインドされたストアがあることが保証されます。

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

ESMCJS

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

コールバックも channel.runStores(context, ...) で実行されます。これにより、場合によってはコンテキストの損失を回復できます。

ESMCJS

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

`tracingChannel.hasSubscribers`

追加: v22.0.0, v20.13.0

[Stable: 1 - Experimental]

Stable: 1 Stability: 1 - 試験的

戻り値: <boolean> 個々のチャネルのいずれかにサブスクライバーが存在する場合は true、そうでない場合は false。

これは、TracingChannel Channelsのいずれかにサブスクライバーが存在するかどうかを確認するために、TracingChannelインスタンスで使用できるヘルパーメソッドです。いずれかに少なくとも 1 つのサブスクライバーが存在する場合は true が返され、そうでない場合は false が返されます。

ESMCJS

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
}

TracingChannel Channels

TracingChannel は、単一の追跡可能なアクションの実行ライフサイクルにおける特定のポイントを表す、いくつかの diagnostics_channels のコレクションです。動作は、start、end、asyncStart、asyncEnd、および error で構成される 5 つの diagnostics_channels に分割されます。単一の追跡可能なアクションは、すべてのイベント間で同じイベントオブジェクトを共有します。これは、weakmap を介した相関関係の管理に役立ちます。

これらのイベントオブジェクトは、タスクが「完了」すると、result または error の値で拡張されます。同期タスクの場合、result は戻り値になり、error は関数からスローされたものになります。コールバックベースの非同期関数では、result はコールバックの 2 番目の引数になり、error は end イベントで表示されるスローされたエラー、または asyncStart イベントまたは asyncEnd イベントのいずれかの最初のコールバック引数になります。

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

トレースチャネルは、次の命名パターンに従う必要があります。

tracing:module.class.method:start または tracing:module.function:start
tracing:module.class.method:end または tracing:module.function:end
tracing:module.class.method:asyncStart または tracing:module.function:asyncStart
tracing:module.class.method:asyncEnd または tracing:module.function:asyncEnd
tracing:module.class.method:error または tracing:module.function:error

`start(event)`

Name: tracing:${name}:start

start イベントは、関数が呼び出された時点を表します。この時点で、イベントデータには関数の引数、または関数の実行開始時に利用可能なその他のものが含まれている場合があります。

`end(event)`

Name: tracing:${name}:end

end イベントは、関数の呼び出しが値を返す時点を表します。非同期関数の場合、これは関数自体が内部で return ステートメントを作成したときではなく、返された Promise が解決されたときです。この時点で、トレースされた関数が同期的であった場合、result フィールドは関数の戻り値に設定されます。あるいは、スローされたエラーを表すために error フィールドが存在する場合があります。

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

`asyncStart(event)`

Name: tracing:${name}:asyncStart

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

コールバックベースの関数の場合、コールバックの最初の引数は、undefined または null でない場合、error フィールドに割り当てられ、2 番目の引数は result フィールドに割り当てられます。

Promise の場合、resolve パスへの引数は result に割り当てられ、reject パスへの引数は error に割り当てられます。

`asyncEnd(event)`

Name: tracing:${name}:asyncEnd

asyncEnd イベントは、非同期関数のコールバックが戻ることを表します。asyncStart イベントの後にイベントデータが変更される可能性は低いですが、コールバックが完了する時点を確認するのに役立つ場合があります。

`error(event)`

名前: tracing:${name}:error

error イベントは、トレース可能な関数が同期または非同期で生成したすべてのエラーを表します。トレースされた関数の同期部分でエラーがスローされた場合、エラーはイベントの error フィールドに割り当てられ、error イベントがトリガーされます。コールバックまたは Promise の拒否を通じて非同期的にエラーを受信した場合も、エラーはイベントの error フィールドに割り当てられ、error イベントがトリガーされます。

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

ビルトインチャネル

[Stable: 1 - Experimental]

Stable: 1 Stability: 1 - 実験的

diagnostics_channel APIは現在安定版と見なされていますが、現在利用可能なビルトインチャネルは安定版ではありません。各チャネルは個別に安定版として宣言される必要があります。

HTTP

http.client.request.created

request <http.ClientRequest>

クライアントがリクエストオブジェクトを作成したときに発生します。http.client.request.startとは異なり、このイベントはリクエストが送信される前に発生します。

http.client.request.start

request <http.ClientRequest>

クライアントがリクエストを開始したときに発生します。

http.client.request.error

request <http.ClientRequest>
error <Error>

クライアントリクエスト中にエラーが発生したときに発生します。

http.client.response.finish

request <http.ClientRequest>
response <http.IncomingMessage>

クライアントがレスポンスを受信したときに発生します。

http.server.request.start

サーバーがリクエストを受信したときに発生します。

http.server.response.created

request <http.IncomingMessage>
response <http.ServerResponse>

サーバーがレスポンスを作成したときに発生します。イベントはレスポンスが送信される前に発生します。

http.server.response.finish

サーバーがレスポンスを送信したときに発生します。

モジュール

module.require.start

event <Object> 次のプロパティを含む
- id - require() に渡された引数。モジュール名。
- parentFilename - require(id) を試みたモジュールの名前。

require() が実行されると発生します。start イベントを参照してください。

module.require.end

event <Object> 次のプロパティを含む
- id - require() に渡された引数。モジュール名。
- parentFilename - require(id) を試みたモジュールの名前。

require() の呼び出しが返されると発生します。end イベントを参照してください。

module.require.error

event <Object> 次のプロパティを含む
- id - require() に渡された引数。モジュール名。
- parentFilename - require(id) を試みたモジュールの名前。
error <Error>

require() がエラーをスローすると発生します。error イベントを参照してください。

module.import.asyncStart

event <Object> 次のプロパティを含む
- id - import() に渡された引数。モジュール名。
- parentURL - import(id) を試みたモジュールの URL オブジェクト。

import() が呼び出されると発生します。asyncStart イベントを参照してください。

module.import.asyncEnd

event <Object> 次のプロパティを含む
- id - import() に渡された引数。モジュール名。
- parentURL - import(id) を試みたモジュールの URL オブジェクト。

import() が完了すると発生します。asyncEnd イベントを参照してください。

module.import.error

event <Object> 次のプロパティを含む
- id - import() に渡された引数。モジュール名。
- parentURL - import(id) を試みたモジュールの URL オブジェクト。
error <Error>

import() がエラーをスローすると発生します。error イベントを参照してください。

NET

net.client.socket

socket <net.Socket>

新しい TCP またはパイプのクライアントソケットが作成されたときに発生します。

net.server.socket

socket <net.Socket>

新しい TCP またはパイプの接続を受信したときに発生します。

tracing:net.server.listen:asyncStart

server <net.Server>
options <Object>

net.Server.listen() が呼び出されたときに、ポートまたはパイプが実際に設定される前に発生します。

tracing:net.server.listen:asyncEnd

server <net.Server>

net.Server.listen() が完了し、サーバーが接続を受け入れる準備ができたときに発生します。

tracing:net.server.listen:error

server <net.Server>
error <Error>

net.Server.listen() がエラーを返すときに発生します。

UDP

udp.socket

socket <dgram.Socket>

新しい UDP ソケットが作成されたときに発生します。

Process

Added in: v16.18.0

child_process

process <ChildProcess>

新しいプロセスが作成されたときに発生します。

Worker Thread

Added in: v16.18.0

worker_threads

worker Worker

新しいスレッドが作成されたときに発生します。

Diagnostics Channel ​

公開 API ​

概要 ​

diagnostics_channel.hasSubscribers(name) ​

diagnostics_channel.channel(name) ​

diagnostics_channel.subscribe(name, onMessage) ​

diagnostics_channel.unsubscribe(name, onMessage) ​

diagnostics_channel.tracingChannel(nameOrChannels) ​

クラス: Channel ​

channel.hasSubscribers ​

channel.publish(message) ​

channel.subscribe(onMessage) ​

channel.unsubscribe(onMessage) ​

channel.bindStore(store[, transform]) ​

channel.unbindStore(store) ​

channel.runStores(context, fn[, thisArg[, ...args]]) ​

クラス: TracingChannel ​

tracingChannel.subscribe(subscribers) ​

tracingChannel.unsubscribe(subscribers) ​

tracingChannel.traceSync(fn[, context[, thisArg[, ...args]]]) ​

tracingChannel.tracePromise(fn[, context[, thisArg[, ...args]]]) ​

tracingChannel.traceCallback(fn[, position[, context[, thisArg[, ...args]]]]) ​

tracingChannel.hasSubscribers ​

TracingChannel Channels ​

start(event) ​

end(event) ​

asyncStart(event) ​

asyncEnd(event) ​

error(event) ​

ビルトインチャネル ​

HTTP ​

モジュール ​

NET ​

UDP ​

Process ​

Worker Thread ​

Diagnostics Channel

公開 API

概要

`diagnostics_channel.hasSubscribers(name)`

`diagnostics_channel.channel(name)`

`diagnostics_channel.subscribe(name, onMessage)`

`diagnostics_channel.unsubscribe(name, onMessage)`

`diagnostics_channel.tracingChannel(nameOrChannels)`

クラス: `Channel`

`channel.hasSubscribers`

`channel.publish(message)`

`channel.subscribe(onMessage)`

`channel.unsubscribe(onMessage)`

`channel.bindStore(store[, transform])`

`channel.unbindStore(store)`

`channel.runStores(context, fn[, thisArg[, ...args]])`

クラス: `TracingChannel`

`tracingChannel.subscribe(subscribers)`

`tracingChannel.unsubscribe(subscribers)`

`tracingChannel.traceSync(fn[, context[, thisArg[, ...args]]])`

`tracingChannel.tracePromise(fn[, context[, thisArg[, ...args]]])`

`tracingChannel.traceCallback(fn[, position[, context[, thisArg[, ...args]]]])`

`tracingChannel.hasSubscribers`

TracingChannel Channels

`start(event)`

`end(event)`

`asyncStart(event)`

`asyncEnd(event)`

`error(event)`

ビルトインチャネル

HTTP

モジュール

NET

UDP

Process

Worker Thread