Inspector

[Stable: 2 - Stabile]

Il modulo node:inspector fornisce un'API per interagire con l'inspector V8.

È accessibile tramite:

ESMCJS

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

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

oppure

ESMCJS

import * as inspector from 'node:inspector';

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

API Promises

[Stable: 1 - Sperimentale]

Stable: 1 Stabilità: 1 - Sperimentale

Aggiunto in: v19.0.0

Classe: `inspector.Session`

Estende: <EventEmitter>

La inspector.Session viene utilizzata per inviare messaggi al back-end dell'inspector V8 e ricevere risposte e notifiche ai messaggi.

`new inspector.Session()`

Aggiunto in: v8.0.0

Crea una nuova istanza della classe inspector.Session. La sessione dell'inspector deve essere connessa tramite session.connect() prima che i messaggi possano essere inviati al back-end dell'inspector.

Quando si utilizza Session, l'oggetto emesso dall'API console non verrà rilasciato, a meno che non venga eseguito manualmente il comando Runtime.DiscardConsoleEntries.

Evento: `'inspectorNotification'`

Aggiunto in: v8.0.0

<Object> L'oggetto del messaggio di notifica

Emesso quando viene ricevuta una notifica dall'Inspector V8.

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

È anche possibile sottoscrivere solo le notifiche con un metodo specifico:

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

Aggiunto in: v8.0.0

<Object> L'oggetto del messaggio di notifica

Emesso quando viene ricevuta una notifica dell'inspector il cui campo method è impostato sul valore \<inspector-protocol-method\>.

Il seguente snippet installa un listener sull'evento 'Debugger.paused' e stampa il motivo della sospensione del programma ogni volta che l'esecuzione del programma viene sospesa (ad esempio, tramite punti di interruzione):

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

`session.connect()`

Aggiunto in: v8.0.0

Connette una sessione al back-end dell'inspector.

`session.connectToMainThread()`

Aggiunto in: v12.11.0

Connette una sessione al back-end dell'inspector del thread principale. Verrà generata un'eccezione se questa API non è stata chiamata su un thread Worker.

`session.disconnect()`

Aggiunto in: v8.0.0

Chiude immediatamente la sessione. Tutti i callback dei messaggi in sospeso verranno chiamati con un errore. session.connect() dovrà essere chiamato per poter inviare nuovamente i messaggi. La sessione riconnessa perderà tutto lo stato dell'inspector, come gli agenti abilitati o i punti di interruzione configurati.

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

Aggiunto in: v19.0.0

method <string>
params <Object>
Restituisce: <Promise>

Invia un messaggio al back-end dell'inspector.

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

L'ultima versione del protocollo dell'inspector V8 è pubblicata su Chrome DevTools Protocol Viewer.

L'inspector di Node.js supporta tutti i domini del protocollo Chrome DevTools dichiarati da V8. Il dominio del protocollo Chrome DevTools fornisce un'interfaccia per interagire con uno degli agenti di runtime utilizzati per ispezionare lo stato dell'applicazione e ascoltare gli eventi di runtime.

Esempio di utilizzo

Oltre al debugger, sono disponibili vari V8 Profiler tramite il protocollo DevTools.

Profilatore CPU

Ecco un esempio che mostra come utilizzare il Profilatore 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');
// Richiama la logica di business sotto misurazione qui...

// qualche tempo dopo...
const { profile } = await session.post('Profiler.stop');

// Scrivi il profilo su disco, carica, ecc.
fs.writeFileSync('./profile.cpuprofile', JSON.stringify(profile));

Profilatore Heap

Ecco un esempio che mostra come utilizzare il Profilatore Heap:

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 fatto:', result);
session.disconnect();
fs.closeSync(fd);

API Callback

Classe: `inspector.Session`

Estende: <EventEmitter>

La inspector.Session viene utilizzata per inviare messaggi al back-end dell'ispettore V8 e ricevere risposte e notifiche ai messaggi.

`new inspector.Session()`

Aggiunto in: v8.0.0

Crea una nuova istanza della classe inspector.Session. La sessione dell'ispettore deve essere connessa tramite session.connect() prima che i messaggi possano essere inviati al back-end dell'ispettore.

Quando si utilizza Session, l'oggetto prodotto dall'API della console non verrà rilasciato, a meno che non eseguiamo manualmente il comando Runtime.DiscardConsoleEntries.

Evento: `'inspectorNotification'`

Aggiunto in: v8.0.0

<Object> L'oggetto del messaggio di notifica

Emesso quando viene ricevuta qualsiasi notifica dall'V8 Inspector.

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

