Inspecteur

[Stable : 2 - Stable]

Le module node:inspector fournit une API pour interagir avec l'inspecteur V8.

Il est accessible en utilisant :

ESMCJS

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

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

ESMCJS

import * as inspector from 'node:inspector'

const inspector = require('node:inspector')

API Promises

[Stable : 1 - Expérimental]

Stable : 1 Stability : 1 - Expérimental

Ajouté dans : v19.0.0

Classe : `inspector.Session`

Étend : <EventEmitter>

inspector.Session est utilisé pour envoyer des messages au back-end de l'inspecteur V8 et recevoir les réponses et les notifications des messages.

`new inspector.Session()`

Ajouté dans : v8.0.0

Crée une nouvelle instance de la classe inspector.Session. La session de l'inspecteur doit être connectée via session.connect() avant que les messages puissent être envoyés au back-end de l'inspecteur.

Lors de l'utilisation de Session, la sortie objet de l'API console ne sera pas libérée, sauf si nous avons exécuté manuellement la commande Runtime.DiscardConsoleEntries.

Événement : `'inspectorNotification'`

Ajouté dans : v8.0.0

<Object> L'objet message de notification

Émis lorsqu'une notification de l'inspecteur V8 est reçue.

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

Il est également possible de ne s'abonner qu'aux notifications avec une méthode spécifique :

Événement : `<inspector-protocol-method>` ; {#event-<inspector-protocol-method>;}

Ajouté dans : v8.0.0

<Objet> L'objet message de notification

Émis lorsqu'une notification de l'inspecteur est reçue et que son champ method est défini sur la valeur <inspector-protocol-method>.

L'extrait suivant installe un écouteur sur l'événement 'Debugger.paused', et affiche la raison de la suspension du programme chaque fois que l'exécution du programme est suspendue (par exemple, via des points d'arrêt) :

session.on('Debugger.paused', ({ params }) => {
  console.log(params.hitBreakpoints)
})
// [ '/le/fichier/qui/contient/le/point/d/arrêt.js:11:0' ]

`session.connect()`

Ajouté dans : v8.0.0

Connecte une session au back-end de l'inspecteur.

`session.connectToMainThread()`

Ajouté dans : v12.11.0

Connecte une session au back-end de l'inspecteur du thread principal. Une exception sera levée si cette API n'a pas été appelée sur un thread Worker.

`session.disconnect()`

Ajouté dans : v8.0.0

Ferme immédiatement la session. Tous les rappels de messages en attente seront appelés avec une erreur. session.connect() devra être appelé pour pouvoir envoyer à nouveau des messages. La session reconnectée perdra tout l'état de l'inspecteur, tel que les agents activés ou les points d'arrêt configurés.

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

Ajouté dans : v19.0.0

method <chaîne de caractères>
params <Objet>
Retourne : <Promise>

Envoie un message au back-end de l'inspecteur.

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

La dernière version du protocole d'inspection V8 est publiée sur le Visualiseur de protocole Chrome DevTools.

L'inspecteur Node.js prend en charge tous les domaines du protocole Chrome DevTools déclarés par V8. Le domaine du protocole Chrome DevTools fournit une interface pour interagir avec l'un des agents d'exécution utilisés pour inspecter l'état de l'application et écouter les événements d'exécution.

Utilisation exemple

En plus du débogueur, divers profileurs V8 sont disponibles via le protocole DevTools.

Profileur CPU

Voici un exemple illustrant l'utilisation du Profileur 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')
// Invoquer la logique métier à mesurer ici...

// quelque temps plus tard...
const { profile } = await session.post('Profiler.stop')

// Écrire le profil sur le disque, le télécharger, etc.
fs.writeFileSync('./profile.cpuprofile', JSON.stringify(profile))

Profileur de tas

Voici un exemple illustrant l'utilisation du Profileur de tas:

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)

API de rappel

Classe : `inspector.Session`

Étend : <EventEmitter>

inspector.Session est utilisé pour envoyer des messages au back-end de l'inspecteur V8 et recevoir les réponses aux messages et les notifications.

`new inspector.Session()`

Ajouté dans : v8.0.0

Créer une nouvelle instance de la classe inspector.Session. La session de l'inspecteur doit être connectée via session.connect() avant que les messages puissent être envoyés au back-end de l'inspecteur.

Lors de l'utilisation de Session, la sortie de l'API de la console ne sera pas libérée, sauf si nous exécutons manuellement la commande Runtime.DiscardConsoleEntries.

Événement : `'inspectorNotification'`

Ajouté dans : v8.0.0

<Objet> L’objet message de notification

Émis lorsqu’une notification de l’inspecteur V8 est reçue.

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

Il est également possible de ne s’abonner qu’aux notifications avec une méthode spécifique :

