Promises API

class inspector.Session extends EventEmitter

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

new inspector.Session(): inspector.Session

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.

When using Session, the object outputted by the console API will not be released, unless we performed manually Runtime.DiscardConsoleEntries command.

Emitted when any notification from the V8 Inspector is received.

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

Caveat Breakpoints with same-thread session is not recommended, see support of breakpoints.

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

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):

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

Caveat Breakpoints with same-thread session is not recommended, see support of breakpoints.

session.connect(): void

Connects a session to the inspector back-end.

session.connectToMainThread(): void

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.

session.disconnect(): void

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.

session.post(method, params?): Promise

Posts a message to the inspector back-end.

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

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.

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

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

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');
// Invoke business logic under measurement here...

// some time later...
const { profile } = await session.post('Profiler.stop');

// Write profile to disk, upload, etc.
fs.writeFileSync('./profile.cpuprofile', JSON.stringify(profile));

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

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