ドキュメント価格ブログ
お問い合わせ
ログイン無料で新規登録
Back to Tech Articles

Node.js async_hooks による非同期リソースライフサイクルの理解

8月 30, 2025
# Misc

Daniel Hayes

Full-Stack Engineer · Leapcell

この記事はEnglish、한국어、Deutschでも利用できます
Cover of "Node.js async_hooks による非同期リソースライフサイクルの理解"

はじめに

Node.js の世界では、非同期操作は基本的です。ファイル I/O からネットワークリクエストまで、ほぼすべての重要なインタラクションはノンブロッキング実行を伴います。このパラダイムは計り知れないパフォーマンス上の利点を提供しますが、複雑さももたらします。複数の非同期呼び出しにわたる実行フローの追跡は、特にメモリリーク、キャッチされないエラー、または予期しないイベントシーケンスに根ざしたパフォーマンスのボトルネックといった、把握しにくい問題のデバッグにおいて、手ごわい課題となり得ます。開発者は、突然変化するコールスタックや、予想よりも長く現存または持続するリソースと格闘することがよくあります。まさにここで Node.js の async_hooks が登場します。これらは、非同期リソースの完全なライフサイクルを観察するための比類なきメカニズムを提供し、非同期操作がどのように接続され管理されているかについての深い、詳細な理解を提供します。この記事では、async_hooks の実践的な応用について掘り下げ、それらを活用してアプリケーションの非同期動作に関する重要な洞察を得る方法を実証します。

Core Concepts of async_hooks

実際例に入る前に、async_hooks に関連するコアコンセプトと用語の基本的な理解を確立しましょう。

  • async_hooks module: この組み込み Node.js モジュールは、非同期リソースのライフタイムを追跡するための API を提供します。これにより、非同期操作のライフのさまざまなステージのコールバックを登録できます。

  • Asynchronous Resource: 後でコールバックが呼び出される関連オブジェクトを持つ任意のオブジェクト。例としては、setTimeout タイマー、ネットワークソケット、ファイルシステム操作、Promise などがあります。async_hooks は、これらの各リソースに一意の asyncId を割り当てます。

  • asyncId: 各非同期リソースに割り当てられた一意の識別子。この ID を使用すると、特定のリソースをそのライフサイクル全体にわたって追跡できます。

  • triggerAsyncId: 現在の非同期リソースの作成を引き起こした非同期リソースの asyncId。この概念は、非同期操作の完全な因果関係チェーンを構築するために不可欠です。

  • AsyncHook class: 非同期フックを作成するためのプライマリインターフェース。このクラスをインスタンス化し、さまざまなイベントタイプのコールバック函数を持つオブジェクトを指定します。

  • Lifecycle Events: async_hooks は 4 つの主要なライフサイクルイベントを公開します。

    • init(asyncId, type, triggerAsyncId, resource): 非同期リソースが初期化されたときに呼び出されます。ここで asyncId、リソースの type（例：「'Timeout'」、「'TCPWRAP'」、「'Promise'」）、それを開始した triggerAsyncId、および resource オブジェクト自体への参照を取得します。
    • before(asyncId): asyncId に関連付けられたコールバックが実行される直前に呼び出されます。
    • after(asyncId): asyncId に関連付けられたコールバックが完了した直後に呼び出されます。
    • destroy(asyncId): 非同期リソースが破棄され、ガベージコレクトされた、またはそれ以外の場合は不要になったときに呼び出されます。

  • executionAsyncId(): async_hooks の静的メソッドで、現在実行中のコールバックを持つリソースの asyncId を返します。これは、非同期コールバック内で実行される同期コードの コンテキスト を理解するのに非常に役立ちます。

  • executionAsyncResource(): 現在の実行コンテキストに関連付けられた resource オブジェクトを返します。

Tracing Asynchronous Flows

非同期操作のライフサイクルを追跡するために async_hooks を使用する方法を例示します。setTimeout および Promise を含む簡単な例から始めます。

const async_hooks = require('async_hooks');
const fs = require('fs');

// アクティブな非同期リソースに関する情報を格納するシンプルなマップ
const activeResources = new Map();

