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

Promises API#

クラス: inspector.Session#

• 拡張: <EventEmitter>

inspector.Session は、V8 インスペクター バックエンドにメッセージをディスパッチし、メッセージ応答と通知を受信するために使用されます。

new inspector.Session()#

inspector.Session クラスの新しいインスタンスを作成します。インスペクター セッションは、メッセージをインスペクター バックエンドにディスパッチできるようになる前に、session.connect() を介して接続する必要があります。

Session を使用する場合、コンソール API によって出力されたオブジェクトは、手動で Runtime.DiscardConsoleEntries コマンドを実行しない限り解放されません。

イベント: 'inspectorNotification'#

• <Object> 通知メッセージオブジェクト

V8 インスペクターからの通知を受信したときに発生します。

session.on('inspectorNotification', (message) => console.log(message.method));
// Debugger.paused
// Debugger.resumed copy

注意点 同じスレッドのセッションでのブレークポイントはお勧めしません。 ブレークポイントのサポートを参照してください。

特定のメソッドを持つ通知のみをサブスクライブすることも可能です。

イベント: <inspector-protocol-method>;#

• <Object> 通知メッセージオブジェクト

メソッドフィールドが <inspector-protocol-method> 値に設定されたインスペクター通知を受信したときに発生します。

次のスニペットは、'Debugger.paused' イベントにリスナーをインストールし、プログラムの実行が中断された場合（たとえば、ブレークポイントを介して）、プログラムの中断の理由を出力します

session.on('Debugger.paused', ({ params }) => {
  console.log(params.hitBreakpoints);
});
// [ '/the/file/that/has/the/breakpoint.js:11:0' ] copy

注意点 同じスレッドのセッションでのブレークポイントはお勧めしません。 ブレークポイントのサポートを参照してください。

session.connect()#

セッションをインスペクターバックエンドに接続します。

session.connectToMainThread()#

セッションをメイン スレッド インスペクター バックエンドに接続します。この API がワーカー スレッドで呼び出されなかった場合、例外がスローされます。

session.disconnect()#

セッションをすぐに閉じます。保留中のすべてのメッセージ コールバックはエラーで呼び出されます。session.connect() を呼び出して、再度メッセージを送信できるようにする必要があります。再接続されたセッションは、有効になっているエージェントや構成されたブレークポイントなど、すべてのインスペクターの状態を失います。

session.post(method[, params])#

• method <string>
• params <Object>
• 戻り値: <Promise>

メッセージをインスペクター バックエンドに送信します。

import { Session } from 'node:inspector/promises';
try {
  const session = new Session();
  session.connect();
  const result = await session.post('Runtime.evaluate', { expression: '2 + 2' });
  console.log(result);
} catch (error) {
  console.error(error);
}
// Output: { result: { type: 'number', value: 4, description: '4' } } copy

V8 インスペクター プロトコルの最新バージョンは、Chrome DevTools プロトコル ビューアー に公開されています。

Node.js インスペクターは、V8 によって宣言されたすべての Chrome DevTools プロトコル ドメインをサポートします。Chrome DevTools プロトコル ドメインは、アプリケーションの状態を検査し、実行時イベントをリッスンするために使用されるランタイム エージェントの 1 つと対話するためのインターフェイスを提供します。

使用例#

デバッガーとは別に、DevTools プロトコルを介してさまざまな V8 プロファイラーを利用できます。

CPUプロファイラー#

これは、CPU プロファイラーの使用方法を示す例です。

import { Session } from 'node:inspector/promises';
import fs from 'node:fs';
const session = new Session();
session.connect();

await session.post('Profiler.enable');
await session.post('Profiler.start');
// Invoke business logic under measurement here...

// some time later...
const { profile } = await session.post('Profiler.stop');

// Write profile to disk, upload, etc.
fs.writeFileSync('./profile.cpuprofile', JSON.stringify(profile)); copy

ヒーププロファイラー#

これは、ヒープ プロファイラーの使用方法を示す例です。

import { Session } from 'node:inspector/promises';
import fs from 'node:fs';
const session = new Session();

