События трассировки

Модуль node:trace_events предоставляет механизм для централизованного сбора информации трассировки, генерируемой V8, ядром Node.js и пользовательским кодом.

Трассировку можно включить с помощью флага командной строки --trace-event-categories или используя модуль node:trace_events. Флаг --trace-event-categories принимает список имен категорий, разделенных запятыми.

Доступны следующие категории:

• node: пустой заполнитель.
• node.async_hooks: включает сбор подробных данных трассировки async_hooks. События async_hooks имеют уникальный asyncId и специальное свойство triggerId triggerAsyncId.
• node.bootstrap: включает сбор данных о ключевых этапах загрузки Node.js.
• node.console: включает сбор вывода console.time() и console.count().
• node.threadpoolwork.sync: включает сбор данных трассировки для синхронных операций пула потоков, таких как blob, zlib, crypto и node_api.
• node.threadpoolwork.async: включает сбор данных трассировки для асинхронных операций пула потоков, таких как blob, zlib, crypto и node_api.
• node.dns.native: включает сбор данных трассировки для DNS-запросов.
• node.net.native: включает сбор данных трассировки для сети.
• node.environment: включает сбор данных о ключевых этапах окружения Node.js.
• node.fs.sync: включает сбор данных трассировки для синхронных методов файловой системы.
• node.fs_dir.sync: включает сбор данных трассировки для синхронных методов работы с каталогами файловой системы.
• node.fs.async: включает сбор данных трассировки для асинхронных методов файловой системы.
• node.fs_dir.async: включает сбор данных трассировки для асинхронных методов работы с каталогами файловой системы.
• node.perf: включает сбор измерений API производительности.
  • node.perf.usertiming: включает сбор только отметок и измерений пользовательского времени API производительности.
  • node.perf.timerify: включает сбор только измерений timerify API производительности.
• node.promises.rejections: включает сбор данных трассировки, отслеживающих количество необработанных отклонений Promise и отклонений, обработанных после возникновения.
• node.vm.script: включает сбор данных трассировки для методов runInNewContext(), runInContext() и runInThisContext() модуля node:vm.
• v8: события V8 связаны со сборкой мусора, компиляцией и выполнением.
• node.http: включает сбор данных трассировки для HTTP-запросов и ответов.
• node.module_timer: включает сбор данных трассировки для загрузки модулей CJS.

По умолчанию включены категории node, node.async_hooks и v8.

node --trace-event-categories v8,node,node.async_hooks server.js
bashcopy

В предыдущих версиях Node.js для включения событий трассировки требовалось использовать флаг --trace-events-enabled. Это требование было отменено. Однако флаг --trace-events-enabled по-прежнему можно использовать; по умолчанию он включает категории событий трассировки node, node.async_hooks и v8.

node --trace-events-enabled

# is equivalent to

node --trace-event-categories v8,node,node.async_hooks
bashcopy

Кроме того, события трассировки можно включить с помощью модуля node:trace_events:

import { createTracing } from 'node:trace_events';
const tracing = createTracing({ categories: ['node.perf'] });
tracing.enable();  // Enable trace event capture for the 'node.perf' category

// do work

tracing.disable();  // Disable trace event capture for the 'node.perf' category

const { createTracing } = require('node:trace_events');
const tracing = createTracing({ categories: ['node.perf'] });
tracing.enable();  // Enable trace event capture for the 'node.perf' category

// do work

tracing.disable();  // Disable trace event capture for the 'node.perf' category

При запуске Node.js с включенной трассировкой создаются файлы журналов, которые можно открыть на вкладке chrome://tracing в Chrome.

По умолчанию файл журнала называется node_trace.${rotation}.log, где ${rotation} — идентификатор ротации журнала, увеличивающийся при каждом изменении. Шаблон пути к файлу можно задать с помощью --trace-event-file-pattern, принимающего строку шаблона с поддержкой ${rotation} и ${pid}:

node --trace-event-categories v8 --trace-event-file-pattern '${pid}-${rotation}.log' server.js
bashcopy

Чтобы гарантировать корректное создание файла журнала после таких событий-сигналов, как SIGINT, SIGTERM или SIGBREAK, убедитесь, что в коде предусмотрены соответствующие обработчики, например:

process.on('SIGINT', function onSigint() {
  console.info('Received SIGINT.');
  process.exit(130);  // Or applicable exit code depending on OS and signal
});
jscopy

Система трассировки использует тот же источник времени, что и process.hrtime(). Однако временные метки событий трассировки выражены в микросекундах, в отличие от process.hrtime(), который возвращает наносекунды.

Возможности этого модуля недоступны в потоках Worker.

Модуль node:trace_events

Объект Tracing

Объект Tracing используется для включения или отключения трассировки наборов категорий. Экземпляры создаются с помощью метода trace_events.createTracing().

При создании объект Tracing отключен. Вызов метода tracing.enable() добавляет категории в набор включенных категорий событий трассировки. Вызов tracing.disable() удаляет категории из набора включенных категорий событий трассировки.

