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

トレースイベント#

ソースコード: 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: Performance API の計測値のキャプチャを有効にします。
  • node.perf.usertiming: Performance API の User Timing のメジャーとマークのみのキャプチャを有効にします。
  • node.perf.timerify: Performance API の timerify の計測値のみのキャプチャを有効にします。
• node.promises.rejections: 未処理の Promise の拒否 (rejection) と、後から処理された拒否 (handled-after-rejection) の数を追跡するトレースデータのキャプチャを有効にします。
• 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 copy

以前のバージョンの 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 copy

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

import { createTracing } from 'node:trace_events';
const tracing = createTracing({ categories: ['node.perf'] });
tracing.enable();  // Enable trace event capture for the 'node.perf' category

// do work

tracing.disable();  // Disable trace event capture for the 'node.perf' categoryconst { createTracing } = require('node:trace_events');
const tracing = createTracing({ categories: ['node.perf'] });
tracing.enable();  // Enable trace event capture for the 'node.perf' category

// do work

tracing.disable();  // Disable trace event capture for the 'node.perf' categorycopy

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

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

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

SIGINT、SIGTERM、または SIGBREAK のようなシグナルイベントの後でもログファイルが適切に生成されることを保証するために、次のように、コードに適切なハンドラがあることを確認してください。

process.on('SIGINT', function onSigint() {
  console.info('Received SIGINT.');
  process.exit(130);  // Or applicable exit code depending on OS and signal
}); copy

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

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

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

// Prints 'node,node.perf,v8'
console.log(getEnabledCategories());

t2.disable(); // Will only disable emission of the 'node.perf' category

// Prints 'node,v8'
console.log(getEnabledCategories());const { createTracing, getEnabledCategories } = require('node:trace_events');
const t1 = createTracing({ categories: ['node', 'v8'] });
const t2 = createTracing({ categories: ['node.perf', 'node'] });
t1.enable();
t2.enable();

// Prints 'node,node.perf,v8'
console.log(getEnabledCategories());

t2.disable(); // Will only disable emission of the 'node.perf' category

// Prints 'node,v8'
console.log(getEnabledCategories());copy

import { createTracing } from 'node:trace_events';
const categories = ['node.perf', 'node.async_hooks'];
const tracing = createTracing({ categories });
tracing.enable();
// do stuff
tracing.disable();const { createTracing } = require('node:trace_events');
const categories = ['node.perf', 'node.async_hooks'];
const tracing = createTracing({ categories });
tracing.enable();
// do stuff
tracing.disable();copy

import { createTracing, getEnabledCategories } from 'node:trace_events';
const t1 = createTracing({ categories: ['node.async_hooks'] });
const t2 = createTracing({ categories: ['node.perf'] });
const t3 = createTracing({ categories: ['v8'] });

t1.enable();
t2.enable();

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

t1.enable();
t2.enable();

console.log(getEnabledCategories());copy

import { Session } from '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();'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();copy