È anche possibile sottoscriversi solo alle notifiche con un metodo specifico:

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

Aggiunto in: v8.0.0

<Object> L'oggetto del messaggio di notifica

Emesso quando viene ricevuta una notifica dell'inspector che ha il suo campo metodo impostato sul valore \<inspector-protocol-method\>.

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

`session.connect()`

Aggiunto in: v8.0.0

Connette una sessione al back-end dell'inspector.

`session.connectToMainThread()`

Aggiunto in: v12.11.0

Connette una sessione al back-end dell'inspector del thread principale. Verrà generata un'eccezione se questa API non è stata chiamata su un thread Worker.

`session.disconnect()`

Aggiunto in: v8.0.0

Chiude immediatamente la sessione. Tutti i callback dei messaggi in sospeso verranno richiamati con un errore. Sarà necessario chiamare session.connect() per poter inviare nuovamente i messaggi. La sessione riconnessa perderà tutto lo stato dell'inspector, come agenti abilitati o punti di interruzione configurati.

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

[Cronologia]

Versione	Modifiche
v18.0.0	Passare un callback non valido all'argomento `callback` ora genera `ERR_INVALID_ARG_TYPE` invece di `ERR_INVALID_CALLBACK`.
v8.0.0	Aggiunto in: v8.0.0

method <stringa>
params <Oggetto>
callback <Funzione>

Invia un messaggio al back-end dell'inspector. callback verrà notificato quando viene ricevuta una risposta. callback è una funzione che accetta due argomenti opzionali: errore e risultato specifico del messaggio.

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

L'ultima versione del protocollo V8 inspector è pubblicata sul Chrome DevTools Protocol Viewer.

Non è possibile impostare reportProgress su true quando si invia un comando HeapProfiler.takeHeapSnapshot o HeapProfiler.stopTrackingHeapObjects a V8.

Esempio di utilizzo

Oltre al debugger, sono disponibili vari profiler V8 tramite il protocollo DevTools.

Profiler CPU

Ecco un esempio che mostra come utilizzare il Profiler 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', () => {
    // Richiama la logica di business sotto misurazione qui...

    // qualche tempo dopo...
    session.post('Profiler.stop', (err, { profile }) => {
      // Scrivi il profilo su disco, caricalo, ecc.
      if (!err) {
        fs.writeFileSync('./profile.cpuprofile', JSON.stringify(profile));
      }
    });
  });
});

Profiler Heap

Ecco un esempio che mostra come utilizzare il Profiler Heap:

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

Oggetti comuni

`inspector.close()`

[Cronologia]

Versione	Modifiche
v18.10.0	L'API è esposta nei thread di worker.
v9.0.0	Aggiunto in: v9.0.0

Tenta di chiudere tutte le connessioni rimanenti, bloccando il ciclo di eventi finché non sono tutte chiuse. Una volta chiuse tutte le connessioni, disattiva l'inspector.

`inspector.console`

<Object> Un oggetto per inviare messaggi alla console dell'inspector remoto.

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

La console dell'inspector non ha la parità API con la console di Node.js.

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

[Cronologia]

Versione	Modifiche
v20.6.0	inspector.open() ora restituisce un oggetto `Disposable`.

port <number> Porta su cui ascoltare le connessioni dell'inspector. Opzionale. Predefinito: quello specificato nella CLI.
host <string> Host su cui ascoltare le connessioni dell'inspector. Opzionale. Predefinito: quello specificato nella CLI.
wait <boolean> Blocca fino a quando un client non si è connesso. Opzionale. Predefinito: false.
Restituisce: <Disposable> Un Disposable che chiama inspector.close().

Attiva l'inspector su host e porta. Equivalente a node --inspect=[[host:]port], ma può essere fatto programmaticamente dopo che node è stato avviato.

Se wait è true, si bloccherà fino a quando un client non si sarà connesso alla porta di ispezione e il controllo del flusso non sarà stato passato al client del debugger.

Vedi l'avviso di sicurezza riguardante l'utilizzo del parametro host.

`inspector.url()`

Restituisce: <string> | <undefined>

Restituisce l'URL dell'inspector attivo, o undefined se non ce n'è nessuno.

bash

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

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

`inspector.waitForDebugger()`

Aggiunto in: v12.7.0

Blocca fino a quando un client (esistente o connesso successivamente) ha inviato il comando Runtime.runIfWaitingForDebugger.

Verrà lanciata un'eccezione se non è presente un inspector attivo.

Integrazione con DevTools

