API тайминга производительности

API тайминга производительности предоставляет реализацию спецификации W3C Performance Timeline. Цель API — поддержка сбора метрик производительности с высокой точностью. Это тот же API производительности, что и в современных веб-браузерах.

const { performance } = require('perf_hooks');
performance.mark('A');
doSomeLongRunningProcess(() => {
  performance.mark('B');
  performance.measure('A to B', 'A', 'B');
  const measure = performance.getEntriesByName('A to B')[0];
  console.log(measure.duration);
  // Prints the number of milliseconds between Mark 'A' and Mark 'B'
});

Класс: Performance

Данный Performance предоставляет доступ к данным метрик производительности. Единственный экземпляр этого класса предоставляется через свойство performance.

performance.clearEntries(name)

Удаляет все объекты записей производительности с entryType равным name из таймлайна производительности.

performance.clearFunctions([name])

• name <строка>

Если name не указан, удаляет все объекты PerformanceFunction из таймлайна производительности. Если name указан, удаляются записи с name.

performance.clearGC()

Удаляет все объекты записей производительности с entryType равным gc из таймлайна производительности.

performance.clearMarks([name])

• name <строка>

Если name не указан, удаляет все объекты PerformanceMark из таймлайна производительности. Если name указан, удаляется только метка с указанным именем.

performance.clearMeasures([name])

• name <строка>

Если name не указан, удаляет все объекты PerformanceMeasure из таймлайна производительности. Если name указан, удаляются только объекты, чьё performanceEntry.name совпадает с name.

performance.getEntries()

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

Возвращает список всех объектов PerformanceEntry в хронологическом порядке относительно performanceEntry.startTime.

performance.getEntriesByName(name[, type])

• name <строка>
• type <строка>
• Возвращает: <Массив>

Возвращает список всех объектов PerformanceEntry в хронологическом порядке относительно performanceEntry.startTime с performanceEntry.name равным name, и необязательно с performanceEntry.entryType равным type.

performance.getEntriesByType(type)

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

Возвращает список всех объектов PerformanceEntry в хронологическом порядке относительно performanceEntry.startTime с performanceEntry.entryType равным type.

performance.mark([name])

• name <строка>

Создаёт новую запись PerformanceMark в таймлайне производительности. PerformanceMark — это подкласс PerformanceEntry, у которого performanceEntry.entryType всегда 'mark', а performanceEntry.duration всегда 0. Метки производительности используются для маркировки значимых моментов в таймлайне производительности.

performance.maxEntries

Значение: <число>

Максимальное количество элементов Performance Entry, которые должны быть добавлены в таймлайн производительности. Это ограничение не строго соблюдается, но предупреждение будет выведено, если количество записей в таймлайне превысит это ограничение.

По умолчанию равно 150.

performance.measure(name, startMark, endMark)

• name <строка>
• startMark <строка>
• endMark <строка>

Создаёт новую запись PerformanceMeasure в таймлайне производительности. PerformanceMeasure — это подкласс PerformanceEntry, у которого performanceEntry.entryType всегда 'measure', а performanceEntry.duration измеряет количество миллисекунд, прошедших с момента startMark и endMark.

Аргумент startMark может идентифицировать существующую метку PerformanceMark в таймлайне производительности или любую из свойств временных меток, предоставленных классом PerformanceNodeTiming. Если названная метка startMark не существует, то startMark устанавливается в timeOrigin по умолчанию.

Аргумент endMark должен идентифицировать существующую метку PerformanceMark в таймлайне производительности или любое из свойств временных меток, предоставляемых классом PerformanceNodeTiming. Если названная метка endMark не существует, будет выброшено исключение.

performance.nodeTiming

• <PerformanceNodeTiming>

Экземпляр класса PerformanceNodeTiming, предоставляющий метрики производительности для конкретных вех Node.js.

performance.now()

• Возвращает: <число>

Возвращает текущую отметку времени в миллисекундах с высокой точностью, где 0 соответствует началу текущего процесса node.

performance.timeOrigin

• <число>

Значение timeOrigin указывает отметку времени в миллисекундах с высокой точностью, в которой начался текущий процесс node, измеренную в Unix time.

performance.timerify(fn)

• fn <Функция>

Оборачивает функцию в новую функцию, которая измеряет время выполнения обернутой функции. Функция PerformanceObserver должна быть подписана на тип события 'function' для доступа к данным тайминга.

const {
  performance,
  PerformanceObserver
} = require('perf_hooks');

function someFunction() {
  console.log('hello world');
}