// async ID を付けてログを記録するためのヘルパー
function logWithAsyncId(message, asyncId = async_hooks.executionAsyncId()) {
  const resourceInfo = activeResources.get(asyncId);
  console.log(`[ID: ${asyncId}${resourceInfo ? `, Type: ${resourceInfo.type}` : ''}] ${message}`);
}

// 新しい AsyncHook インスタンスを作成
const asyncHook = async_hooks.createHook({
  init(asyncId, type, triggerAsyncId, resource) {
    activeResources.set(asyncId, { type, triggerAsyncId, resource });
    logWithAsyncId(`INIT ${type} (triggered by ${triggerAsyncId})`, asyncId);
  },
  before(asyncId) {
    logWithAsyncId(`BEFORE callback`);
  },
  after(asyncId) {
    logWithAsyncId(`AFTER callback`);
  },
  destroy(asyncId) {
    const resourceInfo = activeResources.get(asyncId);
    if (resourceInfo) {
      logWithAsyncId(`DESTROY ${resourceInfo.type}`, asyncId);
      activeResources.delete(asyncId);
    }
  },
});

// トラッキングイベントを開始するためにフックを有効化
asyncHook.enable();

// --- Application Logic ---

console.log('--- Start of Application ---');

// 例 1: 基本的な setTimeout
setTimeout(() => {
  logWithAsyncId('Timeout callback executed');
}, 100);

// 例 2: Promise チェーン
const myPromise = new Promise((resolve) => {
  logWithAsyncId('Inside Promise constructor (synchronous part)');
  setTimeout(() => {
    logWithAsyncId('Resolving promise after timeout');
    resolve('Promise Fulfillerd');
  }, 50);
});

myPromise.then((value) => {
  logWithAsyncId(`Promise then() callback: ${value}`);
  fs.readFile(__filename, 'utf8', (err, data) => {
    if (err) throw err;
    logWithAsyncId(`File read completed. First 20 chars: ${data.substring(0, 20)}`);
  });
});

// 例 3: 即時非同期操作
setImmediate(() => {
  logWithAsyncId('SetImmediate callback executed');
});

console.log('--- End of Application (synchronous part finished) ---');

// アプリケーションのシャットダウン時、またはトラッキングが不要になったときにフックを無効化
// asyncHook.disable();

このコードを実行すると、イベントの詳細なログが観察されます。

--- Start of Application ---
[ID: 1, Type: Timeout] INIT Timeout (triggered by 1) // グローバルコンテキスト ID は通常 1 です
[ID: 1] Inside Promise constructor (synchronous part)
[ID: 1, Type: Promise] INIT Promise (triggered by 1)
[ID: 1, Type: Timeout] INIT Timeout (triggered by 1)
[ID: 1, Type: Immediate] INIT Immediate (triggered by 1)
--- End of Application (synchronous part finished) ---
[ID: 4] BEFORE callback // setImmediate のコールバック
[ID: 4, Type: Immediate] DESTROY Immediate
[ID: 4] AFTER callback
[ID: 3] BEFORE callback // これは Promise のためのタイムアウトです
[ID: 3] Resolving promise after timeout
[ID: 5, Type: Promise] INIT Promise (triggered by 3) // Promise.then() は `then` の内部に新しい Promise を作成します
[ID: 3] AFTER callback
[ID: 2] BEFORE callback // これは最初の setTimeout です
[ID: 2] Timeout callback executed
[ID: 2, Type: Timeout] DESTROY Timeout
[ID: 2] AFTER callback
[ID: 5] BEFORE callback // これは Promise.then() コールバックです
[ID: 6, Type: FSREQCALLBACK] INIT FSREQCALLBACK (triggered by 5) // fs.readFile は FSREQCALLBACK を作成します
[ID: 5] AFTER callback
[ID: 6] BEFORE callback // これは fs.readFile コールバックです
[ID: 6] File read completed. First 20 chars: const async_hooks = 
[ID: 6, Type: FSREQCALLBACK] DESTROY FSREQCALLBACK
[ID: 6] AFTER callback
[ID: 5, Type: Promise] DESTROY Promise
[ID: 3, Type: Timeout] DESTROY Timeout
[ID: 1, Type: Promise] DESTROY Promise

