home / documentation / v19 / inspector

Inspector

目录

Added in: v8.0.0

稳定性: 2 - Stable

The node:inspector module provides an API for interacting with the V8 inspector.

It can be accessed using:

MJS
CJS

or

MJS
CJS

Promises API

稳定性: 1 - Experimental

Added in: v19.0.0

C inspector.Session

The inspector.Session is used for dispatching messages to the V8 inspector back-end and receiving message responses and notifications.

M new inspector.Session()

Added in: v8.0.0

Create a new instance of the inspector.Session class. The inspector session needs to be connected through session.connect() before the messages can be dispatched to the inspector backend.

E 'inspectorNotification'

Added in: v8.0.0

  • Object The notification message object

Emitted when any notification from the V8 Inspector is received.

JS

It is also possible to subscribe only to notifications with specific method:

E <inspector-protocol-method>;

Added in: v8.0.0

  • Object The notification message object

Emitted when an inspector notification is received that has its method field set to the <inspector-protocol-method> value.

The following snippet installs a listener on the 'Debugger.paused' event, and prints the reason for program suspension whenever program execution is suspended (through breakpoints, for example):

JS
M session.connect()

Added in: v8.0.0

Connects a session to the inspector back-end.

M session.connectToMainThread()

Added in: v12.11.0

Connects a session to the main thread inspector back-end. An exception will be thrown if this API was not called on a Worker thread.

M session.disconnect()

Added in: v8.0.0

Immediately close the session. All pending message callbacks will be called with an error. session.connect() will need to be called to be able to send messages again. Reconnected session will lose all inspector state, such as enabled agents or configured breakpoints.

M session.post(method[, params])

Added in: v19.0.0

Posts a message to the inspector back-end.

MJS

The latest version of the V8 inspector protocol is published on the Chrome DevTools Protocol Viewer.

Node.js inspector supports all the Chrome DevTools Protocol domains declared by V8. Chrome DevTools Protocol domain provides an interface for interacting with one of the runtime agents used to inspect the application state and listen to the run-time events.

Example usage

Apart from the debugger, various V8 Profilers are available through the DevTools protocol.

CPU profiler

Here's an example showing how to use the CPU Profiler:

MJS
Heap profiler

Here's an example showing how to use the Heap Profiler:

MJS

Callback API

C inspector.Session

The inspector.Session is used for dispatching messages to the V8 inspector back-end and receiving message responses and notifications.

M new inspector.Session()

Added in: v8.0.0

Create a new instance of the inspector.Session class. The inspector session needs to be connected through session.connect() before the messages can be dispatched to the inspector backend.

E 'inspectorNotification'

Added in: v8.0.0

  • Object The notification message object

Emitted when any notification from the V8 Inspector is received.

JS

It is also possible to subscribe only to notifications with specific method:

E <inspector-protocol-method>;

Added in: v8.0.0

  • Object The notification message object

Emitted when an inspector notification is received that has its method field set to the <inspector-protocol-method> value.

The following snippet installs a listener on the 'Debugger.paused' event, and prints the reason for program suspension whenever program execution is suspended (through breakpoints, for example):

JS
M session.connect()

Added in: v8.0.0

Connects a session to the inspector back-end.

M session.connectToMainThread()

Added in: v12.11.0

Connects a session to the main thread inspector back-end. An exception will be thrown if this API was not called on a Worker thread.

M session.disconnect()

Added in: v8.0.0

Immediately close the session. All pending message callbacks will be called with an error. session.connect() will need to be called to be able to send messages again. Reconnected session will lose all inspector state, such as enabled agents or configured breakpoints.

M session.post(method[, params][, callback])
历史
版本更改
v18.0.0Passing an invalid callback to the `callback` argument now throws `ERR_INVALID_ARG_TYPE` instead of `ERR_INVALID_CALLBACK`.
v8.0.0Added in: v8.0.0

Posts a message to the inspector back-end. callback will be notified when a response is received. callback is a function that accepts two optional arguments: error and message-specific result.

JS

The latest version of the V8 inspector protocol is published on the Chrome DevTools Protocol Viewer.

Node.js inspector supports all the Chrome DevTools Protocol domains declared by V8. Chrome DevTools Protocol domain provides an interface for interacting with one of the runtime agents used to inspect the application state and listen to the run-time events.

Example usage

Apart from the debugger, various V8 Profilers are available through the DevTools protocol.

CPU profiler

Here's an example showing how to use the CPU Profiler:

JS
Heap profiler

Here's an example showing how to use the Heap Profiler:

JS

Common Objects

M inspector.close()

历史
版本更改
v18.10.0The API is exposed in the worker threads.
v9.0.0Added in: v9.0.0

Deactivate the inspector. Blocks until there are no active connections.

M inspector.console

  • Object An object to send messages to the remote inspector console.
JS

The inspector console does not have API parity with Node.js console.

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

  • port number Port to listen on for inspector connections. Optional. Default: what was specified on the CLI.
  • host string Host to listen on for inspector connections. Optional. Default: what was specified on the CLI.
  • wait boolean Block until a client has connected. Optional. Default: false.

Activate inspector on host and port. Equivalent to node --inspect=[[host:]port], but can be done programmatically after node has started.

If wait is true, will block until a client has connected to the inspect port and flow control has been passed to the debugger client.

See the security warning regarding the host parameter usage.

M inspector.url()

Return the URL of the active inspector, or undefined if there is none.

BASH

M inspector.waitForDebugger()

Added in: v12.7.0

Blocks until a client (existing or connected later) has sent Runtime.runIfWaitingForDebugger command.

An exception will be thrown if there is no active inspector.