События отслеживания

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

Модуль trace_events предоставляет механизм для централизации информации об отслеживании, генерируемой кодом 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.dns.native: Включает захват данных отслеживания для запросов DNS.
• node.environment: Включает захват вех ключевых моментов среды Node.js.
• node.fs.sync: Включает захват данных отслеживания для синхронных методов файловой системы.
• node.perf: Включает захват измерений API производительности Performance API.
  • node.perf.usertiming: Включает захват только измерений и меток пользовательского тайминга Performance API.
  • node.perf.timerify: Включает захват только измерений timerify Performance 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

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

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

Модуль 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());