Diagnostics Channel

[履歴]

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

[安定版: 2 - 安定版]

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

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

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

以下を使用してアクセスできます。

ESM

import diagnostics_channel from 'node:diagnostics_channel'

CJS

const diagnostics_channel = require('node:diagnostics_channel')

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

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

公開 API

概要

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

ESM

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)

CJS

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 はオプションですが、非常にパフォーマンスが重視されるコードからメッセージを公開しようとする場合に役立ちます。

ESM

import diagnostics_channel from 'node:diagnostics_channel'

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

CJS

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> 名前付きチャンネルオブジェクト

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

ESM

import diagnostics_channel from 'node:diagnostics_channel'

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

CJS

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' をトリガーします。

ESM

import diagnostics_channel from 'node:diagnostics_channel'

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

CJS

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)で以前にこのチャネルに登録されたメッセージハンドラーを削除します。

ESM

import diagnostics_channel from 'node:diagnostics_channel'

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

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

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

CJS

const diagnostics_channel = require('node:diagnostics_channel')

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

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 チャネルを含むオブジェクト
• 戻り値: <TracingChannel> トレース対象のチャネルのコレクション

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

ESM

import diagnostics_channel from 'node:diagnostics_channel'

const channelsByName = diagnostics_channel.tracingChannel('my-channel')

// または...

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

CJS

const diagnostics_channel = require('node:diagnostics_channel')

const channelsByName = diagnostics_channel.tracingChannel('my-channel')

// または...

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

クラス: 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 はオプションですが、非常にパフォーマンスが重視されるコードからメッセージをパブリッシュしようとする場合に役立ちます。

ESM

import diagnostics_channel from 'node:diagnostics_channel'

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

if (channel.hasSubscribers) {
  // サブスクライバーが存在する場合、メッセージを準備してパブリッシュします
}

CJS

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> チャネルのサブスクライバーに送信するメッセージ

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

ESM

import diagnostics_channel from 'node:diagnostics_channel'

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

channel.publish({
  some: 'message',
})

CJS

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' をトリガーします。

ESM

import diagnostics_channel from 'node:diagnostics_channel'

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

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

CJS

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) でこのチャネルに以前登録されたメッセージハンドラーを削除します。

ESM

import diagnostics_channel from 'node:diagnostics_channel'

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

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

channel.subscribe(onMessage)

channel.unsubscribe(onMessage)

CJS

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

追加: v19.9.0, v18.19.0

[安定版: 1 - 実験的]

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

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

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

ESM

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

CJS

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)

追加: v19.9.0, v18.19.0

[安定版: 1 - 実験的]

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

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

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

ESM

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)

CJS

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) に変換関数が指定されている場合、ストアのコンテキスト値になる前に、メッセージデータを変換するために適用されます。コンテキストのリンクが必要な場合、変換関数内から前のストレージコンテキストにアクセスできます。

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

ESM

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

CJS

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

[安定版: 1 - 実験的]

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

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

tracingChannel.subscribe(subscribers)

追加: v19.9.0, v18.19.0

[安定版: 1 - 実験的]

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

• subscribers <Object> TracingChannel チャネル のサブスクライバーのセット
  • start <Function> start イベント のサブスクライバー
  • end <Function> end イベント のサブスクライバー
  • asyncStart <Function> asyncStart イベント のサブスクライバー
  • asyncEnd <Function> asyncEnd イベント のサブスクライバー
  • error <Function> error イベント のサブスクライバー

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

ESM

import diagnostics_channel from 'node:diagnostics_channel'

const channels = diagnostics_channel.tracingChannel('my-channel')

channels.subscribe({
  start(message) {
    // start メッセージを処理
  },
  end(message) {
    // end メッセージを処理
  },
  asyncStart(message) {
    // asyncStart メッセージを処理
  },
  asyncEnd(message) {
    // asyncEnd メッセージを処理
  },
  error(message) {
    // error メッセージを処理
  },
})

CJS

const diagnostics_channel = require('node:diagnostics_channel')

const channels = diagnostics_channel.tracingChannel('my-channel')

channels.subscribe({
  start(message) {
    // start メッセージを処理
  },
  end(message) {
    // end メッセージを処理
  },
  asyncStart(message) {
    // asyncStart メッセージを処理
  },
  asyncEnd(message) {
    // asyncEnd メッセージを処理
  },
  error(message) {
    // error メッセージを処理
  },
})

tracingChannel.unsubscribe(subscribers)

追加: v19.9.0, v18.19.0

[安定版: 1 - 実験的]

安定版: 1 安定版: 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) を呼び出すのと同じです。

ESM

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

CJS

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

追加: v19.9.0, v18.19.0

[安定版: 1 - 試験的]

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

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

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

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

ESM

import diagnostics_channel from 'node:diagnostics_channel'

const channels = diagnostics_channel.tracingChannel('my-channel')

channels.traceSync(
  () => {
    // 何かを行う
  },
  {
    some: 'thing',
  }
)

CJS

const diagnostics_channel = require('node:diagnostics_channel')

const channels = diagnostics_channel.tracingChannel('my-channel')

channels.traceSync(
  () => {
    // 何かを行う
  },
  {
    some: 'thing',
  }
)

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

追加: v19.9.0, v18.19.0

