トレースイベント

[安定版: 1 - 実験的]

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

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

node:trace_events モジュールは、V8、Node.js コア、およびユーザースペースコードによって生成されたトレース情報を一元管理するメカニズムを提供します。

トレースは、--trace-event-categories コマンドラインフラグを使用するか、node:trace_events モジュールを使用することで有効にできます。--trace-event-categories フラグは、コンマ区切りのカテゴリ名のリストを受け入れます。

使用可能なカテゴリは次のとおりです。

• node: 空のプレースホルダー。

• node.async_hooks: 詳細なasync_hooks トレースデータのキャプチャを有効にします。async_hooks イベントは一意の asyncId と特別な triggerId triggerAsyncId プロパティを持ちます。

• node.bootstrap: Node.js ブートストラップの主要なイベントのキャプチャを有効にします。

• node.console: console.time() と console.count() の出力のキャプチャを有効にします。

• node.threadpoolwork.sync: blob、zlib、crypto、node_api などのスレッドプール同期操作のトレースデータのキャプチャを有効にします。

• node.threadpoolwork.async: blob、zlib、crypto、node_api などのスレッドプール非同期操作のトレースデータのキャプチャを有効にします。

• node.dns.native: DNS クエリに関するトレースデータのキャプチャを有効にします。

• node.net.native: ネットワークに関するトレースデータのキャプチャを有効にします。

• node.environment: Node.js 環境の主要なイベントのキャプチャを有効にします。

• node.fs.sync: ファイルシステム同期メソッドに関するトレースデータのキャプチャを有効にします。

• node.fs_dir.sync: ファイルシステム同期ディレクトリメソッドに関するトレースデータのキャプチャを有効にします。

• node.fs.async: ファイルシステム非同期メソッドに関するトレースデータのキャプチャを有効にします。

• node.fs_dir.async: ファイルシステム非同期ディレクトリメソッドに関するトレースデータのキャプチャを有効にします。

• node.perf: パフォーマンス API 測定値のキャプチャを有効にします。

  • node.perf.usertiming: パフォーマンス API のユーザタイミング測定とマークのみのキャプチャを有効にします。
  • node.perf.timerify: パフォーマンス API の timerify 測定値のみのキャプチャを有効にします。

• node.promises.rejections: 未処理の Promise 拒否と拒否後の処理の数を追跡するトレースデータのキャプチャを有効にします。

• node.vm.script: node:vm モジュールの runInNewContext()、runInContext()、runInThisContext() メソッドに関するトレースデータのキャプチャを有効にします。

• v8: V8 イベントは、GC、コンパイル、および実行関連です。

• node.http: http リクエスト/レスポンスに関するトレースデータのキャプチャを有効にします。

• node.module_timer: CJS モジュールの読み込みに関するトレースデータのキャプチャを有効にします。

デフォルトでは、node、node.async_hooks、v8 カテゴリが有効になっています。

node --trace-event-categories v8,node,node.async_hooks server.js

以前のバージョンの Node.js では、トレースイベントを有効にするために--trace-events-enabledフラグを使用する必要がありました。この要件は削除されました。ただし、--trace-events-enabledフラグは使用可能であり、デフォルトでnode、node.async_hooks、v8トレースイベントカテゴリを有効にします。

node --trace-events-enabled

# は次のものと同等です {#is-equivalent-to}

node --trace-event-categories v8,node,node.async_hooks

または、node:trace_events モジュールを使用してトレースイベントを有効にすることができます。

const trace_events = require('node:trace_events')
const tracing = trace_events.createTracing({ categories: ['node.perf'] })
tracing.enable() // 'node.perf' カテゴリのトレースイベントキャプチャを有効にします

// 作業を実行

tracing.disable() // 'node.perf' カテゴリのトレースイベントキャプチャを無効にします

トレースを有効にして Node.js を実行すると、Chrome のchrome://tracingタブで開くことができるログファイルが生成されます。

ログファイルはデフォルトでnode_trace.${rotation}.logという名前で、${rotation}は増分ログローテーション ID です。ファイルパスのパターンは、${rotation}と${pid}をサポートするテンプレート文字列を受け入れる--trace-event-file-patternで指定できます。

node --trace-event-categories v8 --trace-event-file-pattern '${pid}-${rotation}.log' server.js

SIGINT、SIGTERM、SIGBREAKなどのシグナルイベントの後でログファイルが正しく生成されるようにするには、次のような適切なハンドラをコードに含めるようにしてください。

