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

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

Трассировка может быть включена с помощью флага командной строки --trace-event-categories или с использованием модуля 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.fs.sync - Включает захват данных трассировки для методов синхронного доступа к файловой системе.

• node.perf - Включает захват измерений API производительности.

  • node.perf.usertiming - Включает захват только измерений и отметок пользовательского времени API производительности.
  • node.perf.timerify - Включает захват только измерений timerify API производительности.
• node.promises.rejections - Включает захват данных трассировки, отслеживающих количество необработанных отклонений Promise и обработанных отклонений после них.
• node.vm.script - Включает захват данных трассировки для методов vm модуля runInNewContext(), runInContext(), и runInThisContext().
• v8 - События V8 относятся к GC, компиляции и выполнению.

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

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

Предыдущие версии 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

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

const trace_events = require('trace_events');
const tracing = trace_events.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

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

Модуль trace_events

Tracing объект

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

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

tracing.categories

• <строка>

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

tracing.disable()

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

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

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

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

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

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

tracing.enable()

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

tracing.enabled

• <логическое значение> true только если объект Tracing был включен.

trace_events.createTracing(options)

• options <Объект>

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

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

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

trace_events.getEnabledCategories()

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

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

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

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

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

console.log(trace_events.getEnabledCategories());