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

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

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

const obs = new PerformanceObserver((items) => {
  console.log(items.getEntries()[0].duration);
  performance.clearMarks();
});
obs.observe({ entryTypes: ['measure'] });

performance.mark('A');
doSomeLongRunningProcess(() => {
  performance.mark('B');
  performance.measure('A to B', 'A', 'B');
});

Класс: Performance

performance.clearMarks([name])

• name <строка>

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

performance.mark([name])

• name <строка>

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

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-времени.

performance.timerify(fn)

• fn <Функция>

Оборачивает функцию в новую функцию, которая измеряет время выполнения обернутой функции. Для доступа к данным тайминга необходимо подписаться на событие '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();
});
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', или 'http2'.

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.loopExit

• <число>

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

performanceNodeTiming.loopStart

• <число>

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

performanceNodeTiming.nodeStart

• <число>

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

performanceNodeTiming.v8Start

• <число>

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

Класс: PerformanceObserver[src]

new PerformanceObserver(callback)[src]

• callback <Функция>

  • list <Список записей PerformanceObserver>
  • observer <PerformanceObserver>

Объекты 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 вводят свой дополнительный накладные расходы на производительность, экземпляры не должны оставаться подписанными на уведомления неопределённое время. Пользователи должны отсоединять наблюдателей, как только они больше не нужны.

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

performanceObserver.disconnect()[src]

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

performanceObserver.observe(options)[src]

• 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}`);

Класс: PerformanceObserverEntryList

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

performanceObserverEntryList.getEntries()

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

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

performanceObserverEntryList.getEntriesByName(name[, type])

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

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

performanceObserverEntryList.getEntriesByType(type)

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

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

Примеры

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

В следующем примере используются 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();
  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();
});
obs.observe({ entryTypes: ['function'], buffered: true });

require('some-module');