Événement : `<méthode-protocole-inspecteur>`; {#event-<inspector-protocol-method>;_1}

Ajouté dans : v8.0.0

<Objet> L’objet message de notification

Émis lorsqu’une notification de l’inspecteur est reçue et que son champ method est défini sur la valeur \<méthode-protocole-inspecteur\>.

L’extrait suivant installe un écouteur sur l’événement 'Debugger.paused', et imprime la raison de la suspension du programme chaque fois que l’exécution du programme est suspendue (par exemple, via des points d’arrêt) :

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

`session.connect()`

Ajouté dans : v8.0.0

Connecte une session au back-end de l’inspecteur.

`session.connectToMainThread()`

Ajouté dans : v12.11.0

Connecte une session au back-end de l’inspecteur du thread principal. Une exception sera levée si cette API n’a pas été appelée sur un thread Worker.

`session.disconnect()`

Ajouté dans : v8.0.0

Ferme immédiatement la session. Tous les rappels de messages en attente seront appelés avec une erreur. session.connect() devra être appelé pour pouvoir à nouveau envoyer des messages. La session reconnectée perdra tout l’état de l’inspecteur, comme les agents activés ou les points d’arrêt configurés.

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

[Historique]

Version	Modifications
v18.0.0	Passer un rappel invalide à l’argument `callback` lève désormais `ERR_INVALID_ARG_TYPE` au lieu de `ERR_INVALID_CALLBACK`.
v8.0.0	Ajouté dans : v8.0.0

method <chaîne de caractères>
params <Objet>
callback <Fonction>

Envoie un message au back-end de l’inspecteur. callback sera notifié lorsqu’une réponse est reçue. callback est une fonction qui accepte deux arguments facultatifs : l’erreur et le résultat spécifique au message.

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

La dernière version du protocole de l’inspecteur V8 est publiée sur le Visualiseur de protocole Chrome DevTools.

L’inspecteur Node.js prend en charge tous les domaines du protocole Chrome DevTools déclarés par V8. Le domaine du protocole Chrome DevTools fournit une interface pour interagir avec l’un des agents d’exécution utilisés pour inspecter l’état de l’application et écouter les événements d’exécution.

Vous ne pouvez pas définir reportProgress sur true lorsque vous envoyez une commande HeapProfiler.takeHeapSnapshot ou HeapProfiler.stopTrackingHeapObjects à V8.

Utilisation en exemple

Outre le débogueur, divers profileurs V8 sont disponibles via le protocole DevTools.

Profileur CPU

Voici un exemple montrant comment utiliser le Profileur 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', () => {
    // Invoquer la logique métier à mesurer ici...

    // un peu plus tard...
    session.post('Profiler.stop', (err, { profile }) => {
      // Écrire le profil sur le disque, le télécharger, etc.
      if (!err) {
        fs.writeFileSync('./profile.cpuprofile', JSON.stringify(profile))
      }
    })
  })
})

Profileur de tas

Voici un exemple montrant comment utiliser le Profileur de tas:

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

Objets courants

`inspector.close()`

[Historique]

Version	Modifications
v18.10.0	L'API est exposée dans les threads worker.
v9.0.0	Ajouté dans : v9.0.0

Tente de fermer toutes les connexions restantes, bloquant la boucle d'événements jusqu'à ce que toutes soient fermées. Une fois toutes les connexions fermées, désactive l'inspecteur.

`inspector.console`

<Objet> Un objet pour envoyer des messages à la console de l'inspecteur distant.

require('node:inspector').console.log('un message')

La console de l'inspecteur n'a pas la parité API avec la console Node.js.

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

[Historique]

Version	Modifications
v20.6.0	`inspector.open()` retourne désormais un objet `Disposable`.

port <nombre> Port sur lequel écouter les connexions de l'inspecteur. Facultatif. Défaut : ce qui a été spécifié sur la ligne de commande.
host <chaîne de caractères> Hôte sur lequel écouter les connexions de l'inspecteur. Facultatif. Défaut : ce qui a été spécifié sur la ligne de commande.
wait <booléen> Bloquer jusqu'à ce qu'un client se soit connecté. Facultatif. Défaut : false.
Retourne : <Disposable> Un objet Disposable qui appelle inspector.close().

Active l'inspecteur sur l'hôte et le port. Équivalent à node --inspect=[[host:]port], mais peut être fait par programmation après le démarrage de Node.

Si wait est true, bloquera jusqu'à ce qu'un client se soit connecté au port d'inspection et que le contrôle de flux ait été passé au client de débogage.

Voir l' avertissement de sécurité concernant l'utilisation du paramètre host.

`inspector.url()`

Retourne : <chaîne de caractères> | <indéfini>

Retourne l'URL de l'inspecteur actif, ou undefined s'il n'y en a pas.

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

Ajouté dans : v12.7.0

Bloque jusqu'à ce qu'un client (existant ou connecté ultérieurement) ait envoyé la commande Runtime.runIfWaitingForDebugger.

Une exception sera levée s'il n'y a pas d'inspecteur actif.

Intégration avec DevTools