この出力は、非同期操作のインターリーブされた性質と、async_hooks がそれらの作成、実行、破棄をどのように照らし出すかを示しています。triggerAsyncId が因果関係を理解するのに役立つことに注意してください。たとえば、Promise.then() リゾルバー (ID: 5) は、最初の Promise を解決した Timeout (ID: 3) によってトリガーされました。

Advanced Applications

Building a Causal Chain/Call Stack Reconstruction

async_hooks の最も強力な用途の 1 つは、非同期コールスタック、または因果関係チェーンを再構築することです。標準の Error.stack は、エラー発生時点までの同期コールパスのみを示します。async_hooks は、これらの同期セグメントを非同期境界を越えて接続できます。

const async_hooks = require('async_hooks');
const util = require('util');

const asyncIdToStack = new Map();
const asyncIdToResource = new Map();

const asyncHook = async_hooks.createHook({
  init(asyncId, type, triggerAsyncId, resource) {
    asyncIdToResource.set(asyncId, { type, triggerAsyncId });
    // 非同期リソース作成時点でスタックトレースをキャプチャ
    asyncIdToStack.set(asyncId, AsyncLocalStorage.currentStore ? AsyncLocalStorage.currentStore.get('stack') : new Error().stack);
  },
  destroy(asyncId) {
    asyncIdToStack.delete(asyncId);
    asyncIdToResource.delete(asyncId);
  }
}).enable();

function getCausalChain(rootAsyncId) {
  let currentId = rootAsyncId;
  const chain = [];
  while (currentId !== null && currentId !== undefined && currentId !== 0) { // 0 はしばしばルート ID です
    const resourceInfo = asyncIdToResource.get(currentId);
    if (!resourceInfo) break; // 未知または破棄されたリソースに到達しました
    
    chain.unshift({
      asyncId: currentId,
      type: resourceInfo.type,
      creationStack: asyncIdToStack.get(currentId) // リソース作成時のスタック
    });
    currentId = resourceInfo.triggerAsyncId;
  }
  return chain;
}

// "論理"スタックコンテキストを維持するために AsyncLocalStorage を使用
const { AsyncLocalStorage } = require('async_hooks');
const als = new AsyncLocalStorage();

function operationA() {
  return new Promise(resolve => {
    setTimeout(() => {
      console.log('Operation A completed.');
      resolve();
    }, 50);
  });
}

function operationB() {
  return new Promise(resolve => {
    setTimeout(() => {
      console.log('Operation B completed.');
      resolve();
    }, 20);
  });
}

