API обещаний

Класс: inspector.Session

• Расширяет: <EventEmitter>

inspector.Session используется для отправки сообщений в бэкенд инспектора V8 и получения ответов на сообщения и уведомлений.

new inspector.Session()

Создайте новый экземпляр класса inspector.Session. Сеанс инспектора необходимо подключить через session.connect(), прежде чем отправлять сообщения бэкенду инспектора.

При использовании Session, объект, выводимый API консоли, не будет освобожден, если мы не выполнили вручную команду Runtime.DiscardConsoleEntries.

Событие: 'inspectorNotification'

• <Объект> Объект сообщения уведомления

Вызывается при получении любого уведомления от инспектора V8.

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

Примечание Не рекомендуется использовать точки останова с сеансом в одном потоке, см. поддержку точек останова.

Также возможно подписаться только на уведомления с определенным методом:

Событие: <inspector-protocol-method>;

• <Объект> Объект сообщения уведомления

Вызывается при получении уведомления инспектора, у которого поле метода установлено в значение <inspector-protocol-method>.

Следующий фрагмент устанавливает обработчик события 'Debugger.paused' и выводит причину приостановки выполнения программы, когда выполнение программы приостанавливается (например, через точки останова):

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

Примечание Не рекомендуется использовать точки останова с сеансом в одном потоке, см. поддержку точек останова.

session.connect()

Подключает сеанс к бэкенду инспектора.

session.connectToMainThread()

Подключает сеанс к бэкенду инспектора основного потока. Будет выброшено исключение, если этот API не был вызван в потоке Worker.

session.disconnect()

Немедленно закрывает сеанс. Все ожидающие обратные вызовы сообщений будут вызваны с ошибкой. session.connect() необходимо вызвать, чтобы снова отправлять сообщения. Подключенный заново сеанс потеряет все состояние инспектора, такие как включенные агенты или настроенные точки останова.

session.post(method[, params])

• method <строка>
• params <объект>
• Возвращает: <Обещание>

Отправляет сообщение в бэкенд инспектора.

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

Последняя версия протокола инспектора V8 опубликована на Просмотрщике протокола Chrome DevTools.

Инспектор Node.js поддерживает все домены протокола Chrome DevTools, объявленные V8. Домен протокола Chrome DevTools предоставляет интерфейс для взаимодействия с одним из агентов выполнения, используемых для проверки состояния приложения и прослушивания событий во время выполнения.

Пример использования

Помимо отладчика, доступны различные профилировщики V8 через протокол DevTools.

Профилировщик процессора

Вот пример того, как использовать профилировщик процессора:

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

Профилировщик кучи

Вот пример того, как использовать профилировщик кучи:

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

API обратного вызова

Класс: inspector.Session

• Расширяет: <EventEmitter>

Класс inspector.Session используется для отправки сообщений в бэкенд V8 инспектора и получения ответов и уведомлений.

new inspector.Session()

Создает новый экземпляр класса inspector.Session. Сеанс инспектора должен быть подключен через session.connect() перед отправкой сообщений в бэкенд инспектора.

При использовании Session, объект, выводимый API консоли, не будет освобожден, если не будет выполнена команда Runtime.DiscardConsoleEntries.

Событие: 'inspectorNotification'

• <Объект> Объект сообщения уведомления

Вызывается при получении любого уведомления от V8 инспектора.

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

Примечание Точки останова с сеансом в том же потоке не рекомендуются, см. поддержку точек останова.

Также можно подписаться только на уведомления с определённым методом:

Событие: <inspector-protocol-method>;

• <Объект> Объект сообщения уведомления

Вызывается при получении уведомления инспектора, у которого поле метода установлено в значение <inspector-protocol-method>.

Следующий фрагмент кода устанавливает обработчик для события 'Debugger.paused' и выводит причину приостановки выполнения программы при её приостановке (например, через точки останова):

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

Примечание Точки останова с сеансом в том же потоке не рекомендуются, см. поддержку точек останова.

session.connect()