Il modulo node:inspector fornisce un'API per l'integrazione con i devtool che supportano il protocollo Chrome DevTools. I frontend DevTools connessi a un'istanza Node.js in esecuzione possono acquisire gli eventi del protocollo emessi dall'istanza e visualizzarli di conseguenza per facilitare il debug. I seguenti metodi trasmettono un evento del protocollo a tutti i frontend connessi. I params passati ai metodi possono essere facoltativi, a seconda del protocollo.

// Verrà attivato l'evento `Network.requestWillBeSent`.
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])`

Aggiunto in: v22.6.0, v20.18.0

[Stable: 1 - Sperimentale]

Stable: 1 Stabilità: 1 - Sperimentale

params <Object>

Questa funzionalità è disponibile solo con il flag --experimental-network-inspection abilitato.

Trasmette l'evento Network.requestWillBeSent ai frontend connessi. Questo evento indica che l'applicazione sta per inviare una richiesta HTTP.

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

Aggiunto in: v22.6.0, v20.18.0

[Stable: 1 - Sperimentale]

Stable: 1 Stabilità: 1 - Sperimentale

params <Object>

Questa funzionalità è disponibile solo con il flag --experimental-network-inspection abilitato.

Trasmette l'evento Network.responseReceived ai frontend connessi. Questo evento indica che la risposta HTTP è disponibile.

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

Aggiunto in: v22.6.0, v20.18.0

[Stabile: 1 - Sperimentale]

Stabile: 1 Stabilità: 1 - Sperimentale

params <Object>

Questa funzionalità è disponibile solo con il flag --experimental-network-inspection abilitato.

Trasmette l'evento Network.loadingFinished ai frontend connessi. Questo evento indica che il caricamento della richiesta HTTP è terminato.

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

Aggiunto in: v22.7.0, v20.18.0

[Stabile: 1 - Sperimentale]

Stabile: 1 Stabilità: 1 - Sperimentale

params <Object>

Questa funzionalità è disponibile solo con il flag --experimental-network-inspection abilitato.

Trasmette l'evento Network.loadingFailed ai frontend connessi. Questo evento indica che il caricamento della richiesta HTTP non è riuscito.

Supporto dei punti di interruzione

Il Debugger domain del protocollo Chrome DevTools consente a una inspector.Session di collegarsi a un programma e impostare punti di interruzione per scorrere i codici.

Tuttavia, l'impostazione di punti di interruzione con una inspector.Session a thread singolo, che è connessa da session.connect(), dovrebbe essere evitata poiché il programma a cui ci si collega e che viene messo in pausa è esattamente il debugger stesso. Invece, prova a connetterti al thread principale tramite session.connectToMainThread() e imposta i punti di interruzione in un thread worker, oppure connettiti con un programma Debugger tramite connessione WebSocket.

Inspector ​

API Promises ​

Classe: inspector.Session ​

new inspector.Session() ​

Evento: 'inspectorNotification' ​

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

session.connect() ​

session.connectToMainThread() ​

session.disconnect() ​

session.post(method[, params]) ​

Esempio di utilizzo ​

Profilatore CPU ​

Profilatore Heap ​

API Callback ​

Classe: inspector.Session ​

new inspector.Session() ​

Evento: 'inspectorNotification' ​

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

session.connect() ​

session.connectToMainThread() ​

session.disconnect() ​

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

Esempio di utilizzo ​

Profiler CPU ​

Profiler Heap ​

Oggetti comuni ​

inspector.close() ​

inspector.console ​

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

inspector.url() ​

inspector.waitForDebugger() ​

Integrazione con DevTools ​

inspector.Network.requestWillBeSent([params]) ​

inspector.Network.responseReceived([params]) ​

inspector.Network.loadingFinished([params]) ​

inspector.Network.loadingFailed([params]) ​

Supporto dei punti di interruzione ​

Inspector

API Promises

Classe: `inspector.Session`

`new inspector.Session()`

Evento: `'inspectorNotification'`

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

`session.connect()`

`session.connectToMainThread()`

`session.disconnect()`

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

Esempio di utilizzo

Profilatore CPU

Profilatore Heap

API Callback

Classe: `inspector.Session`

`new inspector.Session()`

Evento: `'inspectorNotification'`

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

`session.connect()`

`session.connectToMainThread()`

`session.disconnect()`

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

Esempio di utilizzo

Profiler CPU

Profiler Heap

Oggetti comuni

`inspector.close()`

`inspector.console`

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

`inspector.url()`

`inspector.waitForDebugger()`

Integrazione con DevTools

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

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

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

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

Supporto dei punti di interruzione