async function mainFlow() {
  console.log('Starting main flow');
  await operationA();
  await operationB();
  console.log('Main flow completed.');

  // エラーを意図的にスローして因果関係チェーンを実証
  const error = new Error('Something went wrong in the main flow!');
  const currentAsyncId = async_hooks.executionAsyncId();
  console.error('
--- Tracing Error Context ---');
  console.error('Original Error Stack:', error.stack);
  console.error('
Causal Chain for current execution context:');
  const causalChain = getCausalChain(currentAsyncId);
  causalChain.forEach((entry, index) => {
    console.error(`
${' '.repeat(index * 2)}-> [Async ID: ${entry.asyncId}, Type: ${entry.type}] Created at:\n${util.inspect(entry.creationStack, { colors: true, depth: 3 }).replace(/^Error:\s*(\n)?/, '')}`);
  });
}

als.run(new Map([['stack', new Error().stack]]), () => {
    mainFlow();
});

この例では、AsyncLocalStorage（async_hooks の一部）を導入して、「論理」スタックトレースを非同期境界を越えて伝播させます。エラーが発生すると、triggerAsyncId チェーンをたどって、各操作の作成時点での同期スタックを含む、現在の実行につながった非同期操作のシーケンスを確認できます。これは、複雑な非同期インタラクションのデバッグに非常に強力です。

Performance Monitoring and Resource Leak Detection

init および destroy イベントを追跡することで、アプリケーションのアクティブな非同期リソースの数を監視できます。対応する destroy イベントなしに特定のタイプのリソースのカウントが常に増加している場合、リソースリーク（例：忘れられたタイマー、閉じられていない接続）を示している可能性があります。

const async_hooks = require('async_hooks');

const resourceCount = new Map();

const leakDetectorHook = async_hooks.createHook({
  init(asyncId, type) {
    resourceCount.set(type, (resourceCount.get(type) || 0) + 1);
    // console.log(`INIT: ${type}, Active: ${resourceCount.get(type)}`);
  },
  destroy(asyncId) {
    const resourceInfo = asyncIdToResource.get(asyncId); // 前の例の asyncIdToResource を想定
    if (resourceInfo && resourceInfo.type) {
      resourceCount.set(resourceInfo.type, resourceCount.get(resourceInfo.type) - 1);
      // console.log(`DESTROY: ${resourceInfo.type}, Active: ${resourceCount.get(resourceInfo.type)}`);
    }
  }
}).enable();

setInterval(() => {
  console.log('
--- Active Async Resources Snapshot ---');
  resourceCount.forEach((count, type) => {
    if (count > 0) {
      console.log(`${type}: ${count}`);
    }
  });

  // 潜在的なリークをシミュレート:
  // if (Math.random() > 0.8) {
  //   setTimeout(() => {}, 10 * 60 * 1000); // 非常に長期間持続するタイマー
  // }
}, 2000);

// ここにアプリケーションロジックを配置し、非同期リソースを生成します
setTimeout(() => console.log('Short timeout finished'), 100);
Promise.resolve().then(() => console.log('Promise resolved'));
new Promise(() => {}); // 解決されない Promise、管理されない場合の「リーク」をシミュレートします。

この単純化された例は、アクティブなリソースをカウントする方法を示しています。実際のシナリオでは、次のようなものを追加します。

  • asyncId から resource へのマッピングを destroy でより多くのコンテキストで格納します。
  • 特定のリソースタイプに対してしきい値とアラートを設定します。
  • 傾向を視覚化するために、オブザーバビリティツールと統合します。

Considerations and Best Practices

  • Performance Overhead: async_hooks は強力ですが、パフォーマンスコストが伴います。必要なく、高スループットのアプリケーションでグローバルに有効にすると、顕著なオーバーヘッドが発生する可能性があります。それらを賢明に使用し、必要ないときは無効にしてください。Node.js コアは async_hooks の最適化に多大な努力を払ってきましたが、コンテキストスイッチとコールバック実行には依然としていくらかのコストがかかります。
  • Context Loss: async_hooks の before および after コールバックは、アプリケーションコードとは別個の特別なコンテキストで実行されることに注意してください。これらのフック内で重い作業を行ったり、アプリケーション固有の状態とやり取りしたりすることは、慎重に管理されない限り避けてください。
  • Error Handling: async_hooks コールバック内でスローされたエラーは、Node.js プロセスをクラッシュさせる可能性があります。フックコールバックが堅牢であることを確認してください。
  • Debugging vs. Monitoring: async_hooks は、詳細なデバッグと複雑なフローの理解に優れています。一般的なパフォーマンス監視には、より高レベルのメトリックが適切である場合があります。しかし、複雑な問題を特定するには、async_hooks は不可欠です。
  • Integration with Tracing Libraries: OpenTelemetry のようなライブラリは、async_hooks を基盤として、非同期境界を越えてトレーシングコンテキストを自動的に伝播します。async_hooks を理解することは、そのようなツールを扱うための強力な基盤を提供します。

Conclusion

Node.js async_hooks は、アプリケーションの非同期ランタイムを観察および操作するための強力な低レベルメカニズムを提供します。非同期リソースのライフサイクルイベントを公開することにより、実行フローに関する比類なき洞察を提供し、開発者が堅牢なデバッグツールを構築し、高度なパフォーマンス分析を実行し、リソースリークを検出できるようにします。パフォーマンスコストが伴いますが、非同期操作の複雑なネットワークを解きほぐす能力により、複雑な Node.js アプリケーションを理解および最適化するための貴重な資産となります。async_hooks をマスターすることは、Node.js の非同期の心臓部を真に理解することを可能にします。

Share this article

HackerNews

More Posts from Leapcell

cover

TypeScriptにおけるInversifyJSまたはTSyringeを用いたIoCのマスター

cover

TSDocとTypeDocによるTypeScriptライブラリのドキュメント生成の合理化

Popular Posts