const fd = fs.openSync('profile.heapsnapshot', 'w');

session.connect();

session.on('HeapProfiler.addHeapSnapshotChunk', (m) => {
  fs.writeSync(fd, m.params.chunk);
});

const result = await session.post('HeapProfiler.takeHeapSnapshot', null);
console.log('HeapProfiler.takeHeapSnapshot done:', result);
session.disconnect();
fs.closeSync(fd); copy

コールバック API#

クラス: inspector.Session#

• 拡張: <EventEmitter>

inspector.Session は、V8 インスペクター バックエンドにメッセージをディスパッチし、メッセージ応答と通知を受信するために使用されます。

new inspector.Session()#

inspector.Session クラスの新しいインスタンスを作成します。インスペクター セッションは、メッセージをインスペクター バックエンドにディスパッチできるようになる前に、session.connect() を介して接続する必要があります。

Session を使用する場合、コンソール API によって出力されたオブジェクトは、手動で Runtime.DiscardConsoleEntries コマンドを実行しない限り解放されません。

イベント: 'inspectorNotification'#

• <Object> 通知メッセージオブジェクト

V8 インスペクターからの通知を受信したときに発生します。

session.on('inspectorNotification', (message) => console.log(message.method));
// Debugger.paused
// Debugger.resumed copy

注意点 同じスレッドのセッションでのブレークポイントはお勧めしません。 ブレークポイントのサポートを参照してください。

特定のメソッドを持つ通知のみをサブスクライブすることも可能です。

イベント: <inspector-protocol-method>;#

• <Object> 通知メッセージオブジェクト

メソッドフィールドが <inspector-protocol-method> 値に設定されたインスペクター通知を受信したときに発生します。

次のスニペットは、'Debugger.paused' イベントにリスナーをインストールし、プログラムの実行が中断された場合（たとえば、ブレークポイントを介して）、プログラムの中断の理由を出力します

session.on('Debugger.paused', ({ params }) => {
  console.log(params.hitBreakpoints);
});
// [ '/the/file/that/has/the/breakpoint.js:11:0' ] copy

注意点 同じスレッドのセッションでのブレークポイントはお勧めしません。 ブレークポイントのサポートを参照してください。

session.connect()#

セッションをインスペクターバックエンドに接続します。

session.connectToMainThread()#

セッションをメイン スレッド インスペクター バックエンドに接続します。この API がワーカー スレッドで呼び出されなかった場合、例外がスローされます。

session.disconnect()#

セッションをすぐに閉じます。保留中のすべてのメッセージ コールバックはエラーで呼び出されます。session.connect() を呼び出して、再度メッセージを送信できるようにする必要があります。再接続されたセッションは、有効になっているエージェントや構成されたブレークポイントなど、すべてのインスペクターの状態を失います。

session.post(method[, params][, callback])#

• method <string>
• params <Object>
• callback <Function>

メッセージをインスペクター バックエンドに送信します。応答を受信すると、callback が通知されます。callback は、エラーとメッセージ固有の結果の 2 つのオプション引数を受け入れる関数です。

session.post('Runtime.evaluate', { expression: '2 + 2' },
             (error, { result }) => console.log(result));
// Output: { type: 'number', value: 4, description: '4' } copy

V8 インスペクター プロトコルの最新バージョンは、Chrome DevTools プロトコル ビューアー に公開されています。

Node.js インスペクターは、V8 によって宣言されたすべての Chrome DevTools プロトコル ドメインをサポートします。Chrome DevTools プロトコル ドメインは、アプリケーションの状態を検査し、実行時イベントをリッスンするために使用されるランタイム エージェントの 1 つと対話するためのインターフェイスを提供します。

V8 に HeapProfiler.takeHeapSnapshot または HeapProfiler.stopTrackingHeapObjects コマンドを送信するときに、reportProgress を true に設定することはできません。

使用例#

デバッガーとは別に、DevTools プロトコルを介してさまざまな V8 プロファイラーを利用できます。

CPUプロファイラー#

これは、CPU プロファイラーの使用方法を示す例です。

