Inspektor

[Stabil: 2 - Stabil]

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

Es kann wie folgt zugegriffen werden:

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>

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 Nachrichten an das Inspektor-Backend gesendet werden können.

Bei Verwendung von Session wird die von der Konsolen-API ausgegebene Objekt nicht freigegeben, es sei denn, wir haben den Befehl Runtime.DiscardConsoleEntries manuell ausgeführt.

Ereignis: `'inspectorNotification'`

Hinzugefügt in: v8.0.0

<Object> Das Benachrichtigungsnachrichtenobjekt

Wird ausgegeben, wenn eine Benachrichtigung vom V8-Inspektor 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:

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

Hinzugefügt in: v8.0.0

<Object> Das Benachrichtigungsnachrichtenobjekt

Wird ausgegeben, wenn eine Inspektorbenachrichtigung empfangen wird, deren Methodenfeld auf den Wert \<inspector-protocol-method\> gesetzt ist.

Das folgende Snippet installiert einen Listener für das Ereignis 'Debugger.paused' und gibt den Grund für die Programmaussetzung aus, wann immer die Programmausführung angehalten 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 Main-Thread-Inspector-Backend. Eine Ausnahme wird 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. Die wiederverbundene Sitzung verliert den gesamten Inspektorzustand, z. B. aktivierte Agents oder konfigurierte Breakpoints.

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

Hinzugefügt in: v19.0.0

method <string>
params <Object>
Rückgabewert: <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 auf der Chrome DevTools Protocol Viewer veröffentlicht.

Node.js Inspector unterstützt alle von V8 deklarierten Chrome DevTools Protocol-Domains. Die Chrome DevTools Protocol-Domain bietet eine Schnittstelle zur Interaktion mit einem der Runtime-Agents, die verwendet werden, um den Anwendungszustand zu inspizieren und die Laufzeitereignisse abzuhören.

Beispielhafte Verwendung

Neben dem Debugger stehen verschiedene V8-Profiler über das DevTools-Protokoll zur Verfügung.

CPU-Profiler

Hier ist ein Beispiel für die Verwendung des CPU-Profilers:

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 zu messende Geschäftslogik aufrufen...

// etwas 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 für die Verwendung des Heap-Profilers:

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-Inspector-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 Nachrichten an das Inspector-Backend gesendet werden können.

Bei Verwendung von Session wird das von der Konsolen-API ausgegebene Objekt nicht freigegeben, es sei denn, wir haben den Befehl Runtime.DiscardConsoleEntries manuell ausgeführt.

Ereignis: `'inspectorNotification'`

Hinzugefügt in: v8.0.0

<Objekt> Das Benachrichtigungsnachrichtenobjekt

Wird ausgegeben, wenn eine Benachrichtigung vom V8-Inspektor 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:

