Inspector

[Stabil: 2 - Stabil]

Das Modul node:inspector bietet eine API zur Interaktion mit dem V8 Inspector.

Der Zugriff erfolgt über:

ESMCJS

import * as inspector from 'node:inspector/promises';

const inspector = require('node:inspector/promises');

oder

ESMCJS

import * as inspector from 'node:inspector';

const inspector = require('node:inspector');

Promises API

[Stabil: 1 - Experimentell]

Stabil: 1 Stabilität: 1 - Experimentell

Hinzugefügt in: v19.0.0

Klasse: `inspector.Session`

Erweitert: <EventEmitter>

Die inspector.Session wird verwendet, um Nachrichten an das V8 Inspector Back-End zu senden und Nachrichtenantworten und Benachrichtigungen zu empfangen.

`new inspector.Session()`

Hinzugefügt in: v8.0.0

Erstellt eine neue Instanz der Klasse inspector.Session. Die Inspector-Sitzung muss über session.connect() verbunden werden, bevor die Nachrichten an das Inspector-Backend gesendet werden können.

Wenn Session verwendet wird, wird das von der Console API ausgegebene Objekt erst freigegeben, wenn wir den Befehl Runtime.DiscardConsoleEntries manuell ausgeführt haben.

Ereignis: `'inspectorNotification'`

Hinzugefügt in: v8.0.0

<Object> Das Benachrichtigungsnachrichtenobjekt

Wird ausgegeben, wenn eine Benachrichtigung vom V8 Inspector empfangen wird.

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

Es ist auch möglich, nur Benachrichtigungen mit einer bestimmten Methode zu abonnieren:

Event: `<inspector-protocol-method>`; {#event-<inspector-protocol-method>;}

Hinzugefügt in: v8.0.0

<Object> Das Benachrichtigungsnachrichtenobjekt

Wird ausgelöst, wenn eine Inspector-Benachrichtigung empfangen wird, deren Methodenfeld auf den Wert \<inspector-protocol-method\> gesetzt ist.

Der folgende Codeausschnitt installiert einen Listener auf dem 'Debugger.paused'-Ereignis und gibt den Grund für die Programmaussetzung aus, wann immer die Programmausführung unterbrochen wird (z. B. durch Breakpoints):

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

`session.connect()`

Hinzugefügt in: v8.0.0

Verbindet eine Sitzung mit dem Inspector-Backend.

`session.connectToMainThread()`

Hinzugefügt in: v12.11.0

Verbindet eine Sitzung mit dem Inspector-Backend des Hauptthreads. Es wird eine Ausnahme ausgelöst, wenn diese API nicht in einem Worker-Thread aufgerufen wurde.

`session.disconnect()`

Hinzugefügt in: v8.0.0

Schließt die Sitzung sofort. Alle ausstehenden Nachrichten-Callbacks werden mit einem Fehler aufgerufen. session.connect() muss aufgerufen werden, um wieder Nachrichten senden zu können. Eine wiederverbundene Sitzung verliert den gesamten Inspector-Zustand, wie z. B. aktivierte Agents oder konfigurierte Breakpoints.

`session.post(method[, params])`

Hinzugefügt in: v19.0.0

method <string>
params <Object>
Rückgabe: <Promise>

Sendet eine Nachricht an das Inspector-Backend.

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);
}
// Ausgabe: { result: { type: 'number', value: 4, description: '4' } }

Die neueste Version des V8 Inspector-Protokolls wird im Chrome DevTools Protocol Viewer veröffentlicht.

Node.js Inspector unterstützt alle Chrome DevTools Protocol-Domänen, die von V8 deklariert werden. Die Chrome DevTools Protocol-Domäne bietet eine Schnittstelle zur Interaktion mit einem der Runtime-Agents, die verwendet werden, um den Anwendungsstatus zu inspizieren und auf die Laufzeitereignisse zu lauschen.

Beispielhafte Verwendung

Abgesehen vom Debugger sind verschiedene V8-Profiler über das DevTools-Protokoll verfügbar.

CPU-Profiler

Hier ist ein Beispiel, das die Verwendung des CPU-Profilers zeigt:

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');
// Hier die Business-Logik unter Messung aufrufen...

// Einige Zeit später...
const { profile } = await session.post('Profiler.stop');

// Profil auf die Festplatte schreiben, hochladen usw.
fs.writeFileSync('./profile.cpuprofile', JSON.stringify(profile));

Heap-Profiler