Le module node:inspector fournit une API pour l'intégration avec les outils de développement qui prennent en charge le protocole Chrome DevTools. Les interfaces frontales DevTools connectées à une instance Node.js en cours d'exécution peuvent capturer les événements de protocole émis par l'instance et les afficher en conséquence pour faciliter le débogage. Les méthodes suivantes diffusent un événement de protocole à toutes les interfaces frontales connectées. Les params passés aux méthodes peuvent être facultatifs, selon le protocole.

// L'événement `Network.requestWillBeSent` sera déclenché.
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])`

Ajouté dans : v22.6.0, v20.18.0

[Stable : 1 - Expérimental]

Stable : 1 Stabilité : 1 - Expérimental

params <Objet>

Cette fonctionnalité n'est disponible qu'avec l'option --experimental-network-inspection activée.

Diffuse l'événement Network.requestWillBeSent aux interfaces frontales connectées. Cet événement indique que l'application est sur le point d'envoyer une requête HTTP.

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

Ajouté dans : v22.6.0, v20.18.0

[Stable : 1 - Expérimental]

Stable : 1 Stabilité : 1 - Expérimental

params <Objet>

Cette fonctionnalité n'est disponible qu'avec l'option --experimental-network-inspection activée.

Diffuse l'événement Network.responseReceived aux interfaces frontales connectées. Cet événement indique qu'une réponse HTTP est disponible.

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

Ajouté dans : v22.6.0, v20.18.0

[Stable : 1 - Expérimental]

Stable : 1 Stabilité : 1 - Expérimental

params <Objet>

Cette fonctionnalité est uniquement disponible avec l’indicateur --experimental-network-inspection activé.

Diffuse l’événement Network.loadingFinished aux interfaces connectées. Cet événement indique qu’une requête HTTP a fini de se charger.

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

Ajouté dans : v22.7.0, v20.18.0

[Stable : 1 - Expérimental]

Stable : 1 Stabilité : 1 - Expérimental

params <Objet>

Cette fonctionnalité est uniquement disponible avec l’indicateur --experimental-network-inspection activé.

Diffuse l’événement Network.loadingFailed aux interfaces connectées. Cet événement indique qu’une requête HTTP a échoué au chargement.

Prise en charge des points d’arrêt

Le protocole Chrome DevTools domaine Debugger permet à une inspector.Session de se connecter à un programme et de définir des points d’arrêt pour parcourir le code étape par étape.

Cependant, il convient d’éviter de définir des points d’arrêt avec une inspector.Session sur le même thread, connectée par session.connect(), car le programme auquel on se connecte et qui est mis en pause est le débogueur lui-même. Essayez plutôt de vous connecter au thread principal par session.connectToMainThread() et de définir des points d’arrêt dans un thread de travail, ou de vous connecter avec un programme Debugger via une connexion WebSocket.

Inspecteur ​

API Promises ​

Classe : inspector.Session ​

new inspector.Session() ​

Événement : 'inspectorNotification' ​

Événement : &lt;inspector-protocol-method&gt; ; {#event-<inspector-protocol-method>;} ​

session.connect() ​

session.connectToMainThread() ​

session.disconnect() ​

session.post(method[, params]) ​

Utilisation exemple ​

Profileur CPU ​

Profileur de tas ​

API de rappel ​

Classe : inspector.Session ​

new inspector.Session() ​

Événement : 'inspectorNotification' ​

Événement : &lt;méthode-protocole-inspecteur&gt;; {#event-<inspector-protocol-method>;_1} ​

session.connect() ​

session.connectToMainThread() ​

session.disconnect() ​

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

Utilisation en exemple ​

Profileur CPU ​

Profileur de tas ​

Objets courants ​

inspector.close() ​

inspector.console ​

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

inspector.url() ​

inspector.waitForDebugger() ​

Intégration avec DevTools ​

inspector.Network.requestWillBeSent([params]) ​

inspector.Network.responseReceived([params]) ​

inspector.Network.loadingFinished([params]) ​

inspector.Network.loadingFailed([params]) ​

Prise en charge des points d’arrêt ​

Inspecteur

API Promises

Classe : `inspector.Session`

`new inspector.Session()`

Événement : `'inspectorNotification'`

Événement : `<inspector-protocol-method>` ; {#event-<inspector-protocol-method>;}

`session.connect()`

`session.connectToMainThread()`

`session.disconnect()`

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

Utilisation exemple

Profileur CPU

Profileur de tas

API de rappel

Classe : `inspector.Session`

`new inspector.Session()`

Événement : `'inspectorNotification'`

Événement : `<méthode-protocole-inspecteur>`; {#event-<inspector-protocol-method>;_1}

`session.connect()`

`session.connectToMainThread()`

`session.disconnect()`

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

Utilisation en exemple

Profileur CPU

Profileur de tas

Objets courants

`inspector.close()`

`inspector.console`

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

`inspector.url()`

`inspector.waitForDebugger()`

Intégration avec DevTools

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

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

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

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

Prise en charge des points d’arrêt