Инспектор¶

Стабильность: 2 – Стабильная

API является удовлетворительным. Совместимость с npm имеет высший приоритет и не будет нарушена, кроме случаев явной необходимости.

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

Доступ:

MJSCJS

import * as inspector from 'node:inspector/promises';

const inspector = require('node:inspector/promises');

или

MJSCJS

import * as inspector from 'node:inspector';

const inspector = require('node:inspector');

API на промисах¶

Стабильность: 1 – Экспериментальная

Эта возможность изменяется и может быть изменена или удалена в последующих версиях.

Класс: `inspector.Session`¶

Расширяет: EventEmitter

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

`new inspector.Session()`¶

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

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

Событие: `'inspectorNotification'`¶

Тип: <Object> объект сообщения-уведомления

Генерируется при получении любого уведомления от V8 Inspector.

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

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

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

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

Тип: <Object> объект сообщения-уведомления

Генерируется при получении уведомления инспектора, у которого поле 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])`¶

method <string>
params <Object>
Возвращает: <Promise>

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

MJS

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

Актуальная версия протокола V8 inspector опубликована в Chrome DevTools Protocol Viewer.

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

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

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

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

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

MJS

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');
// Здесь вызывается измеряемая бизнес-логика...

// спустя время...
const { profile } = await session.post('Profiler.stop');

// Запись профиля на диск, загрузка и т.д.
fs.writeFileSync('./profile.cpuprofile', JSON.stringify(profile));

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

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

MJS

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

API с колбэками¶

Класс: `inspector.Session`¶

Расширяет: EventEmitter

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

`new inspector.Session()`¶

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

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

Событие: `'inspectorNotification'`¶

Тип: <Object> объект сообщения-уведомления

Генерируется при получении любого уведомления от V8 Inspector.

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

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

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

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

Тип: <Object> объект сообщения-уведомления

Генерируется при получении уведомления инспектора, у которого поле 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])`¶

Добавлено в: v8.0.0

method <string>
params <Object>
callback <Function>

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

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

Актуальная версия протокола V8 inspector опубликована в Chrome DevTools Protocol Viewer.

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

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

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

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

Профилировщик 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', () => {
        // Здесь вызывается измеряемая бизнес-логика...

        // спустя время...
        session.post(
            'Profiler.stop',
            (err, { profile }) => {
                // Запись профиля на диск, загрузка и т.д.
                if (!err) {
                    fs.writeFileSync(
                        './profile.cpuprofile',
                        JSON.stringify(profile)
                    );
                }
            }
        );
    });
});

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

Пример использования 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);
    }
);

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

`inspector.close()`¶

Добавлено в: v9.0.0

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

`inspector.console`¶

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

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

Консоль инспектора не дублирует API консоли Node.js полностью.

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

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

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

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

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

`inspector.url()`¶

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

`inspector.waitForDebugger()`¶

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

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

Интеграция с DevTools¶

Стабильность: 1.1 – активная разработка

API может существенно меняться между минорными версиями. Используйте с осторожностью.

Модуль node:inspector предоставляет API для интеграции с инструментами разработки, поддерживающими Chrome DevTools Protocol. Подключённые к работающему процессу Node.js клиенты DevTools могут получать события протокола и отображать их для упрощения отладки. Следующие методы рассылают событие протокола всем подключённым клиентам. Параметр params у методов может быть необязательным в зависимости от протокола.

// Будет сгенерировано событие `Network.requestWillBeSent`.
inspector.Network.requestWillBeSent({
    requestId: 'request-id-1',
    timestamp: Date.now() / 1000,
    wallTime: Date.now(),
    request: {
        url: 'https://nodejs.org/en',
        method: 'GET',
    },
});