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

[Стабильно: 1 - Экспериментально]

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

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

Модуль 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: Включает захват измерений Performance API.

  • node.perf.usertiming: Включает захват только измерений и меток User Timing Performance API.
  • node.perf.timerify: Включает захват только измерений Performance API timerify.

• node.promises.rejections: Включает захват данных трассировки, отслеживающих количество необработанных отклонений Promise и обработанных после отклонений.

• node.vm.script: Включает захват данных трассировки для методов runInNewContext(), runInContext() и runInThisContext() модуля node:vm.

• v8: События V8 связаны с GC, компиляцией и выполнением.

• node.http: Включает захват данных трассировки для HTTP-запросов/ответов.

• node.module_timer: Включает захват данных трассировки для загрузки модулей CJS.

По умолчанию включены категории 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

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

const trace_events = require('node:trace_events')
const tracing = trace_events.createTracing({ categories: ['node.perf'] })
tracing.enable() // Включить захват событий трассировки для категории 'node.perf'

// выполнить работу

tracing.disable() // Отключить захват событий трассировки для категории 'node.perf'

Запуск 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

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

process.on('SIGINT', function onSigint() {
  console.info('Received SIGINT.')
  process.exit(130) // Или соответствующий код выхода в зависимости от ОС и сигнала
})

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

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

Модуль node:trace_events

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

Объект Tracing

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

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

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

tracing.categories

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

• <string>

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

tracing.disable()

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

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

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

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

// Выводит 'node,node.perf,v8'
console.log(trace_events.getEnabledCategories())

t2.disable() // Отключит только генерацию категории 'node.perf'

// Выводит 'node,v8'
console.log(trace_events.getEnabledCategories())

tracing.enable()

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

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

tracing.enabled

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

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

trace_events.createTracing(options)

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

• options <Object>

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

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

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

const trace_events = require('node:trace_events')
const categories = ['node.perf', 'node.async_hooks']
const tracing = trace_events.createTracing({ categories })
tracing.enable()
// выполнение действий
tracing.disable()

trace_events.getEnabledCategories()

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

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

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

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

const trace_events = require('node: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())

Примеры

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

'use strict'

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', () => {
    // завершено
  })
  const traceConfig = { includedCategories: ['v8'] }
  await post('NodeTracing.start', { traceConfig })
  // выполнить какое-либо действие
  setTimeout(() => {
    post('NodeTracing.stop').then(() => {
      session.disconnect()
      console.log(data)
    })
  }, 1000)
}

collect()