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 Protocol, объявленные V8. Домен Chrome DevTools Protocol предоставляет интерфейс для взаимодействия с одним из агентов выполнения, используемых для инспекции состояния приложения и прослушивания событий выполнения.

Нельзя установить 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 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()

• Возвращает: <строка> | <undefined>

Возвращает 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.