Ereignis: `<inspector-protokoll-methode>`; {#event-<inspector-protocol-method>;_1}

Hinzugefügt in: v8.0.0

<Objekt> Das Benachrichtigungsnachrichtenobjekt

Wird ausgegeben, wenn eine Inspektorbenachrichtigung empfangen wird, deren Methodenfeld auf den Wert \<inspector-protokoll-methode\> gesetzt ist.

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 Inspektor-Backend.

`session.connectToMainThread()`

Hinzugefügt in: v12.11.0

Verbindet eine Sitzung mit dem Main-Thread-Inspektor-Backend. Eine Ausnahme wird 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. Die wiederhergestellte Sitzung verliert den gesamten Inspektorzustand, z. B. aktivierte Agents oder konfigurierte Breakpoints.

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

[Historie]

Version	Änderungen
v18.0.0	Das Übergeben eines ungültigen Callbacks an das Argument `callback` löst jetzt `ERR_INVALID_ARG_TYPE` anstelle von `ERR_INVALID_CALLBACK` aus.
v8.0.0	Hinzugefügt in: v8.0.0

method <Zeichenkette>
params <Objekt>
callback <Funktion>

Sendet eine Nachricht an das Inspektor-Backend. callback wird benachrichtigt, wenn eine Antwort empfangen wird. callback ist eine Funktion, die zwei optionale Argumente akzeptiert: Fehler und messageabhängiges Ergebnis.

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

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

Node.js Inspector unterstützt alle von V8 deklarierten Chrome DevTools-Protokolldomänen. Die Chrome DevTools-Protokolldomäne bietet eine Schnittstelle zur Interaktion mit einem der Laufzeit-Agents, die verwendet werden, um den Anwendungszustand zu inspizieren und die Laufzeitereignisse abzuhören.

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

Beispielhafte Verwendung

Neben dem Debugger stehen verschiedene V8-Profiler über das DevTools-Protokoll zur Verfügung.

CPU-Profiler

Hier ist ein Beispiel, das zeigt, wie der CPU-Profiler verwendet wird:

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 Geschäftslogik unter Messung aufrufen...

    // einige Zeit 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 zeigt, wie der Heap-Profiler verwendet wird:

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

Gemeinsame 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, deaktiviert der Inspektor.

`inspector.console`

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

require('node:inspector').console.log('eine Nachricht')

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

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

[Historie]

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

port <number> Port zum Abhören von Inspector-Verbindungen. Optional. Standard: was über die CLI angegeben wurde.
host <string> Host zum Abhören von Inspector-Verbindungen. Optional. Standard: was über die 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. Entspricht node --inspect=[[host:]port], kann aber programmatisch ausgeführt werden, nachdem Node gestartet wurde.

Wenn wait true ist, wird blockiert, bis ein Client mit dem Inspect-Port verbunden ist und die Flusskontrolle 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 keiner 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 (bestehend oder später verbunden) den Befehl Runtime.runIfWaitingForDebugger gesendet hat.

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

Integration mit DevTools

Das Modul node:inspector bietet eine API zur Integration mit DevTools, die das Chrome DevTools Protokoll unterstützen. DevTools-Frontends, die mit einer laufenden Node.js-Instanz verbunden sind, können Protokollereignisse erfassen, die von der Instanz emittiert werden, und diese zur Erleichterung des Debuggens entsprechend anzeigen. 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 mit aktivierter --experimental-network-inspection-Flag verfügbar.

Sendet das Ereignis Network.requestWillBeSent an verbundene Frontends. Dieses Ereignis zeigt an, dass die Anwendung im Begriff ist, eine HTTP-Anfrage 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 mit aktivierter --experimental-network-inspection-Flag verfügbar.

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>

Diese Funktion ist nur mit aktiviertem --experimental-network-inspection-Flag verfügbar.

Sendet das Ereignis Network.loadingFinished an verbundene Frontends. Dieses Ereignis zeigt an, dass der HTTP-Request abgeschlossen wurde.

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

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

[Stabil: 1 - Experimentell]

Stabil: 1 Stabilität: 1 - Experimentell

params <Object>

Diese Funktion ist nur mit aktiviertem --experimental-network-inspection-Flag verfügbar.

Sendet das Ereignis Network.loadingFailed an verbundene Frontends. Dieses Ereignis zeigt an, dass der HTTP-Request fehlgeschlagen ist.

Unterstützung von Breakpoints

Das Chrome DevTools Protokoll Debugger-Domäne erlaubt einer inspector.Session, sich an ein Programm anzuhängen und Breakpoints zu setzen, um den Code schrittweise zu durchlaufen.

Das Setzen von Breakpoints mit einer gleichzeitigen inspector.Session, die über session.connect() verbunden ist, sollte jedoch vermieden werden, da das angehängte und angehaltene Programm genau der Debugger selbst ist. Versuchen Sie stattdessen, sich über session.connectToMainThread() mit dem Hauptthread zu verbinden und Breakpoints in einem Worker-Thread zu setzen, oder verbinden Sie sich mit einem Debugger-Programm über eine WebSocket-Verbindung.

Inspektor ​

Promises-API ​

Klasse: inspector.Session ​

new inspector.Session() ​

Ereignis: 'inspectorNotification' ​

Ereignis: &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() ​

Ereignis: 'inspectorNotification' ​

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

session.connect() ​

session.connectToMainThread() ​

session.disconnect() ​

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

Beispielhafte Verwendung ​

CPU-Profiler ​

Heap-Profiler ​

Gemeinsame 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 Breakpoints ​

Inspektor

Promises-API

Klasse: `inspector.Session`

`new inspector.Session()`

Ereignis: `'inspectorNotification'`

Ereignis: `<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()`

Ereignis: `'inspectorNotification'`

Ereignis: `<inspector-protokoll-methode>`; {#event-<inspector-protocol-method>;_1}

`session.connect()`

`session.connectToMainThread()`

`session.disconnect()`

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

Beispielhafte Verwendung

CPU-Profiler

Heap-Profiler

Gemeinsame 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 Breakpoints