Ispettore

[Stabile: 2 - Stabile]

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

È possibile accedervi utilizzando:

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 basata su Promises

[Stabile: 1 - Sperimentale]

Stabile: 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'ispettore V8 e per ricevere risposte ai messaggi e notifiche.

`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 restituito dall'API della 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'ispettore 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 che ha il campo metodo 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 (tramite breakpoint, ad esempio):

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 chiamata per poter inviare nuovamente i messaggi. La sessione riconnessa perderà tutto lo stato dell'inspector, come agenti abilitati o breakpoint 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 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 d'uso

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

Profiler CPU

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

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

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

Profiler heap

Ecco un esempio che mostra come utilizzare il Profiler 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>

inspector.Session viene utilizzato per l'invio di messaggi al back-end dell'inspector V8 e per la ricezione di risposte ai messaggi e notifiche.

`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 usa Session, l'oggetto restituito dall'API della console non verrà rilasciato, a meno che non si esegua 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 da V8 Inspector.

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

Aggiunto in: v8.0.0

<Object> L'oggetto del messaggio di notifica

Emesso quando viene ricevuta una notifica dell'inspector con il campo method 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. Un'eccezione verrà generata se questa API non viene 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 di nuovo messaggi. La sessione riconnessa perderà tutto lo stato dell'inspector, come gli agenti abilitati o i punti di interruzione configurati.

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

[Cronologia]

Versione	Modifiche
v18.0.0	Il passaggio di 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 <string>
params <Object>
callback <Function>

Invia un messaggio al back-end dell'inspector. Il 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 su 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.

Profilatore CPU

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

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

Profilatore heap

Ecco un esempio che mostra come utilizzare il Profilatore 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 fatto:', err, r)
  session.disconnect()
  fs.closeSync(fd)
})

Oggetti Comuni

`inspector.close()`

[Cronologia]

Versione	Modifiche
v18.10.0	L'API è esposta nei worker thread.
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('un messaggio')

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 restare in ascolto per le connessioni dell'inspector. Opzionale. Predefinito: ciò che è stato specificato nella CLI.
host <string> Host su cui restare in ascolto per le connessioni dell'inspector. Opzionale. Predefinito: ciò che è stato 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 sull'host e sulla porta. Equivalente a node --inspect=[[host:]port], ma può essere eseguito a livello di programmazione dopo l'avvio di node.

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

Vedere l'avviso di sicurezza relativo all'uso 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, vedere: 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, vedere: 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

Si blocca finché un client (esistente o connesso successivamente) non ha inviato il comando Runtime.runIfWaitingForDebugger.

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

Integrazione con DevTools

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

// L'evento `Network.requestWillBeSent` verrà attivato.
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

[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.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

[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.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.

Invia l'evento Network.loadingFinished alle interfacce utente connesse. 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.

Invia l'evento Network.loadingFailed alle interfacce utente connesse. Questo evento indica che il caricamento della richiesta HTTP non è riuscito.

Supporto dei punti di interruzione

Il dominio Debugger del protocollo Chrome DevTools consente a una inspector.Session di collegarsi a un programma e impostare punti di interruzione per scorrere il codice.

Tuttavia, l'impostazione di punti di interruzione con una inspector.Session dello stesso thread, che è connessa da session.connect(), dovrebbe essere evitata poiché il programma a cui si sta collegando 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.

Ispettore ​

API basata su 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 d'uso ​

Profiler CPU ​

Profiler 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 ​

Profilatore CPU ​

Profilatore 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 ​

Ispettore

API basata su 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 d'uso

Profiler CPU

Profiler 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

Profilatore CPU

Profilatore 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