Node.js v21.7.2 ドキュメント

node:trace_events モジュール#

Tracing オブジェクト#

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

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

tracing.categories#

• <文字列>

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

tracing.disable()#

この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();

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

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

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

tracing.enable()#

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

tracing.enabled#

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

trace_events.createTracing(options)#

• options <オブジェクト>
  • categories <文字列[]> トレースカテゴリ名の配列。配列に含まれる値は、可能な限り文字列に変換されます。値を変換できない場合はエラーがスローされます。
• 戻り値：<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();
// do stuff
tracing.disable(); copy

trace_events.getEnabledCategories()#

• 戻り値：<文字列>

現在有効になっているすべてのトレースイベントカテゴリのコンマ区切りのリストを返します。現在有効になっているトレースイベントカテゴリのセットは、現在有効になっているすべての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()); copy

例#

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

'use strict';

const { Session } = require('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