Hier ist ein Beispiel, das die Verwendung des Heap-Profilers zeigt:

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);

Callback-API

Klasse: `inspector.Session`

Erweitert: <EventEmitter>

Die inspector.Session wird verwendet, um Nachrichten an das V8-Inspektor-Backend zu senden und Nachrichtenantworten und Benachrichtigungen zu empfangen.

`new inspector.Session()`

Hinzugefügt in: v8.0.0

Erstellt eine neue Instanz der Klasse inspector.Session. Die Inspektorsitzung muss über session.connect() verbunden werden, bevor die Nachrichten an das Inspektor-Backend gesendet werden können.

Wenn Session verwendet wird, wird das von der Konsolen-API ausgegebene Objekt erst freigegeben, wenn wir manuell den Befehl Runtime.DiscardConsoleEntries ausgeführt haben.

Event: `'inspectorNotification'`

Hinzugefügt in: v8.0.0

<Object> Das Benachrichtigungsobjekt

Wird ausgelöst, wenn eine Benachrichtigung vom V8 Inspector empfangen wird.

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

Es ist auch möglich, nur Benachrichtigungen mit einer bestimmten Methode zu abonnieren:

Event: `<inspector-protocol-method>`; {#event-<inspector-protocol-method>;_1}

Hinzugefügt in: v8.0.0

<Object> Das Benachrichtigungsobjekt

Wird ausgelöst, wenn eine Inspector-Benachrichtigung empfangen wird, deren Method-Feld auf den Wert \<inspector-protocol-method\> gesetzt ist.

Das folgende Code-Snippet installiert einen Listener für das 'Debugger.paused' Ereignis und gibt den Grund für die Programmunterbrechung aus, wenn die Programmausführung unterbrochen wird (z. B. durch Breakpoints):

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

`session.connect()`

Hinzugefügt in: v8.0.0

Verbindet eine Sitzung mit dem Inspector-Backend.

`session.connectToMainThread()`

Hinzugefügt in: v12.11.0

Verbindet eine Sitzung mit dem Haupt-Thread Inspector Backend. Eine Ausnahme wird ausgelöst, wenn diese API nicht auf einem Worker-Thread aufgerufen wurde.

`session.disconnect()`

Hinzugefügt in: v8.0.0

Schließt die Sitzung sofort. Alle ausstehenden Nachrichten-Callbacks werden mit einem Fehler aufgerufen. session.connect() muss aufgerufen werden, um wieder Nachrichten senden zu können. Eine wiederverbundene Sitzung verliert alle Inspector-Zustände, wie z. B. aktivierte Agents oder konfigurierte Breakpoints.

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

[Verlauf]

Version	Änderungen
v18.0.0	Die Übergabe eines ungültigen Callbacks an das `callback`-Argument wirft jetzt `ERR_INVALID_ARG_TYPE` anstelle von `ERR_INVALID_CALLBACK`.
v8.0.0	Hinzugefügt in: v8.0.0

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

Sendet eine Nachricht an das Inspector-Backend. callback wird benachrichtigt, wenn eine Antwort empfangen wird. callback ist eine Funktion, die zwei optionale Argumente akzeptiert: error und nachrichtenspezifisches Ergebnis.

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

Die neueste Version des V8 Inspector-Protokolls ist im Chrome DevTools Protocol Viewer veröffentlicht.

Der Node.js Inspector unterstützt alle Chrome DevTools Protocol-Domänen, die von V8 deklariert werden. Die Chrome DevTools Protocol-Domäne bietet eine Schnittstelle zur Interaktion mit einem der Runtime-Agents, die verwendet werden, um den Anwendungsstatus zu inspizieren und auf die Runtime-Ereignisse zu hören.

Sie können reportProgress nicht auf true setzen, wenn Sie den Befehl HeapProfiler.takeHeapSnapshot oder HeapProfiler.stopTrackingHeapObjects an V8 senden.

Beispielhafte Verwendung

Abgesehen vom Debugger stehen über das DevTools-Protokoll verschiedene V8-Profiler zur Verfügung.

CPU-Profiler

Hier ist ein Beispiel, das die Verwendung des CPU-Profilers zeigt:

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', () => {
    // Hier die Geschäftslogik unter Messung aufrufen...

    // Etwas später...
    session.post('Profiler.stop', (err, { profile }) => {
      // Profil auf Festplatte schreiben, hochladen usw.
      if (!err) {
        fs.writeFileSync('./profile.cpuprofile', JSON.stringify(profile));
      }
    });
  });
});