const inspector = require('node:inspector');
const fs = require('node:fs');
const session = new inspector.Session();
session.connect();

session.post('Profiler.enable', () => {
  session.post('Profiler.start', () => {
    // Invoke business logic under measurement here...

    // some time later...
    session.post('Profiler.stop', (err, { profile }) => {
      // Write profile to disk, upload, etc.
      if (!err) {
        fs.writeFileSync('./profile.cpuprofile', JSON.stringify(profile));
      }
    });
  });
}); copy

ヒーププロファイラー#

これは、ヒープ プロファイラーの使用方法を示す例です。

const inspector = require('node:inspector');
const fs = require('node:fs');
const session = new inspector.Session();

const fd = fs.openSync('profile.heapsnapshot', 'w');

session.connect();

session.on('HeapProfiler.addHeapSnapshotChunk', (m) => {
  fs.writeSync(fd, m.params.chunk);
});

session.post('HeapProfiler.takeHeapSnapshot', null, (err, r) => {
  console.log('HeapProfiler.takeHeapSnapshot done:', err, r);
  session.disconnect();
  fs.closeSync(fd);
}); copy

共通オブジェクト#

inspector.close()#

残りのすべての接続を閉じようとし、すべてが閉じられるまでイベント ループをブロックします。すべての接続が閉じられると、インスペクターを非アクティブ化します。

inspector.console#

• <Object> リモート インスペクター コンソールにメッセージを送信するオブジェクト。

require('node:inspector').console.log('a message'); copy

インスペクター コンソールには、Node.js コンソールとの API パリティはありません。

inspector.open([port[, host[, wait]]])#

• port <number> インスペクター接続をリッスンするポート。オプション。既定: CLI で指定されたもの。
• host <string> インスペクター接続をリッスンするホスト。オプション。既定: CLI で指定されたもの。
• wait <boolean> クライアントが接続するまでブロックします。オプション。既定: false。
• 戻り値: <Disposable> inspector.close() を呼び出す Disposable。

ホストとポートでインスペクターをアクティブ化します。node --inspect=[[host:]port] と同等ですが、node の起動後にプログラムで実行できます。

wait が true の場合、クライアントが検査ポートに接続し、フロー制御がデバッガークライアントに渡されるまでブロックします。

host パラメータの使用に関するセキュリティ警告を参照してください。

inspector.url()#

• 戻り値: <string> | <undefined>

アクティブなインスペクターの URL を返すか、存在しない場合は undefined を返します。

$ node --inspect -p 'inspector.url()'
Debugger listening on ws://127.0.0.1:9229/166e272e-7a30-4d09-97ce-f1c012b43c34
For help, see: https://node.dokyumento.jp/en/docs/inspector
ws://127.0.0.1:9229/166e272e-7a30-4d09-97ce-f1c012b43c34

$ node --inspect=localhost:3000 -p 'inspector.url()'
Debugger listening on ws://127.0.0.1:3000/51cf8d0e-3c36-4c59-8efd-54519839e56a
For help, see: https://node.dokyumento.jp/en/docs/inspector
ws://127.0.0.1:3000/51cf8d0e-3c36-4c59-8efd-54519839e56a

$ node -p 'inspector.url()'
undefined copy

inspector.waitForDebugger()#

クライアント（既存または後から接続されるもの）が Runtime.runIfWaitingForDebugger コマンドを送信するまでブロックします。

アクティブなインスペクターがない場合は例外がスローされます。

ブレークポイントのサポート#

Chrome DevTools Protocol の Debugger ドメインを使用すると、inspector.Session はプログラムにアタッチし、ブレークポイントを設定してコードをステップ実行できます。

ただし、session.connect() で接続された同じスレッドの inspector.Session でブレークポイントを設定することは、アタッチおよび一時停止されているプログラムがまさにデバッガー自身であるため、避ける必要があります。代わりに、session.connectToMainThread() でメインスレッドに接続し、ワーカースレッドでブレークポイントを設定するか、WebSocket 接続を介して Debugger プログラムに接続してみてください。