Инспектор

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

К нему можно обратиться следующим образом:

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

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

или

import * as inspector from 'node:inspector';

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

API промисов

Класс: inspector.Session

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

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

new inspector.Session()

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

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

Событие: 'inspectorNotification'

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

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

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

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

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

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

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

session.connect()

Подключает сессию к серверной части инспектора.

session.connectToMainThread()

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

session.disconnect()

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

session.post(method[, params])

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

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

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

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

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

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

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

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

Пример использования профилировщика ЦП:

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

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

Пример использования профилировщика кучи:

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

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

Класс: inspector.Session

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

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

new inspector.Session()

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

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

Событие: 'inspectorNotification'

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

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

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

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

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

Event: <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' ]
jscopy

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

session.connect()

Подключает сессию к серверной части инспектора.

session.connectToMainThread()

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

session.disconnect()

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

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

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

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

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

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

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

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

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

Ниже приведён пример использования профилировщика ЦП:

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

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

Ниже приведён пример использования профилировщика кучи:

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

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

inspector.close()

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

inspector.console

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

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

Консоль инспектора не полностью соответствует 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/learn/getting-started/debugging
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/learn/getting-started/debugging
ws://localhost:3000/51cf8d0e-3c36-4c59-8efd-54519839e56a

$ node -p 'inspector.url()'
undefined
consolecopy

inspector.waitForDebugger()

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

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

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

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

// The `Network.requestWillBeSent` event will be fired.
inspector.Network.requestWillBeSent({
  requestId: 'request-id-1',
  timestamp: Date.now() / 1000,
  wallTime: Date.now(),
  request: {
    url: 'https://nodejs.org/en',
    method: 'GET',
  },
});
jscopy

inspector.Network.dataReceived([params])

• params <Object>

Эта функция доступна только при включенном флаге --experimental-network-inspection.

Рассылает подключенным интерфейсам событие Network.dataReceived или буферизует данные, если для данного запроса еще не была вызвана команда Network.streamResourceContent.

Также включает команду Network.getResponseBody для получения данных ответа.

inspector.Network.dataSent([params])

• params <Object>

Эта функция доступна только при включенном флаге --experimental-network-inspection.

Включает команду Network.getRequestPostData для получения данных запроса.

inspector.Network.requestWillBeSent([params])

• params <Object>

Эта функция доступна только при включенном флаге --experimental-network-inspection.

Рассылает подключенным интерфейсам событие Network.requestWillBeSent. Это событие указывает на то, что приложение собирается отправить HTTP-запрос.

inspector.Network.responseReceived([params])

• params <Object>

Эта функция доступна только при включенном флаге --experimental-network-inspection.

Рассылает подключенным интерфейсам событие Network.responseReceived. Это событие указывает на то, что HTTP-ответ доступен.

inspector.Network.loadingFinished([params])

• params <Object>

Эта функция доступна только при включенном флаге --experimental-network-inspection.

Рассылает подключенным интерфейсам событие Network.loadingFinished. Это событие указывает на то, что загрузка HTTP-запроса завершена.

inspector.Network.loadingFailed([params])

• params <Object>

Эта функция доступна только при включенном флаге --experimental-network-inspection.

Рассылает подключенным интерфейсам событие Network.loadingFailed. Это событие указывает на то, что загрузка HTTP-запроса завершилась с ошибкой.

inspector.Network.webSocketCreated([params])

• params <Object>

Эта функция доступна только при включенном флаге --experimental-network-inspection.

Рассылает подключенным интерфейсам событие Network.webSocketCreated. Это событие указывает на то, что было инициировано соединение WebSocket.

inspector.Network.webSocketHandshakeResponseReceived([params])

• params <Object>

Эта функция доступна только при включенном флаге --experimental-network-inspection.

Рассылает подключенным интерфейсам событие Network.webSocketHandshakeResponseReceived. Это событие указывает на то, что получен ответ на рукопожатие WebSocket.

inspector.Network.webSocketClosed([params])

• params <Object>

Эта функция доступна только при включенном флаге --experimental-network-inspection.

Рассылает подключенным интерфейсам событие Network.webSocketClosed. Это событие указывает на то, что соединение WebSocket было закрыто.

inspector.NetworkResources.put

Эта функция доступна только при включенном флаге --experimental-inspector-network-resource.

Метод inspector.NetworkResources.put используется для предоставления ответа на запрос loadNetworkResource, отправленный через Chrome DevTools Protocol (CDP). Обычно это происходит, когда карта исходного кода указана как URL-адрес, а интерфейс DevTools — например, Chrome — запрашивает ресурс, чтобы получить карту исходного кода.

Этот метод позволяет разработчикам заранее определить содержимое ресурса, которое будет предоставлено в ответ на такие запросы CDP.

const inspector = require('node:inspector');
// By preemptively calling put to register the resource, a source map can be resolved when
// a loadNetworkResource request is made from the frontend.
async function setNetworkResources() {
  const mapUrl = 'http://localhost:3000/dist/app.js.map';
  const tsUrl = 'http://localhost:3000/src/app.ts';
  const distAppJsMap = await fetch(mapUrl).then((res) => res.text());
  const srcAppTs = await fetch(tsUrl).then((res) => res.text());
  inspector.NetworkResources.put(mapUrl, distAppJsMap);
  inspector.NetworkResources.put(tsUrl, srcAppTs);
};
setNetworkResources().then(() => {
  require('./dist/app');
});
jscopy

Дополнительные сведения см. в официальной документации CDP: Network.loadNetworkResource

inspector.DOMStorage.domStorageItemAdded

• params <Object>
  • storageId <Object>
    • securityOrigin <string>
    • storageKey <string>
    • isLocalStorage <boolean>
  • key <string>
  • newValue <string>

Эта функция доступна только при включённом флаге --experimental-storage-inspection.

Отправляет событие DOMStorage.domStorageItemAdded подключённым интерфейсам. Это событие указывает на то, что в хранилище был добавлен новый элемент.

inspector.DOMStorage.domStorageItemRemoved

• params <Object>
  • storageId <Object>
    • securityOrigin <string>
    • storageKey <string>
    • isLocalStorage <boolean>
  • key <string>

Эта функция доступна только при включённом флаге --experimental-storage-inspection.

Отправляет событие DOMStorage.domStorageItemRemoved подключённым интерфейсам. Это событие указывает на то, что элемент был удалён из хранилища.

inspector.DOMStorage.domStorageItemUpdated

• params <Object>
  • storageId <Object>
    • securityOrigin <string>
    • storageKey <string>
    • isLocalStorage <boolean>
  • key <string>
  • oldValue <string>
  • newValue <string>

Эта функция доступна только при включённом флаге --experimental-storage-inspection.

Отправляет событие DOMStorage.domStorageItemUpdated подключённым интерфейсам. Это событие указывает на то, что элемент хранилища был обновлён.

inspector.DOMStorage.domStorageItemsCleared

• params <Object>
  • storageId <Object>
    • securityOrigin <string>
    • storageKey <string>
    • isLocalStorage <boolean>

Эта функция доступна только при включённом флаге --experimental-storage-inspection.

Отправляет событие DOMStorage.domStorageItemsCleared подключённым интерфейсам. Это событие указывает на то, что все элементы хранилища были удалены.

inspector.DOMStorage.registerStorage

• params <Object>
  • isLocalStorage <boolean>
  • storageMap <Object>

Эта функция доступна только при включённом флаге --experimental-storage-inspection.

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

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

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