Inspector

[Estable: 2 - Estable]

El módulo node:inspector proporciona una API para interactuar con el inspector de V8.

Se puede acceder 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 Promesas

[Estable: 1 - Experimental]

Estable: 1 Estabilidad: 1 - Experimental

Añadido en: v19.0.0

Clase: `inspector.Session`

Extiende: <EventEmitter>

inspector.Session se utiliza para enviar mensajes al backend del inspector de V8 y recibir respuestas y notificaciones de mensajes.

`new inspector.Session()`

Agregado en: v8.0.0

Crea una nueva instancia de la clase inspector.Session. La sesión del inspector necesita ser conectada a través de session.connect() antes de que los mensajes puedan ser despachados al backend del inspector.

Cuando se usa Session, el objeto emitido por la API de la consola no será liberado, a menos que ejecutemos manualmente el comando Runtime.DiscardConsoleEntries.

Evento: `'inspectorNotification'`

Agregado en: v8.0.0

<Objeto> El objeto del mensaje de notificación

Emitido cuando se recibe cualquier notificación del V8 Inspector.

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

También es posible suscribirse solo a las notificaciones con un método específico:

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

Agregado en: v8.0.0

<Objeto> El objeto del mensaje de notificación

Emitido cuando se recibe una notificación del inspector que tiene su campo de método establecido al valor \<inspector-protocol-method\>.

El siguiente fragmento instala un listener en el evento 'Debugger.paused', e imprime la razón de la suspensión del programa cada vez que la ejecución del programa se suspende (a través de puntos de interrupción, por ejemplo):

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

`session.connect()`

Agregado en: v8.0.0

Conecta una sesión al back-end del inspector.

`session.connectToMainThread()`

Agregado en: v12.11.0

Conecta una sesión al back-end del inspector del hilo principal. Se lanzará una excepción si esta API no se llamó en un hilo de Worker.

`session.disconnect()`

Agregado en: v8.0.0

Cierra inmediatamente la sesión. Todas las devoluciones de llamada de mensajes pendientes se llamarán con un error. Se deberá llamar a session.connect() para poder enviar mensajes nuevamente. La sesión reconectada perderá todo el estado del inspector, como los agentes habilitados o los puntos de interrupción configurados.

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

Agregado en: v19.0.0

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

Publica un mensaje en el back-end del 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' } }

La última versión del protocolo del inspector V8 se publica en el Visor del protocolo de Chrome DevTools.

El inspector de Node.js admite todos los dominios del protocolo de Chrome DevTools declarados por V8. El dominio del protocolo de Chrome DevTools proporciona una interfaz para interactuar con uno de los agentes de tiempo de ejecución utilizados para inspeccionar el estado de la aplicación y escuchar los eventos de tiempo de ejecución.

Ejemplo de uso

Además del depurador, hay varios perfiles de V8 disponibles a través del protocolo DevTools.

Perfilador de CPU

Aquí hay un ejemplo que muestra cómo usar el Perfilador 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')
// Invoca la lógica de negocio bajo medición aquí...

// Algún tiempo después...
const { profile } = await session.post('Profiler.stop')

// Escribe el perfil en el disco, súbelo, etc.
fs.writeFileSync('./profile.cpuprofile', JSON.stringify(profile))

Perfilador de montón

Aquí hay un ejemplo que muestra cómo usar el Perfilador de montón:

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

Clase: `inspector.Session`

Extiende: <EventEmitter>

La inspector.Session se utiliza para enviar mensajes al back-end del inspector V8 y recibir respuestas de mensajes y notificaciones.

`new inspector.Session()`

Añadido en: v8.0.0

Crea una nueva instancia de la clase inspector.Session. La sesión del inspector necesita conectarse a través de session.connect() antes de que los mensajes puedan ser enviados al back-end del inspector.

Cuando se usa Session, el objeto generado por la API de la consola no se liberará, a menos que se realice manualmente el comando Runtime.DiscardConsoleEntries.

Evento: `'inspectorNotification'`

Añadido en: v8.0.0

<Objeto> El objeto del mensaje de notificación

Se emite cuando se recibe cualquier notificación del Inspector V8.

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

También es posible suscribirse solo a notificaciones con un método específico:

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

Agregado en: v8.0.0

<Object> El objeto de mensaje de notificación