Heap-Profiler

Hier ist ein Beispiel, das die Verwendung des Heap-Profilers zeigt:

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);
});

Allgemeine Objekte

`inspector.close()`

[Verlauf]

Version	Änderungen
v18.10.0	Die API wird in den Worker-Threads verfügbar gemacht.
v9.0.0	Hinzugefügt in: v9.0.0

Versucht, alle verbleibenden Verbindungen zu schließen und blockiert die Ereignisschleife, bis alle geschlossen sind. Sobald alle Verbindungen geschlossen sind, wird der Inspector deaktiviert.

`inspector.console`

<Object> Ein Objekt zum Senden von Nachrichten an die Remote-Inspector-Konsole.

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

Die Inspector-Konsole hat keine API-Parität mit der Node.js-Konsole.

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

[Verlauf]

Version	Änderungen
v20.6.0	inspector.open() gibt jetzt ein `Disposable`-Objekt zurück.

port <number> Port, auf dem auf Inspector-Verbindungen gewartet werden soll. Optional. Standard: was in der CLI angegeben wurde.
host <string> Host, auf dem auf Inspector-Verbindungen gewartet werden soll. Optional. Standard: was in der CLI angegeben wurde.
wait <boolean> Blockiert, bis ein Client verbunden ist. Optional. Standard: false.
Gibt zurück: <Disposable> Ein Disposable, das inspector.close() aufruft.

Aktiviert den Inspector auf Host und Port. Äquivalent zu node --inspect=[[host:]port], kann aber programmgesteuert erfolgen, nachdem Node gestartet wurde.

Wenn wait true ist, wird blockiert, bis ein Client sich mit dem Inspect-Port verbunden hat und die Ablaufsteuerung an den Debugger-Client übergeben wurde.

Siehe die Sicherheitswarnung bezüglich der Verwendung des host-Parameters.

`inspector.url()`

Gibt zurück: <string> | <undefined>

Gibt die URL des aktiven Inspectors zurück oder undefined, wenn kein Inspector vorhanden ist.

bash

$ node --inspect -p 'inspector.url()'
Debugger listening on ws://127.0.0.1:9229/166e272e-7a30-4d09-97ce-f1c012b43c34
For help, see: https://nodejs.org/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://localhost:3000/51cf8d0e-3c36-4c59-8efd-54519839e56a
For help, see: https://nodejs.org/en/docs/inspector
ws://localhost:3000/51cf8d0e-3c36-4c59-8efd-54519839e56a

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

`inspector.waitForDebugger()`

Hinzugefügt in: v12.7.0

Blockiert, bis ein Client (bestehender oder später verbundener) den Befehl Runtime.runIfWaitingForDebugger gesendet hat.

Es wird eine Ausnahme ausgelöst, wenn kein aktiver Inspektor vorhanden ist.

Integration mit DevTools

Das node:inspector-Modul bietet eine API zur Integration mit DevTools, die das Chrome DevTools Protocol unterstützen. DevTools-Frontends, die mit einer laufenden Node.js-Instanz verbunden sind, können Protokollereignisse erfassen, die von der Instanz ausgegeben werden, und sie entsprechend anzeigen, um das Debugging zu erleichtern. Die folgenden Methoden senden ein Protokollereignis an alle verbundenen Frontends. Die an die Methoden übergebenen params können optional sein, abhängig vom Protokoll.

// Das Ereignis `Network.requestWillBeSent` wird ausgelöst.
inspector.Network.requestWillBeSent({
  requestId: 'request-id-1',
  timestamp: Date.now() / 1000,
  wallTime: Date.now(),
  request: {
    url: 'https://nodejs.org/en',
    method: 'GET',
  },
});

`inspector.Network.requestWillBeSent([params])`

Hinzugefügt in: v22.6.0, v20.18.0

[Stabil: 1 - Experimentell]

Stabil: 1 Stabilität: 1 - Experimentell

params <Object>

Diese Funktion ist nur verfügbar, wenn das Flag --experimental-network-inspection aktiviert ist.

Sendet das Ereignis Network.requestWillBeSent an verbundene Frontends. Dieses Ereignis zeigt an, dass die Anwendung im Begriff ist, eine HTTP-Anforderung zu senden.

`inspector.Network.responseReceived([params])`

Hinzugefügt in: v22.6.0, v20.18.0

[Stabil: 1 - Experimentell]

Stabil: 1 Stabilität: 1 - Experimentell