const wrapped = performance.timerify(someFunction);

const obs = new PerformanceObserver((list) => {
  console.log(list.getEntries()[0].duration);
  obs.disconnect();
  performance.clearFunctions();
});
obs.observe({ entryTypes: ['function'] });

// A performance timeline entry will be created
wrapped();

Класс: PerformanceEntry

performanceEntry.duration

• <число>

Общее количество миллисекунд, затраченных на эту запись. Это значение не будет иметь смысла для всех типов записей Performance Entry.

performanceEntry.name

• <строка>

Имя записи производительности.

performanceEntry.startTime

• <число>

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

performanceEntry.entryType

• <строка>

Тип записи производительности. В настоящее время это может быть: 'node', 'mark', 'measure', 'gc', или 'function'.

performanceEntry.kind

• <число>

Когда performanceEntry.entryType равно 'gc', свойство performance.kind определяет тип операции сборки мусора, которая произошла. Значение может быть одним из следующих:

• perf_hooks.constants.NODE_PERFORMANCE_GC_MAJOR
• perf_hooks.constants.NODE_PERFORMANCE_GC_MINOR
• perf_hooks.constants.NODE_PERFORMANCE_GC_INCREMENTAL
• perf_hooks.constants.NODE_PERFORMANCE_GC_WEAKCB

Класс: PerformanceNodeTiming расширяет PerformanceEntry

Предоставляет детали времени выполнения самого Node.js.

performanceNodeTiming.bootstrapComplete

• <число>

Отметка времени в миллисекундах с высокой точностью, когда процесс Node.js завершил загрузку. Если загрузка ещё не завершена, свойство имеет значение -1.

performanceNodeTiming.clusterSetupEnd

• <число>

Отметка времени в миллисекундах с высокой точностью, когда обработка кластеров закончилась. Если обработка кластеров ещё не завершена, свойство имеет значение -1.

performanceNodeTiming.clusterSetupStart

• <число>

Отметка времени в миллисекундах с высокой точностью, когда началась обработка кластеров. Если обработка кластеров ещё не началась, свойство имеет значение -1.

performanceNodeTiming.loopExit

• <число>

Отметка времени в миллисекундах с высокой точностью, когда цикл событий Node.js завершился. Если цикл событий ещё не завершился, свойство имеет значение -1. Оно может иметь значение, отличное от -1, только в обработчике события 'exit'.

performanceNodeTiming.loopStart

• <число>

Отметка времени в миллисекундах с высокой точностью, когда начался цикл событий Node.js. Если цикл событий ещё не начался (например, в первом такте основного скрипта), свойство имеет значение -1.

performanceNodeTiming.moduleLoadEnd

• <число>

Отметка времени в миллисекундах с высокой точностью, когда завершилась загрузка основного модуля.

performanceNodeTiming.moduleLoadStart

• <число>

Отметка времени в миллисекундах с высокой точностью, когда началась загрузка основного модуля.

performanceNodeTiming.nodeStart

• <число>

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

performanceNodeTiming.preloadModuleLoadEnd

• <число>

Отметка времени в миллисекундах с высокой точностью, когда завершилась загрузка предварительно загруженного модуля.

performanceNodeTiming.preloadModuleLoadStart

• <число>

Отметка времени в миллисекундах с высокой точностью, когда началась загрузка предварительно загруженного модуля.

performanceNodeTiming.thirdPartyMainEnd

• <число>

Отметка времени в миллисекундах с высокой точностью, когда завершилась обработка third_party_main. Если обработка third_party_main ещё не завершена, свойство имеет значение -1.

performanceNodeTiming.thirdPartyMainStart

• <число>

Отметка времени в миллисекундах с высокой точностью, когда началась обработка third_party_main. Если обработка third_party_main ещё не началась, свойство имеет значение -1.

performanceNodeTiming.v8Start

• <число>

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

Класс: PerformanceObserver(callback)

• callback <Функция> Обратная функция вызова PerformanceObserverCallback.

Объекты PerformanceObserver предоставляют уведомления, когда новые экземпляры PerformanceEntry добавлены в хронологию производительности.

const {
  performance,
  PerformanceObserver
} = require('perf_hooks');

const obs = new PerformanceObserver((list, observer) => {
  console.log(list.getEntries());
  observer.disconnect();
});
obs.observe({ entryTypes: ['mark'], buffered: true });

performance.mark('test');

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

Обратная функция: PerformanceObserverCallback(list, observer)