Подключает сеанс к бэкенду инспектора.

session.connectToMainThread()

Подключает сеанс к бэкенду инспектора основного потока. Исключение будет выброшено, если этот API не был вызван в потоке Worker.

session.disconnect()

Немедленно закрывает сеанс. Все ожидающие обратные вызовы сообщений будут вызваны с ошибкой. session.connect() необходимо будет вызвать, чтобы снова отправить сообщения. Переподключенный сеанс потеряет все состояние инспектора, такие как включенные агенты или настроенные точки останова.

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

• method <строка>
• params <Объект>
• callback <Функция>

Отправляет сообщение в бэкенд инспектора. callback будет уведомлён, когда будет получен ответ. callback — функция, принимающая два необязательных аргумента: ошибку и результат, специфичный для сообщения.

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

Самая последняя версия протокола V8 инспектора опубликована на Chrome DevTools Protocol Viewer.

Инспектор Node.js поддерживает все домены протокола Chrome DevTools, объявленные V8. Домен протокола Chrome DevTools предоставляет интерфейс для взаимодействия с одним из агентов выполнения, используемых для инспектирования состояния приложения и прослушивания событий во время выполнения.

Нельзя установить reportProgress в true при отправке команды HeapProfiler.takeHeapSnapshot или HeapProfiler.stopTrackingHeapObjects в V8.

Пример использования

Помимо отладчика, доступны различные профилировщики V8 через протокол DevTools.

Профилировщик CPU

Вот пример, демонстрирующий, как использовать CPU Profiler:

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', () => {
    // Invoke business logic under measurement here...

    // some time later...
    session.post('Profiler.stop', (err, { profile }) => {
      // Write profile to disk, upload, etc.
      if (!err) {
        fs.writeFileSync('./profile.cpuprofile', JSON.stringify(profile));
      }
    });
  });
}); copy

Профилировщик Heap

Вот пример, демонстрирующий, как использовать Heap Profiler:

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

Общие объекты

inspector.close()

Попытка закрыть все оставшиеся подключения, блокируя цикл событий до тех пор, пока все они не будут закрыты. После закрытия всех подключений отключает инспектор.

inspector.console

• <Объект> Объект для отправки сообщений в удалённую консоль инспектора.

require('node:inspector').console.log('a message'); copy

Консоль инспектора не имеет полной API совместимости с консолью Node.js.

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

• port <число> Порт для прослушивания подключений инспектора. Необязательно. По умолчанию: то, что было указано в командной строке.
• host <строка> Хост для прослушивания подключений инспектора. Необязательно. По умолчанию: то, что было указано в командной строке.
• wait <логическое значение> Блокировать до подключения клиента. Необязательно. По умолчанию: false.
• Возвращает: <Disposable> Disposable, который вызывает inspector.close().

Активировать инспектор на хосте и порту. Эквивалентно node --inspect=[[host:]port], но может быть выполнено программно после запуска node.

Если wait равно true, будет блокировать выполнение, пока клиент не подключится к порту инспекции и управление потоком не будет передано клиенту отладчика.

См. предупреждение о безопасности в отношении использования параметра host.

inspector.url()

• Возвращает: <строка> | <неопределено>

Возвращает URL активного инспектора или undefined, если его нет.

$ 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 copy

inspector.waitForDebugger()

Блокирует выполнение, пока клиент (существующий или подключившийся позже) не отправит команду Runtime.runIfWaitingForDebugger.

Исключение будет выброшено, если активного инспектора нет.

Поддержка точек останова

Протокол Chrome DevTools Debugger домен позволяет inspector.Session подключиться к программе и установить точки останова для пошагового выполнения кода.

Однако, установку точек останова с сеансом inspector.Session в том же потоке, подключённым через session.connect(), следует избегать, поскольку программа, к которой подключается и приостанавливается, является самим отладчиком. Вместо этого, попробуйте подключиться к главному потоку через session.connectToMainThread() и установить точки останова в потоке worker или подключиться с программой отладчика через WebSocket-соединение.