params <Object>

Diese Funktion ist nur verfügbar, wenn das Flag --experimental-network-inspection aktiviert ist.

Sendet das Ereignis Network.responseReceived an verbundene Frontends. Dieses Ereignis zeigt an, dass eine HTTP-Antwort verfügbar ist.

`inspector.Network.loadingFinished([params])`

Hinzugefügt in: v22.6.0, v20.18.0

[Stabil: 1 - Experimentell]

Stabil: 1 Stabilität: 1 - Experimentell

params <Object>

Dieses Feature ist nur mit aktiviertem --experimental-network-inspection Flag verfügbar.

Sendet das Network.loadingFinished Event an verbundene Frontends. Dieses Event zeigt an, dass das Laden einer HTTP-Anfrage abgeschlossen ist.

`inspector.Network.loadingFailed([params])`

Hinzugefügt in: v22.7.0, v20.18.0

[Stabil: 1 - Experimentell]

Stabil: 1 Stabilität: 1 - Experimentell

params <Object>

Dieses Feature ist nur mit aktiviertem --experimental-network-inspection Flag verfügbar.

Sendet das Network.loadingFailed Event an verbundene Frontends. Dieses Event zeigt an, dass das Laden einer HTTP-Anfrage fehlgeschlagen ist.

Unterstützung von Haltepunkten

Die Chrome DevTools Protokoll Debugger Domain erlaubt einer inspector.Session, sich an ein Programm anzuhängen und Haltepunkte zu setzen, um durch den Code zu gehen.

Allerdings sollte das Setzen von Haltepunkten mit einer Single-Thread inspector.Session, die über session.connect() verbunden ist, vermieden werden, da das Programm, an das angehängt und pausiert wird, genau der Debugger selbst ist. Versuchen Sie stattdessen, sich über session.connectToMainThread() mit dem Haupt-Thread zu verbinden und Haltepunkte in einem Worker-Thread zu setzen, oder verbinden Sie sich mit einem Debugger-Programm über eine WebSocket-Verbindung.

Inspector ​

Promises API ​

Klasse: inspector.Session ​

new inspector.Session() ​

Ereignis: 'inspectorNotification' ​

Event: &lt;inspector-protocol-method&gt;; {#event-<inspector-protocol-method>;} ​

session.connect() ​

session.connectToMainThread() ​

session.disconnect() ​

session.post(method[, params]) ​

Beispielhafte Verwendung ​

CPU-Profiler ​

Heap-Profiler ​

Callback-API ​

Klasse: inspector.Session ​

new inspector.Session() ​

Event: 'inspectorNotification' ​

Event: &lt;inspector-protocol-method&gt;; {#event-<inspector-protocol-method>;_1} ​

session.connect() ​

session.connectToMainThread() ​

session.disconnect() ​

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

Beispielhafte Verwendung ​

CPU-Profiler ​

Heap-Profiler ​

Allgemeine Objekte ​

inspector.close() ​

inspector.console ​

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

inspector.url() ​

inspector.waitForDebugger() ​

Integration mit DevTools ​

inspector.Network.requestWillBeSent([params]) ​

inspector.Network.responseReceived([params]) ​

inspector.Network.loadingFinished([params]) ​

inspector.Network.loadingFailed([params]) ​

Unterstützung von Haltepunkten ​

Inspector

Promises API

Klasse: `inspector.Session`

`new inspector.Session()`

Ereignis: `'inspectorNotification'`

Event: `<inspector-protocol-method>`; {#event-<inspector-protocol-method>;}

`session.connect()`

`session.connectToMainThread()`

`session.disconnect()`

`session.post(method[, params])`

Beispielhafte Verwendung

CPU-Profiler

Heap-Profiler

Callback-API

Klasse: `inspector.Session`

`new inspector.Session()`

Event: `'inspectorNotification'`

Event: `<inspector-protocol-method>`; {#event-<inspector-protocol-method>;_1}

`session.connect()`

`session.connectToMainThread()`

`session.disconnect()`

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

Beispielhafte Verwendung

CPU-Profiler

Heap-Profiler

Allgemeine Objekte

`inspector.close()`

`inspector.console`

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

`inspector.url()`

`inspector.waitForDebugger()`

Integration mit DevTools

`inspector.Network.requestWillBeSent([params])`

`inspector.Network.responseReceived([params])`

`inspector.Network.loadingFinished([params])`

`inspector.Network.loadingFailed([params])`

Unterstützung von Haltepunkten