Inspetor

[Estável: 2 - Estável]

O módulo node:inspector fornece uma API para interagir com o inspetor V8.

Ele pode ser acessado usando:

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 de Promises

[Estável: 1 - Experimental]

Estável: 1 Estabilidade: 1 - Experimental

Adicionado em: v19.0.0

Classe: `inspector.Session`

Estende: <EventEmitter>

O inspector.Session é usado para despachar mensagens para o back-end do inspetor V8 e receber respostas de mensagens e notificações.

`new inspector.Session()`

Adicionado em: v8.0.0

Cria uma nova instância da classe inspector.Session. A sessão do inspetor precisa ser conectada através de session.connect() antes que as mensagens possam ser despachadas para o back-end do inspetor.

Ao usar Session, o objeto gerado pela API do console não será liberado, a menos que executemos manualmente o comando Runtime.DiscardConsoleEntries.

Evento: `'inspectorNotification'`

Adicionado em: v8.0.0

<Objeto> O objeto de mensagem de notificação

Emitido quando qualquer notificação do Inspetor V8 é recebida.

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

Também é possível se inscrever apenas para notificações com um método específico:

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

Adicionado em: v8.0.0

<Object> O objeto de mensagem de notificação

Emitido quando uma notificação do inspetor é recebida com o campo method definido para o valor \<inspector-protocol-method\>.

O trecho a seguir instala um ouvinte no evento 'Debugger.paused' e imprime o motivo da suspensão do programa sempre que a execução do programa é suspensa (por meio de pontos de interrupção, por exemplo):

session.on('Debugger.paused', ({ params }) => {
  console.log(params.hitBreakpoints)
})
// [ '/o/arquivo/que/tem/o/breakpoint.js:11:0' ]

`session.connect()`

Adicionado em: v8.0.0

Conecta uma sessão ao back-end do inspetor.

`session.connectToMainThread()`

Adicionado em: v12.11.0

Conecta uma sessão ao back-end do inspetor da thread principal. Uma exceção será lançada se esta API não for chamada em uma thread Worker.

`session.disconnect()`

Adicionado em: v8.0.0

Fecha a sessão imediatamente. Todos os callbacks de mensagens pendentes serão chamados com um erro. session.connect() precisará ser chamado para poder enviar mensagens novamente. A sessão reconectada perderá todo o estado do inspetor, como agentes habilitados ou pontos de interrupção configurados.

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

Adicionado em: v19.0.0

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

Envia uma mensagem para o back-end do inspetor.

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

A versão mais recente do protocolo do inspetor V8 é publicada no Visualizador do Protocolo Chrome DevTools.

O inspetor do Node.js suporta todos os domínios do Protocolo Chrome DevTools declarados pelo V8. O domínio do Protocolo Chrome DevTools fornece uma interface para interagir com um dos agentes de tempo de execução usados para inspecionar o estado do aplicativo e ouvir os eventos de tempo de execução.

Exemplo de uso

Além do depurador, vários V8 Profilers estão disponíveis através do protocolo DevTools.

Profiler de CPU

Aqui está um exemplo mostrando como usar o Profiler de 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')
// Invocar lógica de negócios sob medição aqui...

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

// Escrever perfil em disco, fazer upload, etc.
fs.writeFileSync('./profile.cpuprofile', JSON.stringify(profile))

Profiler de heap

Aqui está um exemplo mostrando como usar o Profiler de 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 done:', result)
session.disconnect()
fs.closeSync(fd)

API de Callback

Classe: `inspector.Session`

Estende: <EventEmitter>

O inspector.Session é usado para despachar mensagens para o back-end do inspetor V8 e receber respostas de mensagens e notificações.

`new inspector.Session()`

Adicionado em: v8.0.0

Ao usar Session, o objeto gerado pela API do console não será liberado, a menos que executemos manualmente o comando Runtime.DiscardConsoleEntries.

Evento: `'inspectorNotification'`

Adicionado em: v8.0.0

<Object> O objeto da mensagem de notificação

Emitido quando qualquer notificação do Inspetor V8 é recebida.

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

Também é possível assinar apenas notificações com um método específico:

Evento: `<método-do-protocolo-do-inspector>`; {#event-<inspector-protocol-method>;_1}

Adicionado em: v8.0.0

<Object> O objeto da mensagem de notificação

Emitido quando uma notificação do inspetor é recebida que tem seu campo de método definido para o valor \<método-do-protocolo-do-inspector\>.

O trecho a seguir instala um ouvinte no evento 'Debugger.paused', e imprime o motivo da suspensão do programa sempre que a execução do programa é suspensa (através de pontos de interrupção, por exemplo):

session.on('Debugger.paused', ({ params }) => {
  console.log(params.hitBreakpoints)
})
// [ '/o/arquivo/que/tem/o/ponto/de/interrupção.js:11:0' ]

`session.connect()`

Adicionado em: v8.0.0

Conecta uma sessão ao back-end do inspetor.

`session.connectToMainThread()`

Adicionado em: v12.11.0

Conecta uma sessão ao back-end do inspetor da thread principal. Uma exceção será lançada se esta API não for chamada em uma thread Worker.

`session.disconnect()`

Adicionado em: v8.0.0

Fecha imediatamente a sessão. Todos os callbacks de mensagens pendentes serão chamados com um erro. session.connect() precisará ser chamado para poder enviar mensagens novamente. A sessão reconectada perderá todo o estado do inspetor, como agentes habilitados ou pontos de interrupção configurados.

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

[Histórico]

Versão	Mudanças
v18.0.0	Passar um callback inválido para o argumento `callback` agora lança `ERR_INVALID_ARG_TYPE` em vez de `ERR_INVALID_CALLBACK`.
v8.0.0	Adicionado em: v8.0.0

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

Posta uma mensagem para o back-end do inspetor. callback será notificado quando uma resposta for recebida. callback é uma função que aceita dois argumentos opcionais: erro e resultado específico da mensagem.

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

A versão mais recente do protocolo do inspetor V8 é publicada no Chrome DevTools Protocol Viewer.

O inspetor Node.js suporta todos os domínios do Protocolo Chrome DevTools declarados pelo V8. O domínio do Protocolo Chrome DevTools fornece uma interface para interagir com um dos agentes de tempo de execução usados para inspecionar o estado do aplicativo e ouvir os eventos de tempo de execução.

Você não pode definir reportProgress como true ao enviar um comando HeapProfiler.takeHeapSnapshot ou HeapProfiler.stopTrackingHeapObjects para V8.

Exemplo de uso

Além do depurador, vários V8 Profilers estão disponíveis através do protocolo DevTools.

Profiler de CPU

Aqui está um exemplo mostrando como usar o Profiler de 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', () => {
    // Invocar a lógica de negócios sob medição aqui...

    // algum tempo depois...
    session.post('Profiler.stop', (err, { profile }) => {
      // Escrever o perfil no disco, fazer upload, etc.
      if (!err) {
        fs.writeFileSync('./profile.cpuprofile', JSON.stringify(profile))
      }
    })
  })
})

Profiler de Heap

Aqui está um exemplo mostrando como usar o Profiler de 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)
})

Objetos Comuns

`inspector.close()`

[Histórico]

Versão	Mudanças
v18.10.0	A API é exposta nas threads de worker.
v9.0.0	Adicionado em: v9.0.0

Tenta fechar todas as conexões restantes, bloqueando o loop de eventos até que todas sejam fechadas. Uma vez que todas as conexões são fechadas, desativa o inspetor.

`inspector.console`

<Object> Um objeto para enviar mensagens para o console do inspetor remoto.

require('node:inspector').console.log('uma mensagem')

O console do inspetor não tem paridade de API com o console do Node.js.

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

[Histórico]

Versão	Mudanças
v20.6.0	inspector.open() agora retorna um objeto `Disposable`.

port <number> Porta para escutar conexões do inspetor. Opcional. Padrão: o que foi especificado na CLI.
host <string> Host para escutar conexões do inspetor. Opcional. Padrão: o que foi especificado na CLI.
wait <boolean> Bloqueia até que um cliente se conecte. Opcional. Padrão: false.
Retorna: <Disposable> Um Disposable que chama inspector.close().

Ativa o inspetor no host e porta. Equivalente a node --inspect=[[host:]port], mas pode ser feito programaticamente após o node ser iniciado.

Se wait for true, irá bloquear até que um cliente tenha se conectado à porta de inspeção e o controle de fluxo tenha sido passado para o cliente de depuração.

Veja o aviso de segurança sobre o uso do parâmetro host.

`inspector.url()`

Retorna: <string> | <undefined>

Retorna a URL do inspetor ativo ou undefined se não houver nenhum.

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

Adicionado em: v12.7.0

Bloqueia até que um cliente (existente ou conectado posteriormente) tenha enviado o comando Runtime.runIfWaitingForDebugger.