tracing.categories

• Тип: <string>

Список категорий событий трассировки, охватываемых этим объектом Tracing, разделенный запятыми.

tracing.disable()

Отключает этот объект Tracing.

Будут отключены только те категории событий трассировки, которые не охватываются другими включенными объектами Tracing и не указаны флагом --trace-event-categories.

import { createTracing, getEnabledCategories } from 'node:trace_events';
const t1 = createTracing({ categories: ['node', 'v8'] });
const t2 = createTracing({ categories: ['node.perf', 'node'] });
t1.enable();
t2.enable();

// Prints 'node,node.perf,v8'
console.log(getEnabledCategories());

t2.disable(); // Will only disable emission of the 'node.perf' category

// Prints 'node,v8'
console.log(getEnabledCategories());

const { createTracing, getEnabledCategories } = require('node:trace_events');
const t1 = createTracing({ categories: ['node', 'v8'] });
const t2 = createTracing({ categories: ['node.perf', 'node'] });
t1.enable();
t2.enable();

// Prints 'node,node.perf,v8'
console.log(getEnabledCategories());

t2.disable(); // Will only disable emission of the 'node.perf' category

// Prints 'node,v8'
console.log(getEnabledCategories());

tracing.enable()

Включает этот объект Tracing для набора категорий, охватываемых объектом Tracing.

tracing.enabled

• Тип: <boolean> true, только если объект Tracing включен.

trace_events.createTracing(options)

• options <Object>
  • categories <string[]> Массив имен категорий трассировки. Значения в массиве по возможности приводятся к строке. Если значение невозможно привести к строке, будет выброшена ошибка.
• Возвращает: <Tracing>.

Создает и возвращает объект Tracing для указанного набора categories.

import { createTracing } from 'node:trace_events';
const categories = ['node.perf', 'node.async_hooks'];
const tracing = createTracing({ categories });
tracing.enable();
// do stuff
tracing.disable();

const { createTracing } = require('node:trace_events');
const categories = ['node.perf', 'node.async_hooks'];
const tracing = createTracing({ categories });
tracing.enable();
// do stuff
tracing.disable();

trace_events.getEnabledCategories()

• Возвращает: <string>

Возвращает список всех включенных в данный момент категорий событий трассировки, разделенный запятыми. Текущий набор включенных категорий событий трассировки определяется объединением всех включенных в данный момент объектов Tracing и любых категорий, включенных с помощью флага --trace-event-categories.

Для приведенного ниже файла test.js команда node --trace-event-categories node.perf test.js выведет в консоль 'node.async_hooks,node.perf'.

import { createTracing, getEnabledCategories } from 'node:trace_events';
const t1 = createTracing({ categories: ['node.async_hooks'] });
const t2 = createTracing({ categories: ['node.perf'] });
const t3 = createTracing({ categories: ['v8'] });

t1.enable();
t2.enable();

console.log(getEnabledCategories());

const { createTracing, getEnabledCategories } = require('node:trace_events');
const t1 = createTracing({ categories: ['node.async_hooks'] });
const t2 = createTracing({ categories: ['node.perf'] });
const t3 = createTracing({ categories: ['v8'] });

t1.enable();
t2.enable();

console.log(getEnabledCategories());

Примеры

Сбор данных событий трассировки с помощью инспектора

import { Session } from 'node:inspector';
const session = new Session();
session.connect();

function post(message, data) {
  return new Promise((resolve, reject) => {
    session.post(message, data, (err, result) => {
      if (err)
        reject(new Error(JSON.stringify(err)));
      else
        resolve(result);
    });
  });
}

async function collect() {
  const data = [];
  session.on('NodeTracing.dataCollected', (chunk) => data.push(chunk));
  session.on('NodeTracing.tracingComplete', () => {
    // done
  });
  const traceConfig = { includedCategories: ['v8'] };
  await post('NodeTracing.start', { traceConfig });
  // do something
  setTimeout(() => {
    post('NodeTracing.stop').then(() => {
      session.disconnect();
      console.log(data);
    });
  }, 1000);
}

collect();

const { Session } = require('node:inspector');
const session = new Session();
session.connect();

function post(message, data) {
  return new Promise((resolve, reject) => {
    session.post(message, data, (err, result) => {
      if (err)
        reject(new Error(JSON.stringify(err)));
      else
        resolve(result);
    });
  });
}

async function collect() {
  const data = [];
  session.on('NodeTracing.dataCollected', (chunk) => data.push(chunk));
  session.on('NodeTracing.tracingComplete', () => {
    // done
  });
  const traceConfig = { includedCategories: ['v8'] };
  await post('NodeTracing.start', { traceConfig });
  // do something
  setTimeout(() => {
    post('NodeTracing.stop').then(() => {
      session.disconnect();
      console.log(data);
    });
  }, 1000);
}

collect();