process.on('SIGINT', function onSigint() {
  console.info('SIGINTを受信しました。')
  process.exit(130) // OSとシグナルに応じて適切な終了コードを使用します
})

トレースシステムは、process.hrtime()で使用されているものと同じタイムソースを使用します。ただし、トレースイベントのタイムスタンプはマイクロ秒で表され、ナノ秒を返すprocess.hrtime()とは異なります。

このモジュールの機能は、Worker スレッドでは使用できません。

node:trace_events モジュール

追加されたバージョン: v10.0.0

Tracing オブジェクト

追加されたバージョン: v10.0.0

Tracing オブジェクトは、カテゴリのセットに対するトレースを有効または無効にするために使用されます。インスタンスは、trace_events.createTracing() メソッドを使用して作成されます。

作成されたとき、Tracing オブジェクトは無効になっています。tracing.enable() メソッドを呼び出すと、有効なトレースイベントカテゴリのセットにカテゴリが追加されます。tracing.disable() を呼び出すと、有効なトレースイベントカテゴリのセットからカテゴリが削除されます。

tracing.categories

追加されたバージョン: v10.0.0

• <string>

この Tracing オブジェクトが対象とするトレースイベントカテゴリのコンマ区切りのリスト。

tracing.disable()

追加されたバージョン: v10.0.0

この Tracing オブジェクトを無効にします。

他の有効な Tracing オブジェクトによって対象とされていないトレースイベントカテゴリ、および --trace-event-categories フラグで指定されていないトレースイベントカテゴリのみが無効になります。

const trace_events = require('node:trace_events')
const t1 = trace_events.createTracing({ categories: ['node', 'v8'] })
const t2 = trace_events.createTracing({ categories: ['node.perf', 'node'] })
t1.enable()
t2.enable()

// 'node,node.perf,v8' と出力します
console.log(trace_events.getEnabledCategories())

t2.disable() // 'node.perf' カテゴリの出力のみが無効になります

// 'node,v8' と出力します
console.log(trace_events.getEnabledCategories())

tracing.enable()

追加されたバージョン: v10.0.0

Tracing オブジェクトによって対象とされているカテゴリのセットに対して、この Tracing オブジェクトを有効にします。

tracing.enabled

追加されたバージョン: v10.0.0

• <boolean> Tracing オブジェクトが有効になっている場合のみ true。

trace_events.createTracing(options)

追加されたバージョン: v10.0.0

• options <Object>

  • categories <string[]> トレースカテゴリ名の配列。配列に含まれる値は、可能な限り文字列に変換されます。値を変換できない場合はエラーがスローされます。

• 戻り値: <Tracing>。

指定された categories のセットに対して Tracing オブジェクトを作成して返します。

const trace_events = require('node:trace_events')
const categories = ['node.perf', 'node.async_hooks']
const tracing = trace_events.createTracing({ categories })
tracing.enable()
// 何らかの処理
tracing.disable()

trace_events.getEnabledCategories()

追加: v10.0.0

• 戻り値: <string>

現在有効になっているすべてのトレースイベントカテゴリのカンマ区切りリストを返します。現在有効になっているトレースイベントカテゴリの集合は、現在有効になっているすべてのTracingオブジェクトと、--trace-event-categoriesフラグを使用して有効になっているすべてのカテゴリの和集合によって決定されます。

下記のtest.jsファイルの場合、コマンドnode --trace-event-categories node.perf test.jsは'node.async_hooks,node.perf'をコンソールに出力します。

const trace_events = require('node:trace_events')
const t1 = trace_events.createTracing({ categories: ['node.async_hooks'] })
const t2 = trace_events.createTracing({ categories: ['node.perf'] })
const t3 = trace_events.createTracing({ categories: ['v8'] })

t1.enable()
t2.enable()

console.log(trace_events.getEnabledCategories())

例

インスペクタによるトレースイベントデータの収集

'use strict'

const { Session } = require('node:inspector')
const session = new Session()
session.connect()

function post(message, data) {
  return new Promise((resolve, reject) => {
    session.post(message, data, (err, result) => {
      if (err) reject(new Error(JSON.stringify(err)))
      else resolve(result)
    })
  })
}

async function collect() {
  const data = []
  session.on('NodeTracing.dataCollected', chunk => data.push(chunk))
  session.on('NodeTracing.tracingComplete', () => {
    // done
  })
  const traceConfig = { includedCategories: ['v8'] }
  await post('NodeTracing.start', { traceConfig })
  // do something
  setTimeout(() => {
    post('NodeTracing.stop').then(() => {
      session.disconnect()
      console.log(data)
    })
  }, 1000)
}

collect()