Se emite cuando se recibe una notificación del inspector que tiene su campo de método establecido en el valor \<inspector-protocol-method\>.

El siguiente fragmento instala un escucha en el evento 'Debugger.paused' e imprime la razón de la suspensión del programa cada vez que se suspende la ejecución del programa (por ejemplo, a través de puntos de interrupción):

session.on('Debugger.paused', ({ params }) => {
  console.log(params.hitBreakpoints)
})
// [ '/el/archivo/que/tiene/el/punto/de/interrupción.js:11:0' ]

`session.connect()`

Agregado en: v8.0.0

Conecta una sesión al backend del inspector.

`session.connectToMainThread()`

Agregado en: v12.11.0

Conecta una sesión al backend del inspector del hilo principal. Se lanzará una excepción si esta API no se llamó en un hilo Worker.

`session.disconnect()`

Agregado en: v8.0.0

Cierra inmediatamente la sesión. Todas las devoluciones de llamada de mensajes pendientes se invocarán con un error. Se deberá llamar a session.connect() para poder enviar mensajes nuevamente. La sesión reconectada perderá todo el estado del inspector, como los agentes habilitados o los puntos de interrupción configurados.

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

[Historial]

Versión	Cambios
v18.0.0	Pasar una devolución de llamada inválida al argumento `callback` ahora lanza `ERR_INVALID_ARG_TYPE` en lugar de `ERR_INVALID_CALLBACK`.
v8.0.0	Agregado en: v8.0.0

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

Publica un mensaje al backend del inspector. Se notificará a callback cuando se reciba una respuesta. callback es una función que acepta dos argumentos opcionales: error y resultado específico del mensaje.

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

La última versión del protocolo del inspector V8 se publica en el Visor del Protocolo de Chrome DevTools.

El inspector de Node.js admite todos los dominios del Protocolo de Chrome DevTools declarados por V8. El dominio del Protocolo de Chrome DevTools proporciona una interfaz para interactuar con uno de los agentes de tiempo de ejecución utilizados para inspeccionar el estado de la aplicación y escuchar los eventos de tiempo de ejecución.

No puedes establecer reportProgress en true al enviar un comando HeapProfiler.takeHeapSnapshot o HeapProfiler.stopTrackingHeapObjects a V8.

Ejemplo de uso

Además del depurador, varios Perfiles de V8 están disponibles a través del protocolo DevTools.

Perfilador de CPU

Aquí hay un ejemplo que muestra cómo usar el Perfilador 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', () => {
    // Invoca la lógica de negocio bajo medición aquí...

    // algún tiempo después...
    session.post('Profiler.stop', (err, { profile }) => {
      // Escribe el perfil en el disco, carga, etc.
      if (!err) {
        fs.writeFileSync('./profile.cpuprofile', JSON.stringify(profile))
      }
    })
  })
})

Perfilador de Heap

Aquí hay un ejemplo que muestra cómo usar el Perfilador 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 hecho:', err, r)
  session.disconnect()
  fs.closeSync(fd)
})

Objetos Comunes

`inspector.close()`

[Historial]

Versión	Cambios
v18.10.0	La API se expone en los hilos de trabajo.
v9.0.0	Añadido en: v9.0.0

Intenta cerrar todas las conexiones restantes, bloqueando el bucle de eventos hasta que todas estén cerradas. Una vez que todas las conexiones están cerradas, desactiva el inspector.

`inspector.console`

<Object> Un objeto para enviar mensajes a la consola del inspector remoto.

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

La consola del inspector no tiene paridad de API con la consola de Node.js.

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

[Historial]

Versión	Cambios
v20.6.0	inspector.open() ahora devuelve un objeto `Disposable`.

port <number> Puerto para escuchar las conexiones del inspector. Opcional. Predeterminado: lo que se especificó en la CLI.
host <string> Host para escuchar las conexiones del inspector. Opcional. Predeterminado: lo que se especificó en la CLI.
wait <boolean> Bloquear hasta que un cliente se haya conectado. Opcional. Predeterminado: false.
Devuelve: <Disposable> Un Disposable que llama a inspector.close().

Activa el inspector en el host y el puerto. Equivalente a node --inspect=[[host:]port], pero se puede hacer programáticamente después de que se haya iniciado node.

Si wait es true, se bloqueará hasta que un cliente se haya conectado al puerto de inspección y el control de flujo se haya pasado al cliente del depurador.