Uma exceção será lançada se não houver nenhum inspetor ativo.

Integração com DevTools

O módulo node:inspector fornece uma API para integração com ferramentas de desenvolvimento que suportam o Protocolo Chrome DevTools. Front-ends de ferramentas de desenvolvimento conectados a uma instância Node.js em execução podem capturar eventos de protocolo emitidos pela instância e exibi-los de acordo para facilitar a depuração. Os seguintes métodos transmitem um evento de protocolo para todos os front-ends conectados. Os params passados para os métodos podem ser opcionais, dependendo do protocolo.

// O evento `Network.requestWillBeSent` será acionado.
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])`

Adicionado em: v22.6.0, v20.18.0

[Estável: 1 - Experimental]

Estável: 1 Estabilidade: 1 - Experimental

params <Objeto>

Este recurso está disponível apenas com a flag --experimental-network-inspection habilitada.

Transmite o evento Network.requestWillBeSent para os front-ends conectados. Este evento indica que o aplicativo está prestes a enviar uma requisição HTTP.

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

Adicionado em: v22.6.0, v20.18.0

[Estável: 1 - Experimental]

Estável: 1 Estabilidade: 1 - Experimental

params <Objeto>

Este recurso está disponível apenas com a flag --experimental-network-inspection habilitada.

Transmite o evento Network.responseReceived para os front-ends conectados. Este evento indica que a resposta HTTP está disponível.

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

Adicionado em: v22.6.0, v20.18.0

[Estável: 1 - Experimental]

Estável: 1 Estabilidade: 1 - Experimental

params <Objeto>

Este recurso está disponível apenas com a flag --experimental-network-inspection habilitada.

Transmite o evento Network.loadingFinished para os frontends conectados. Este evento indica que o carregamento da requisição HTTP foi finalizado.

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

Adicionado em: v22.7.0, v20.18.0

[Estável: 1 - Experimental]

Estável: 1 Estabilidade: 1 - Experimental

params <Objeto>

Este recurso está disponível apenas com a flag --experimental-network-inspection habilitada.

Transmite o evento Network.loadingFailed para os frontends conectados. Este evento indica que o carregamento da requisição HTTP falhou.

Suporte a pontos de interrupção

O Protocolo Chrome DevTools Debugger domain permite que um inspector.Session se conecte a um programa e defina pontos de interrupção para percorrer o código passo a passo.

No entanto, a definição de pontos de interrupção com um inspector.Session de mesma thread, que é conectado por session.connect(), deve ser evitada, pois o programa que está sendo conectado e pausado é exatamente o próprio depurador. Em vez disso, tente conectar-se à thread principal por meio de session.connectToMainThread() e defina pontos de interrupção em uma thread de trabalho ou conecte-se com um programa Debugger por meio de uma conexão WebSocket.

Inspetor ​

API de 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]) ​

Exemplo de uso ​

Profiler de CPU ​

Profiler de heap ​

API de Callback ​

Classe: inspector.Session ​

new inspector.Session() ​

Evento: 'inspectorNotification' ​

Evento: &lt;método-do-protocolo-do-inspector&gt;; {#event-<inspector-protocol-method>;_1} ​

session.connect() ​

session.connectToMainThread() ​

session.disconnect() ​

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

Exemplo de uso ​

Profiler de CPU ​

Profiler de Heap ​

Objetos Comuns ​

inspector.close() ​

inspector.console ​

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

inspector.url() ​

inspector.waitForDebugger() ​

Integração com DevTools ​

inspector.Network.requestWillBeSent([params]) ​

inspector.Network.responseReceived([params]) ​

inspector.Network.loadingFinished([params]) ​

inspector.Network.loadingFailed([params]) ​

Suporte a pontos de interrupção ​

Inspetor

API de 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])`

Exemplo de uso

Profiler de CPU

Profiler de heap

API de Callback

Classe: `inspector.Session`

`new inspector.Session()`

Evento: `'inspectorNotification'`

Evento: `<método-do-protocolo-do-inspector>`; {#event-<inspector-protocol-method>;_1}

`session.connect()`

`session.connectToMainThread()`

`session.disconnect()`

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

Exemplo de uso

Profiler de CPU

Profiler de Heap

Objetos Comuns

`inspector.close()`

`inspector.console`

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

`inspector.url()`

`inspector.waitForDebugger()`

Integração com DevTools

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

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

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

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

Suporte a pontos de interrupção