[Stable: 1 - 実験的]

Stable: 1 Stability: 1 - 実験的

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

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

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

ESM

import diagnostics_channel from 'node:diagnostics_channel'

const channels = diagnostics_channel.tracingChannel('my-channel')

channels.tracePromise(
  async () => {
    // 何かをする
  },
  {
    some: 'thing',
  }
)

CJS

const diagnostics_channel = require('node:diagnostics_channel')

const channels = diagnostics_channel.tracingChannel('my-channel')

channels.tracePromise(
  async () => {
    // 何かをする
  },
  {
    some: 'thing',
  }
)

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

追加: v19.9.0, v18.19.0

[安定版: 1 - 実験的]

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

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

コールバックを受け取る関数呼び出しをトレースします。コールバックは、通常使用されるように、最初のエラー引数の規則に従うことが期待されます。これにより、関数実行の同期部分の周りに常にstartイベントとendイベントが生成され、コールバック実行の周りにasyncStartイベントとasyncEndイベントが生成されます。また、指定された関数がスローされるか、コールバックに渡された最初の引数が設定された場合は、errorイベントを生成する可能性があります。これは、startチャネルで[channel.runStores(context, ...)]（/api/diagnostics_channel#channelrunstorescontext-fn-thisarg-args）を使用して指定された関数を実行します。これにより、すべてのイベントに、このトレースコンテキストに一致するように設定されたバインドストアがあることが保証されます。

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

ESM

import diagnostics_channel from 'node:diagnostics_channel'

const channels = diagnostics_channel.tracingChannel('my-channel')

channels.traceCallback(
  (arg1, callback) => {
    // 何かをする
    callback(null, 'result')
  },
  1,
  {
    some: 'thing',
  },
  thisArg,
  arg1,
  callback
)

CJS

const diagnostics_channel = require('node:diagnostics_channel')

const channels = diagnostics_channel.tracingChannel('my-channel')

channels.traceCallback(
  (arg1, callback) => {
    // 何かをする
    callback(null, 'result')
  },
  1,
  {
    some: 'thing',
  },
  thisArg,
  arg1,
  callback
)

コールバックは[channel.runStores(context, ...)]（/api/diagnostics_channel#channelrunstorescontext-fn-thisarg-args）でも実行され、これにより、場合によってはコンテキスト損失の回復が可能になります。

ESM

import diagnostics_channel from 'node:diagnostics_channel'
import { AsyncLocalStorage } from 'node:async_hooks'

const channels = diagnostics_channel.tracingChannel('my-channel')
const myStore = new AsyncLocalStorage()

// startチャネルは、初期ストアデータを何かに設定し
// そのストアデータ値をトレースコンテキストオブジェクトに格納します
channels.start.bindStore(myStore, data => {
  const span = new Span(data)
  data.span = span
  return span
})

// 次に、asyncStartは以前に保存したデータから復元できます
channels.asyncStart.bindStore(myStore, data => {
  return data.span
})

CJS

const diagnostics_channel = require('node:diagnostics_channel')
const { AsyncLocalStorage } = require('node:async_hooks')

const channels = diagnostics_channel.tracingChannel('my-channel')
const myStore = new AsyncLocalStorage()

// startチャネルは、初期ストアデータを何かに設定し
// そのストアデータ値をトレースコンテキストオブジェクトに格納します
channels.start.bindStore(myStore, data => {
  const span = new Span(data)
  data.span = span
  return span
})

// 次に、asyncStartは以前に保存したデータから復元できます
channels.asyncStart.bindStore(myStore, data => {
  return data.span
})

tracingChannel.hasSubscribers

追加: v22.0.0, v20.13.0

[安定版: 1 - 試験的]

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

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

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

ESM

import diagnostics_channel from 'node:diagnostics_channel'

const channels = diagnostics_channel.tracingChannel('my-channel')

if (channels.hasSubscribers) {
  // 何か処理を行う
}

CJS

const diagnostics_channel = require('node:diagnostics_channel')

const channels = diagnostics_channel.tracingChannel('my-channel')

if (channels.hasSubscribers) {
  // 何か処理を行う
}

TracingChannel チャネル

TracingChannel は、単一のトレース可能なアクションの実行ライフサイクルの特定の時点を表す複数の diagnostics_channel のコレクションです。動作は、start、end、asyncStart、asyncEnd、および error で構成される 5 つの diagnostics_channel に分割されます。単一のトレース可能なアクションは、すべてのイベント間で同じイベントオブジェクトを共有します。これは、弱マップを介した相関の管理に役立ちます。

これらのイベントオブジェクトは、タスクが「完了」したときに 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)

• 名前: 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 イベントが発行されます。1 つは同期エラー用、もう 1 つは非同期エラー用です。

ビルトインチャネル

[安定: 1 - 実験的]

安定: 1 安定: 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

• request <http.IncomingMessage>
• response <http.ServerResponse>
• socket <net.Socket>
• server <http.Server>

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

http.server.response.created

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

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

http.server.response.finish

• request <http.IncomingMessage>
• response <http.ServerResponse>
• socket <net.Socket>
• server <http.Server>

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

モジュール

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

追加: v16.18.0

child_process

• process <ChildProcess>

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

Worker Thread

追加: v16.18.0

worker_threads

• worker Worker

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