Consulte la advertencia de seguridad con respecto al uso del parámetro host.

`inspector.url()`

Devuelve: <string> | <undefined>

Devuelve la URL del inspector activo o undefined si no hay ninguno.

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

Agregado en: v12.7.0

Se bloquea hasta que un cliente (existente o conectado más tarde) ha enviado el comando Runtime.runIfWaitingForDebugger.

Se lanzará una excepción si no hay un inspector activo.

Integración con DevTools

El módulo node:inspector proporciona una API para la integración con herramientas de desarrollo que admiten el Protocolo de DevTools de Chrome. Las interfaces de DevTools conectadas a una instancia de Node.js en ejecución pueden capturar eventos de protocolo emitidos desde la instancia y mostrarlos en consecuencia para facilitar la depuración. Los siguientes métodos transmiten un evento de protocolo a todas las interfaces conectadas. Los params pasados a los métodos pueden ser opcionales, dependiendo del protocolo.

// Se activará el 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])`

Agregado en: v22.6.0, v20.18.0

[Estable: 1 - Experimental]

Estable: 1 Estabilidad: 1 - Experimental

params <Objeto>

Esta función solo está disponible con el indicador --experimental-network-inspection habilitado.

Transmite el evento Network.requestWillBeSent a las interfaces conectadas. Este evento indica que la aplicación está a punto de enviar una solicitud HTTP.

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

Agregado en: v22.6.0, v20.18.0

[Estable: 1 - Experimental]

Estable: 1 Estabilidad: 1 - Experimental

params <Objeto>

Esta función solo está disponible con la bandera --experimental-network-inspection habilitada.

Emite el evento Network.responseReceived a las interfaces conectadas. Este evento indica que la respuesta HTTP está disponible.

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

Agregado en: v22.6.0, v20.18.0

[Estable: 1 - Experimental]

Estable: 1 Estabilidad: 1 - Experimental

params <Objeto>

Esta función solo está disponible con la bandera --experimental-network-inspection habilitada.

Emite el evento Network.loadingFinished a las interfaces conectadas. Este evento indica que la carga de la solicitud HTTP ha finalizado.

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

Agregado en: v22.7.0, v20.18.0

[Estable: 1 - Experimental]

Estable: 1 Estabilidad: 1 - Experimental

params <Object>

Esta función solo está disponible con el indicador --experimental-network-inspection habilitado.

Transmite el evento Network.loadingFailed a los frontends conectados. Este evento indica que una solicitud HTTP no se ha podido cargar.

Soporte de puntos de interrupción

El dominio Debugger del Protocolo de Chrome DevTools permite que una inspector.Session se adjunte a un programa y establezca puntos de interrupción para recorrer el código paso a paso.

Sin embargo, se debe evitar establecer puntos de interrupción con una inspector.Session del mismo hilo, que está conectada mediante session.connect(), ya que el programa al que se adjunta y se pausa es exactamente el propio depurador. En su lugar, intente conectarse al hilo principal mediante session.connectToMainThread() y establecer puntos de interrupción en un hilo de trabajador, o conectarse con un programa Depurador a través de una conexión WebSocket.

Inspector ​

API de Promesas ​

Clase: 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]) ​

Ejemplo de uso ​

Perfilador de CPU ​

Perfilador de montón ​

API de Callback ​

Clase: 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]) ​

Ejemplo de uso ​

Perfilador de CPU ​

Perfilador de Heap ​

Objetos Comunes ​

inspector.close() ​

inspector.console ​

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

inspector.url() ​

inspector.waitForDebugger() ​

Integración con DevTools ​

inspector.Network.requestWillBeSent([params]) ​

inspector.Network.responseReceived([params]) ​

inspector.Network.loadingFinished([params]) ​

inspector.Network.loadingFailed([params]) ​

Soporte de puntos de interrupción ​

Inspector

API de Promesas

Clase: `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])`

Ejemplo de uso

Perfilador de CPU

Perfilador de montón

API de Callback

Clase: `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])`

Ejemplo de uso

Perfilador de CPU

Perfilador de Heap

Objetos Comunes

`inspector.close()`

`inspector.console`

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

`inspector.url()`

`inspector.waitForDebugger()`

Integración con DevTools

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

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

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

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

Soporte de puntos de interrupción