Инспектор

Исходный код: lib/inspector.js

Модуль inspector предоставляет API для взаимодействия с инспектором V8.

К нему можно получить доступ, используя:

const inspector = require('inspector');

inspector.close()

Деактивировать инспектор. Блокирует выполнение, пока нет активных подключений.

inspector.console

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

require('inspector').console.log('a message');

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

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

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

Активировать инспектор на указанном хосте и порту. Эквивалентно 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

inspector.waitForDebugger()

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

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

Класс: inspector.Session

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

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

new inspector.Session()

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

Событие: 'inspectorNotification'

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

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

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

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

Событие: <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' ]

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

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

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

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

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

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

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

const inspector = require('inspector');
const fs = require('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));
      }
    });
  });
});

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

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

const inspector = require('inspector');
const fs = require('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);
});