• list <СписокPerformanceObserverEntry>
• observer <PerformanceObserver>

Функция вызова PerformanceObserverCallback вызывается, когда PerformanceObserver получает уведомление о новых экземплярах PerformanceEntry. Обратная функция получает экземпляр PerformanceObserverEntryList и ссылку на PerformanceObserver.

Класс: PerformanceObserverEntryList

Класс PerformanceObserverEntryList используется для предоставления доступа к экземплярам PerformanceEntry, передаваемых в PerformanceObserver.

performanceObserverEntryList.getEntries()

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

Возвращает список объектов PerformanceEntry в хронологическом порядке относительно performanceEntry.startTime.

performanceObserverEntryList.getEntriesByName(name[, type])

• name <строка>
• type <строка>
• Возвращает: <Массив>

Возвращает список объектов PerformanceEntry в хронологическом порядке относительно performanceEntry.startTime, чьё performanceEntry.name равно name, и необязательно, чьё performanceEntry.entryType равно type.

performanceObserverEntryList.getEntriesByType(type)

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

Возвращает список объектов PerformanceEntry в хронологическом порядке относительно performanceEntry.startTime чьё performanceEntry.entryType равно type.

performanceObserver.disconnect()

Отключает экземпляр PerformanceObserver от всех уведомлений.

performanceObserver.observe(options)

• options <Объект>
  • entryTypes <Массив> Массив строк, идентифицирующих типы экземпляров PerformanceEntry , в которых заинтересован наблюдатель. Если не указан, будет выброшено исключение.
  • buffered <логическое> Если true, функция обратного вызова уведомлений будет вызвана с setImmediate(), и несколько уведомлений о экземплярах PerformanceEntry будут буферизованы внутри. Если false, уведомления будут мгновенными и синхронными. По умолчанию: false.

Подписывает экземпляр PerformanceObserver на уведомления о новых экземплярах PerformanceEntry, идентифицируемых по options.entryTypes.

Когда options.buffered является false, экземпляр callback будет вызван один раз для каждого экземпляра PerformanceEntry.

const {
  performance,
  PerformanceObserver
} = require('perf_hooks');

const obs = new PerformanceObserver((list, observer) => {
  // called three times synchronously. list contains one item
});
obs.observe({ entryTypes: ['mark'] });

for (let n = 0; n < 3; n++)
  performance.mark(`test${n}`);

const {
  performance,
  PerformanceObserver
} = require('perf_hooks');

const obs = new PerformanceObserver((list, observer) => {
  // called once. list contains three items
});
obs.observe({ entryTypes: ['mark'], buffered: true });

for (let n = 0; n < 3; n++)
  performance.mark(`test${n}`);

Примеры

Измерение продолжительности асинхронных операций

Следующий пример использует Async Hooks и Performance API для измерения фактической продолжительности операции Timeout (включая время выполнения обратного вызова).

'use strict';
const async_hooks = require('async_hooks');
const {
  performance,
  PerformanceObserver
} = require('perf_hooks');

const set = new Set();
const hook = async_hooks.createHook({
  init(id, type) {
    if (type === 'Timeout') {
      performance.mark(`Timeout-${id}-Init`);
      set.add(id);
    }
  },
  destroy(id) {
    if (set.has(id)) {
      set.delete(id);
      performance.mark(`Timeout-${id}-Destroy`);
      performance.measure(`Timeout-${id}`,
                          `Timeout-${id}-Init`,
                          `Timeout-${id}-Destroy`);
    }
  }
});
hook.enable();

const obs = new PerformanceObserver((list, observer) => {
  console.log(list.getEntries()[0]);
  performance.clearMarks();
  performance.clearMeasures();
  observer.disconnect();
});
obs.observe({ entryTypes: ['measure'], buffered: true });

setTimeout(() => {}, 1000);

Измерение времени загрузки зависимостей

Следующий пример измеряет продолжительность операций require() для загрузки зависимостей:

'use strict';
const {
  performance,
  PerformanceObserver
} = require('perf_hooks');
const mod = require('module');

// Monkey patch the require function
mod.Module.prototype.require =
  performance.timerify(mod.Module.prototype.require);
require = performance.timerify(require);

// Activate the observer
const obs = new PerformanceObserver((list) => {
  const entries = list.getEntries();
  entries.forEach((entry) => {
    console.log(`require('${entry[0]}')`, entry.duration);
  });
  obs.disconnect();
  // Free memory
  performance.clearFunctions();
});
obs.observe({ entryTypes: ['function'], buffered: true });

require('some-module');