API измерения производительности

Этот модуль предоставляет реализацию подмножества API производительности веба W3C, а также дополнительные API для измерения производительности, специфичного для Node.js.

Node.js поддерживает следующие API производительности веба:

• Время с высоким разрешением
• Временная шкала производительности
• Пользовательские измерения времени
• Измерение времени загрузки ресурсов

import { performance, PerformanceObserver } from 'node:perf_hooks';

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

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

  performance.mark('B');
  performance.measure('A to B', 'A', 'B');
});

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

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

performance.mark('A');
(async function doSomeLongRunningProcess() {
  await new Promise((r) => setTimeout(r, 5000));
  performance.measure('A to Now', 'A');

  performance.mark('B');
  performance.measure('A to B', 'A', 'B');
})();

perf_hooks.performance

Объект, который можно использовать для сбора метрик производительности текущего экземпляра Node.js. Он похож на window.performance в браузерах.

performance.clearMarks([name])

• name <string>

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

performance.clearMeasures([name])

• name <string>

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

performance.clearResourceTimings([name])

• name <string>

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

performance.eventLoopUtilization([utilization1[, utilization2]])

• utilization1 <Object> Результат предыдущего вызова eventLoopUtilization().
• utilization2 <Object> Результат предыдущего вызова eventLoopUtilization(), сделанного до utilization1.
• Возвращает: <Object>
  • idle <number>
  • active <number>
  • utilization <number>

Это псевдоним perf_hooks.eventLoopUtilization().

Это свойство является расширением Node.js. Оно недоступно в веб-браузерах.

performance.getEntries()

• Возвращает: <PerformanceEntry[]>

Возвращает список объектов PerformanceEntry в хронологическом порядке относительно performanceEntry.startTime. Если вас интересуют только записи производительности определенных типов или с определенными именами, см. performance.getEntriesByType() и performance.getEntriesByName().

performance.getEntriesByName(name[, type])

• name <string>
• type <string>
• Возвращает: <PerformanceEntry[]>

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

performance.getEntriesByType(type)

• type <string>
• Возвращает: <PerformanceEntry[]>

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

performance.mark(name[, options])

• name <string>
• options <Object>
  • detail <any> Дополнительные необязательные сведения, добавляемые к отметке.
  • startTime <number> Необязательная временная метка, используемая в качестве времени отметки. По умолчанию: performance.now().

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

Созданная запись PerformanceMark помещается в глобальную временную шкалу производительности и может быть получена с помощью performance.getEntries, performance.getEntriesByName и performance.getEntriesByType. После выполнения наблюдения записи необходимо вручную удалить из глобальной временной шкалы производительности с помощью performance.clearMarks.

performance.markResourceTiming(timingInfo, requestedUrl, initiatorType, global, cacheMode, bodyInfo, responseStatus[, deliveryType])

• timingInfo <Object> Сведения о времени Fetch
• requestedUrl <string> URL ресурса
• initiatorType <string> Имя инициатора, например: 'fetch'
• global <Object>
• cacheMode <string> Режим кэша должен быть пустой строкой ('') или 'local'
• bodyInfo <Object> Сведения о теле ответа Fetch
• responseStatus <number> Код состояния ответа
• deliveryType <string> Тип доставки. По умолчанию: ''.

Это свойство является расширением Node.js. Оно недоступно в веб-браузерах.

Создает новую запись PerformanceResourceTiming во временной шкале ресурсов. PerformanceResourceTiming — это подкласс PerformanceEntry, у которого performanceEntry.entryType всегда равно 'resource'. Ресурсы производительности используются для обозначения моментов во временной шкале ресурсов.

Созданная запись PerformanceMark помещается в глобальную временную шкалу ресурсов и может быть получена с помощью performance.getEntries, performance.getEntriesByName и performance.getEntriesByType. После выполнения наблюдения записи необходимо вручную удалить из глобальной временной шкалы производительности с помощью performance.clearResourceTimings.

performance.measure(name[, startMarkOrOptions[, endMark]])

• name <string>
• startMarkOrOptions <string> | <Object> Необязательный параметр.
  • detail <any> Дополнительные необязательные сведения, добавляемые к измерению.
  • duration <number> Продолжительность между временем начала и временем окончания.
  • end <number> | <string> Временная метка, используемая в качестве времени окончания, или строка, обозначающая ранее записанную отметку.
  • start <number> | <string> Временная метка, используемая в качестве времени начала, или строка, обозначающая ранее записанную отметку.
• endMark <string> Необязательный параметр. Его следует опустить, если startMarkOrOptions является <Object>.

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

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

Необязательный аргумент endMark должен указывать на любую существующую PerformanceMark во временной шкале производительности или на любое из свойств временной метки, предоставляемых классом PerformanceNodeTiming. endMark будет иметь значение performance.now(), если параметр не передан; в противном случае, если указанная endMark не существует, возникнет ошибка.

Созданная запись PerformanceMeasure помещается в глобальную временную шкалу производительности и может быть получена с помощью performance.getEntries, performance.getEntriesByName и performance.getEntriesByType. После выполнения наблюдения записи необходимо вручную удалить из глобальной временной шкалы производительности с помощью performance.clearMeasures.

performance.nodeTiming

• Тип: <PerformanceNodeTiming>

Это свойство является расширением Node.js. Оно недоступно в веб-браузерах.

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

performance.now()

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

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

performance.setResourceTimingBufferSize(maxSize)

Задает глобальный размер буфера измерения времени загрузки ресурсов равным указанному количеству объектов записей производительности типа "resource".

По умолчанию максимальный размер буфера равен 250.

performance.timeOrigin

• Тип: <number>

timeOrigin задает временную метку в миллисекундах с высоким разрешением, соответствующую моменту начала текущего процесса node, измеренному по времени Unix.

performance.timerify(fn[, options])

• fn <Function>
• options <Object>
  • histogram <RecordableHistogram> Объект гистограммы, созданный с помощью perf_hooks.createHistogram(), который будет записывать длительность выполнения в наносекундах.

Это псевдоним perf_hooks.timerify().

Это свойство является расширением Node.js. Оно недоступно в веб-браузерах.

performance.toJSON()

Объект, представляющий объект performance в формате JSON. Он похож на window.performance.toJSON в браузерах.

Событие: 'resourcetimingbufferfull'

Событие 'resourcetimingbufferfull' возникает, когда глобальный буфер измерения времени загрузки ресурсов заполнен. Измените размер буфера с помощью performance.setResourceTimingBufferSize() или очистите его с помощью performance.clearResourceTimings() в обработчике события, чтобы в буфер временной шкалы производительности можно было добавить больше записей.

Класс: PerformanceEntry

Конструктор этого класса напрямую пользователям не предоставляется.

performanceEntry.duration

• Тип: <number>

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

performanceEntry.entryType

• Тип: <string>

Тип записи производительности. Это может быть одно из следующих значений:

• 'dns' (только в Node.js)
• 'function' (только в Node.js)
• 'gc' (только в Node.js)
• 'http2' (только в Node.js)
• 'http' (только в Node.js)
• 'mark' (доступно в веб-браузерах)
• 'measure' (доступно в веб-браузерах)
• 'net' (только в Node.js)
• 'node' (только в Node.js)
• 'resource' (доступно в веб-браузерах)

performanceEntry.name

• Тип: <string>

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

performanceEntry.startTime

• Тип: <number>

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

Класс: PerformanceMark

• Расширяет: <PerformanceEntry>

Предоставляет отметки, созданные с помощью метода Performance.mark().

performanceMark.detail

• Тип: <any>

Дополнительные сведения, заданные при создании с помощью метода Performance.mark().

Класс: PerformanceMeasure

• Расширяет: <PerformanceEntry>

Предоставляет измерения, созданные с помощью метода Performance.measure().

Конструктор этого класса напрямую пользователям не предоставляется.

performanceMeasure.detail

• Тип: <any>

Дополнительные сведения, заданные при создании с помощью метода Performance.measure().

Класс: PerformanceNodeEntry

• Расширяет: <PerformanceEntry>

Этот класс является расширением Node.js. Он недоступен в веб-браузерах.

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

Конструктор этого класса напрямую пользователям не предоставляется.

performanceNodeEntry.detail

• Тип: <any>

Дополнительные сведения, относящиеся к entryType.

performanceNodeEntry.flags

• Тип: <number>

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

• perf_hooks.constants.NODE_PERFORMANCE_GC_FLAGS_NO
• perf_hooks.constants.NODE_PERFORMANCE_GC_FLAGS_CONSTRUCT_RETAINED
• perf_hooks.constants.NODE_PERFORMANCE_GC_FLAGS_FORCED
• perf_hooks.constants.NODE_PERFORMANCE_GC_FLAGS_SYNCHRONOUS_PHANTOM_PROCESSING
• perf_hooks.constants.NODE_PERFORMANCE_GC_FLAGS_ALL_AVAILABLE_GARBAGE
• perf_hooks.constants.NODE_PERFORMANCE_GC_FLAGS_ALL_EXTERNAL_MEMORY
• perf_hooks.constants.NODE_PERFORMANCE_GC_FLAGS_SCHEDULE_IDLE

performanceNodeEntry.kind

• Тип: <number>

Если 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

Подробное описание сборки мусора ('gc')

Когда performanceEntry.type равно 'gc', свойство performanceNodeEntry.detail будет объектом <Object> с двумя свойствами:

• kind <number> Одно из значений:
  • 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
• flags <number> Одно из значений:
  • perf_hooks.constants.NODE_PERFORMANCE_GC_FLAGS_NO
  • perf_hooks.constants.NODE_PERFORMANCE_GC_FLAGS_CONSTRUCT_RETAINED
  • perf_hooks.constants.NODE_PERFORMANCE_GC_FLAGS_FORCED
  • perf_hooks.constants.NODE_PERFORMANCE_GC_FLAGS_SYNCHRONOUS_PHANTOM_PROCESSING
  • perf_hooks.constants.NODE_PERFORMANCE_GC_FLAGS_ALL_AVAILABLE_GARBAGE
  • perf_hooks.constants.NODE_PERFORMANCE_GC_FLAGS_ALL_EXTERNAL_MEMORY
  • perf_hooks.constants.NODE_PERFORMANCE_GC_FLAGS_SCHEDULE_IDLE

Подробное описание HTTP ('http')

Когда performanceEntry.type равно 'http', свойство performanceNodeEntry.detail будет объектом <Object>, содержащим дополнительные сведения.

Если performanceEntry.name равно HttpClient, detail будет содержать следующие свойства: req, res. Свойство req будет объектом <Object>, содержащим method, url, headers, а свойство res будет объектом <Object>, содержащим statusCode, statusMessage, headers.

Если performanceEntry.name равно HttpRequest, detail будет содержать следующие свойства: req, res. Свойство req будет объектом <Object>, содержащим method, url, headers, а свойство res будет объектом <Object>, содержащим statusCode, statusMessage, headers.

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

Подробное описание HTTP/2 ('http2')

Когда performanceEntry.type равно 'http2', свойство performanceNodeEntry.detail будет объектом <Object>, содержащим дополнительные сведения о производительности.

Если performanceEntry.name равно Http2Stream, detail будет содержать следующие свойства:

• bytesRead <number> Количество байтов кадров DATA, полученных для этого Http2Stream.
• bytesWritten <number> Количество байтов кадров DATA, отправленных для этого Http2Stream.
• id <number> Идентификатор связанного Http2Stream
• timeToFirstByte <number> Количество миллисекунд между PerformanceEntry startTime и получением первого кадра DATA.
• timeToFirstByteSent <number> Количество миллисекунд между PerformanceEntry startTime и отправкой первого кадра DATA.
• timeToFirstHeader <number> Количество миллисекунд между PerformanceEntry startTime и получением первого заголовка.

Если performanceEntry.name равно Http2Session, detail будет содержать следующие свойства:

• bytesRead <number> Количество байтов, полученных для этого Http2Session.
• bytesWritten <number> Количество байтов, отправленных для этого Http2Session.
• framesReceived <number> Количество кадров HTTP/2, полученных Http2Session.
• framesSent <number> Количество кадров HTTP/2, отправленных Http2Session.
• maxConcurrentStreams <number> Максимальное количество потоков, одновременно открытых за время существования Http2Session.
• pingRTT <number> Количество миллисекунд между отправкой кадра PING и получением подтверждения для него. Присутствует только в том случае, если кадр PING был отправлен по Http2Session.
• streamAverageDuration <number> Средняя длительность (в миллисекундах) для всех экземпляров Http2Stream.
• streamCount <number> Количество экземпляров Http2Stream, обработанных Http2Session.
• type <string> Значение 'server' или 'client', указывающее тип Http2Session.

Подробное описание Timerify ('function')

Когда performanceEntry.type равно 'function', свойство performanceNodeEntry.detail будет массивом <Array>, содержащим входные аргументы измеряемой функции.

Подробное описание Net ('net')

Когда performanceEntry.type равно 'net', свойство performanceNodeEntry.detail будет объектом <Object>, содержащим дополнительные сведения.

Если performanceEntry.name равно connect, detail будет содержать следующие свойства: host, port.

Подробное описание DNS ('dns')

Когда performanceEntry.type равно 'dns', свойство performanceNodeEntry.detail будет объектом <Object>, содержащим дополнительные сведения.

Если performanceEntry.name равно lookup, detail будет содержать следующие свойства: hostname, family, hints, verbatim, addresses.

Если performanceEntry.name равно lookupService, detail будет содержать следующие свойства: host, port, hostname, service.

Если performanceEntry.name равно queryxxx или getHostByAddr, detail будет содержать следующие свойства: host, ttl, result. Значение result совпадает с результатом queryxxx или getHostByAddr.

Класс: PerformanceNodeTiming

• Расширяет: <PerformanceEntry>

Это свойство является расширением Node.js. Оно недоступно в веб-браузерах.

Предоставляет сведения о времени для самого Node.js. Конструктор этого класса не доступен пользователям.

performanceNodeTiming.bootstrapComplete

• Тип: <number>

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

performanceNodeTiming.environment

• Тип: <number>

Временная метка с высокой точностью в миллисекундах, соответствующая моменту инициализации среды Node.js.

performanceNodeTiming.idleTime

• Тип: <number>

Временная метка с высокой точностью в миллисекундах, обозначающая время простоя цикла событий в поставщике событий цикла (например, epoll_wait). При этом загрузка ЦП не учитывается. Если цикл событий еще не запущен (например, во время первого такта основного скрипта), значение свойства равно 0.

performanceNodeTiming.loopExit

• Тип: <number>

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

performanceNodeTiming.loopStart

• Тип: <number>

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

performanceNodeTiming.nodeStart

• Тип: <number>

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

performanceNodeTiming.uvMetricsInfo

• Возвращает: <Object>
  • loopCount <number> Количество итераций цикла событий.
  • events <number> Количество событий, обработанных обработчиком событий.
  • eventsWaiting <number> Количество событий, ожидавших обработки при вызове поставщика событий.

Это обертка для функции uv_metrics_info. Она возвращает текущий набор метрик цикла событий.

Рекомендуется использовать это свойство внутри функции, выполнение которой запланировано с помощью setImmediate, чтобы не собирать метрики до завершения всех операций, запланированных во время текущей итерации цикла.

const { performance } = require('node:perf_hooks');

setImmediate(() => {
  console.log(performance.nodeTiming.uvMetricsInfo);
});

import { performance } from 'node:perf_hooks';

setImmediate(() => {
  console.log(performance.nodeTiming.uvMetricsInfo);
});

performanceNodeTiming.v8Start

• Тип: <number>

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

Класс: PerformanceResourceTiming

• Расширяет: <PerformanceEntry>

Предоставляет подробные данные о сетевых временных показателях загрузки ресурсов приложения.

Конструктор этого класса недоступен пользователям напрямую.

performanceResourceTiming.workerStart

• Тип: <number>

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

performanceResourceTiming.redirectStart

• Тип: <number>

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

performanceResourceTiming.redirectEnd

• Тип: <number>

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

performanceResourceTiming.fetchStart

• Тип: <number>

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

performanceResourceTiming.domainLookupStart

• Тип: <number>

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

performanceResourceTiming.domainLookupEnd

• Тип: <number>

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

performanceResourceTiming.connectStart

• Тип: <number>

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

performanceResourceTiming.connectEnd

• Тип: <number>

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

performanceResourceTiming.secureConnectionStart

• Тип: <number>

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

performanceResourceTiming.requestStart

• Тип: <number>

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

performanceResourceTiming.responseEnd

• Тип: <number>

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

performanceResourceTiming.transferSize

• Тип: <number>

Число, обозначающее размер (в октетах) загруженного ресурса. Размер включает поля заголовка ответа и тело полезной нагрузки ответа.

performanceResourceTiming.encodedBodySize

• Тип: <number>

Число, обозначающее размер (в октетах) тела полезной нагрузки, полученного при загрузке (HTTP или из кэша), до удаления примененных кодировок содержимого.

performanceResourceTiming.decodedBodySize

• Тип: <number>

Число, обозначающее размер (в октетах) тела сообщения, полученного при загрузке (HTTP или из кэша), после удаления примененных кодировок содержимого.

performanceResourceTiming.toJSON()

Возвращает object, представляющий объект PerformanceResourceTiming в формате JSON

Класс: PerformanceObserver

PerformanceObserver.supportedEntryTypes

• Тип: <string[]>

Получить поддерживаемые типы.

new PerformanceObserver(callback)

• callback <Function>
  • list <PerformanceObserverEntryList>
  • observer <PerformanceObserver>

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

import { performance, PerformanceObserver } from 'node:perf_hooks';

const obs = new PerformanceObserver((list, observer) => {
  console.log(list.getEntries());

  performance.clearMarks();
  performance.clearMeasures();
  observer.disconnect();
});
obs.observe({ entryTypes: ['mark'], buffered: true });

performance.mark('test');

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

const obs = new PerformanceObserver((list, observer) => {
  console.log(list.getEntries());

  performance.clearMarks();
  performance.clearMeasures();
  observer.disconnect();
});
obs.observe({ entryTypes: ['mark'], buffered: true });

performance.mark('test');

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

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

performanceObserver.disconnect()

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

performanceObserver.observe(options)

• options <Object>
  • type <string> Один тип <PerformanceEntry>. Не должен указываться, если entryTypes уже задан.
  • entryTypes <string[]> Массив строк, идентифицирующих типы экземпляров <PerformanceEntry>, которые интересуют наблюдателя. Если параметр не указан, будет выброшена ошибка.
  • buffered <boolean> Если значение равно true, функция обратного вызова наблюдателя вызывается со списком глобальных буферизованных записей PerformanceEntry. Если значение равно false, в функцию обратного вызова наблюдателя передаются только PerformanceEntry, созданные после этого момента времени. Значение по умолчанию: false.

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

import { performance, PerformanceObserver } from 'node:perf_hooks';

const obs = new PerformanceObserver((list, observer) => {
  // Called once asynchronously. `list` contains three items.
});
obs.observe({ type: 'mark' });

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

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

const obs = new PerformanceObserver((list, observer) => {
  // Called once asynchronously. `list` contains three items.
});
obs.observe({ type: 'mark' });

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

performanceObserver.takeRecords()

• Возвращает: <PerformanceEntry[]> Текущий список записей, хранящихся в наблюдателе производительности; список очищается.

Класс: PerformanceObserverEntryList

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

performanceObserverEntryList.getEntries()

• Возвращает: <PerformanceEntry[]>

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

import { performance, PerformanceObserver } from 'node:perf_hooks';

const obs = new PerformanceObserver((perfObserverList, observer) => {
  console.log(perfObserverList.getEntries());
  /**
   * [
   *   PerformanceEntry {
   *     name: 'test',
   *     entryType: 'mark',
   *     startTime: 81.465639,
   *     duration: 0,
   *     detail: null
   *   },
   *   PerformanceEntry {
   *     name: 'meow',
   *     entryType: 'mark',
   *     startTime: 81.860064,
   *     duration: 0,
   *     detail: null
   *   }
   * ]
   */

  performance.clearMarks();
  performance.clearMeasures();
  observer.disconnect();
});
obs.observe({ type: 'mark' });

performance.mark('test');
performance.mark('meow');

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

const obs = new PerformanceObserver((perfObserverList, observer) => {
  console.log(perfObserverList.getEntries());
  /**
   * [
   *   PerformanceEntry {
   *     name: 'test',
   *     entryType: 'mark',
   *     startTime: 81.465639,
   *     duration: 0,
   *     detail: null
   *   },
   *   PerformanceEntry {
   *     name: 'meow',
   *     entryType: 'mark',
   *     startTime: 81.860064,
   *     duration: 0,
   *     detail: null
   *   }
   * ]
   */

  performance.clearMarks();
  performance.clearMeasures();
  observer.disconnect();
});
obs.observe({ type: 'mark' });

performance.mark('test');
performance.mark('meow');

performanceObserverEntryList.getEntriesByName(name[, type])

• name <string>
• type <string>
• Возвращает: <PerformanceEntry[]>

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

import { performance, PerformanceObserver } from 'node:perf_hooks';

const obs = new PerformanceObserver((perfObserverList, observer) => {
  console.log(perfObserverList.getEntriesByName('meow'));
  /**
   * [
   *   PerformanceEntry {
   *     name: 'meow',
   *     entryType: 'mark',
   *     startTime: 98.545991,
   *     duration: 0,
   *     detail: null
   *   }
   * ]
   */
  console.log(perfObserverList.getEntriesByName('nope')); // []

  console.log(perfObserverList.getEntriesByName('test', 'mark'));
  /**
   * [
   *   PerformanceEntry {
   *     name: 'test',
   *     entryType: 'mark',
   *     startTime: 63.518931,
   *     duration: 0,
   *     detail: null
   *   }
   * ]
   */
  console.log(perfObserverList.getEntriesByName('test', 'measure')); // []

  performance.clearMarks();
  performance.clearMeasures();
  observer.disconnect();
});
obs.observe({ entryTypes: ['mark', 'measure'] });

performance.mark('test');
performance.mark('meow');

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

const obs = new PerformanceObserver((perfObserverList, observer) => {
  console.log(perfObserverList.getEntriesByName('meow'));
  /**
   * [
   *   PerformanceEntry {
   *     name: 'meow',
   *     entryType: 'mark',
   *     startTime: 98.545991,
   *     duration: 0,
   *     detail: null
   *   }
   * ]
   */
  console.log(perfObserverList.getEntriesByName('nope')); // []

  console.log(perfObserverList.getEntriesByName('test', 'mark'));
  /**
   * [
   *   PerformanceEntry {
   *     name: 'test',
   *     entryType: 'mark',
   *     startTime: 63.518931,
   *     duration: 0,
   *     detail: null
   *   }
   * ]
   */
  console.log(perfObserverList.getEntriesByName('test', 'measure')); // []

  performance.clearMarks();
  performance.clearMeasures();
  observer.disconnect();
});
obs.observe({ entryTypes: ['mark', 'measure'] });

performance.mark('test');
performance.mark('meow');

performanceObserverEntryList.getEntriesByType(type)

• type <string>
• Возвращает: <PerformanceEntry[]>

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

import { performance, PerformanceObserver } from 'node:perf_hooks';

const obs = new PerformanceObserver((perfObserverList, observer) => {
  console.log(perfObserverList.getEntriesByType('mark'));
  /**
   * [
   *   PerformanceEntry {
   *     name: 'test',
   *     entryType: 'mark',
   *     startTime: 55.897834,
   *     duration: 0,
   *     detail: null
   *   },
   *   PerformanceEntry {
   *     name: 'meow',
   *     entryType: 'mark',
   *     startTime: 56.350146,
   *     duration: 0,
   *     detail: null
   *   }
   * ]
   */
  performance.clearMarks();
  performance.clearMeasures();
  observer.disconnect();
});
obs.observe({ type: 'mark' });

performance.mark('test');
performance.mark('meow');

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

const obs = new PerformanceObserver((perfObserverList, observer) => {
  console.log(perfObserverList.getEntriesByType('mark'));
  /**
   * [
   *   PerformanceEntry {
   *     name: 'test',
   *     entryType: 'mark',
   *     startTime: 55.897834,
   *     duration: 0,
   *     detail: null
   *   },
   *   PerformanceEntry {
   *     name: 'meow',
   *     entryType: 'mark',
   *     startTime: 56.350146,
   *     duration: 0,
   *     detail: null
   *   }
   * ]
   */
  performance.clearMarks();
  performance.clearMeasures();
  observer.disconnect();
});
obs.observe({ type: 'mark' });

performance.mark('test');
performance.mark('meow');

perf_hooks.createHistogram([options])

• options <Object>
  • lowest <number> | <bigint> Наименьшее различимое значение. Должно быть целым числом больше 0. Значение по умолчанию: 1.
  • highest <number> | <bigint> Наибольшее записываемое значение. Должно быть целым числом, равным lowest или превышающим его как минимум в два раза. Значение по умолчанию: Number.MAX_SAFE_INTEGER.
  • figures <number> Количество цифр точности. Должно быть числом от 1 до 5. Значение по умолчанию: 3.
• Возвращает: <RecordableHistogram>

Возвращает объект <RecordableHistogram>.

perf_hooks.eventLoopUtilization([utilization1[, utilization2]])

• utilization1 <Object> Результат предыдущего вызова eventLoopUtilization().
• utilization2 <Object> Результат предыдущего вызова eventLoopUtilization(), выполненного до utilization1.
• Возвращает: <Object>
  • idle <number>
  • active <number>
  • utilization <number>

Функция eventLoopUtilization() возвращает объект, содержащий суммарную длительность времени, в течение которого цикл событий находился в состоянии ожидания и активности, в виде таймера с высокой точностью и миллисекундным разрешением. Значение utilization — это вычисленная утилизация цикла событий (ELU).

Если инициализация в основном потоке ещё не завершена, свойства имеют значение 0. В потоках Worker ELU доступна сразу, поскольку инициализация происходит внутри цикла событий.

Параметры utilization1 и utilization2 необязательны.

Если передан utilization1, вычисляются и возвращаются разница между значениями времени active и idle текущего вызова, а также соответствующее значение utilization (аналогично process.hrtime()).

Если переданы оба параметра — utilization1 и utilization2, разница вычисляется между двумя аргументами. Это упрощает работу, поскольку вычисление ELU, в отличие от process.hrtime(), сложнее, чем простое вычитание.

ELU похожа на загрузку ЦП, но измеряет только статистику цикла событий, а не использование ЦП. Она показывает процент времени, проведённого циклом событий вне поставщика событий цикла событий (например, epoll_wait). Другое время простоя ЦП не учитывается. Ниже приведён пример того, как у практически бездействующего процесса может быть высокое значение ELU.

import { eventLoopUtilization } from 'node:perf_hooks';
import { spawnSync } from 'node:child_process';

setImmediate(() => {
  const elu = eventLoopUtilization();
  spawnSync('sleep', ['5']);
  console.log(eventLoopUtilization(elu).utilization);
});

const { eventLoopUtilization } = require('node:perf_hooks');
const { spawnSync } = require('node:child_process');

setImmediate(() => {
  const elu = eventLoopUtilization();
  spawnSync('sleep', ['5']);
  console.log(eventLoopUtilization(elu).utilization);
});

Хотя во время выполнения этого скрипта ЦП практически бездействует, значение utilization равно 1. Это происходит потому, что вызов child_process.spawnSync() блокирует дальнейшую работу цикла событий.

Передача пользовательского объекта вместо результата предыдущего вызова eventLoopUtilization() приводит к неопределённому поведению. Нет гарантии, что возвращаемые значения будут отражать какое-либо корректное состояние цикла событий.

perf_hooks.monitorEventLoopDelay([options])

• options <Object>
  • resolution <number> Частота выборки в миллисекундах. Должна быть больше нуля. Значение по умолчанию: 10.
• Возвращает: <IntervalHistogram>

Это свойство является расширением Node.js. Оно недоступно в веб-браузерах.

Создаёт объект IntervalHistogram, который отслеживает и сообщает о задержке цикла событий с течением времени. Задержки сообщаются в наносекундах.

Использование таймера для обнаружения приблизительной задержки цикла событий работает, поскольку выполнение таймеров напрямую связано с жизненным циклом цикла событий libuv. То есть задержка в цикле приводит к задержке выполнения таймера, и именно такие задержки предназначен обнаруживать этот API.

import { monitorEventLoopDelay } from 'node:perf_hooks';

const h = monitorEventLoopDelay({ resolution: 20 });
h.enable();
// Do something.
h.disable();
console.log(h.min);
console.log(h.max);
console.log(h.mean);
console.log(h.stddev);
console.log(h.percentiles);
console.log(h.percentile(50));
console.log(h.percentile(99));

const { monitorEventLoopDelay } = require('node:perf_hooks');
const h = monitorEventLoopDelay({ resolution: 20 });
h.enable();
// Do something.
h.disable();
console.log(h.min);
console.log(h.max);
console.log(h.mean);
console.log(h.stddev);
console.log(h.percentiles);
console.log(h.percentile(50));
console.log(h.percentile(99));

perf_hooks.timerify(fn[, options])

• fn <Function>
• options <Object>
  • histogram <RecordableHistogram> Объект гистограммы, созданный с помощью perf_hooks.createHistogram(), который будет записывать длительность выполнения в наносекундах.

Это свойство является расширением Node.js. Оно недоступно в веб-браузерах.

Оборачивает функцию в новую функцию, измеряющую время выполнения обёрнутой функции. Для доступа к данным о времени необходимо подписать объект PerformanceObserver на тип события 'function'.

import { timerify, performance, PerformanceObserver } from 'node:perf_hooks';

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

const wrapped = timerify(someFunction);

const obs = new PerformanceObserver((list) => {
  console.log(list.getEntries()[0].duration);

  performance.clearMarks();
  performance.clearMeasures();
  obs.disconnect();
});
obs.observe({ entryTypes: ['function'] });

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

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

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

const wrapped = timerify(someFunction);

const obs = new PerformanceObserver((list) => {
  console.log(list.getEntries()[0].duration);

  performance.clearMarks();
  performance.clearMeasures();
  obs.disconnect();
});
obs.observe({ entryTypes: ['function'] });

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

Если обёрнутая функция возвращает промис, к нему будет добавлен обработчик finally, а длительность будет передана после вызова этого обработчика.

Класс: Histogram

histogram.count

• Тип: <number>

Количество выборок, записанных гистограммой.

histogram.countBigInt

• Тип: <bigint>

Количество выборок, записанных гистограммой.

histogram.exceeds

• Тип: <number>

Количество случаев, когда задержка цикла событий превысила максимальный порог задержки цикла событий в 1 час.

histogram.exceedsBigInt

• Тип: <bigint>

Количество случаев, когда задержка цикла событий превысила максимальный порог задержки цикла событий в 1 час.

histogram.max

• Тип: <number>

Максимальная зарегистрированная задержка цикла событий.

histogram.maxBigInt

• Тип: <bigint>

Максимальная зарегистрированная задержка цикла событий.

histogram.mean

• Тип: <number>

Среднее значение зарегистрированных задержек цикла событий.

histogram.min

• Тип: <number>

Минимальная зарегистрированная задержка цикла событий.

histogram.minBigInt

• Тип: <bigint>

Минимальная зарегистрированная задержка цикла событий.

histogram.percentile(percentile)

• percentile <number> Значение процентиля в диапазоне (0, 100].
• Возвращает: <number>

Возвращает значение для заданного процентиля.

histogram.percentileBigInt(percentile)

• percentile <number> Значение процентиля в диапазоне (0, 100].
• Возвращает: <bigint>

Возвращает значение для заданного процентиля.

histogram.percentiles

• Тип: <Map>

Возвращает объект Map с данными о накопленном распределении процентилей.

histogram.percentilesBigInt

• Тип: <Map>

Возвращает объект Map с данными о накопленном распределении процентилей.

histogram.reset()

Сбрасывает собранные данные гистограммы.

histogram.stddev

• Тип: <number>

Стандартное отклонение зарегистрированных задержек цикла событий.

Класс: IntervalHistogram extends Histogram

Объект Histogram, который периодически обновляется с заданным интервалом.

histogram.disable()

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

Отключает таймер интервала обновления. Возвращает true, если таймер был остановлен, и false, если он уже был остановлен.

histogram.enable()

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

Включает таймер интервала обновления. Возвращает true, если таймер был запущен, и false, если он уже был запущен.

histogram[Symbol.dispose]()

Отключает таймер интервала обновления при удалении гистограммы.

const { monitorEventLoopDelay } = require('node:perf_hooks');
{
  using hist = monitorEventLoopDelay({ resolution: 20 });
  hist.enable();
  // The histogram will be disabled when the block is exited.
}
jscopy

Клонирование IntervalHistogram

Экземпляры <IntervalHistogram> можно клонировать с помощью <MessagePort>. На принимающей стороне гистограмма клонируется как обычный объект <Histogram>, не реализующий методы enable() и disable().

Класс: RecordableHistogram extends Histogram

histogram.add(other)

• other <RecordableHistogram>

Добавляет значения из other в эту гистограмму.

histogram.record(val)

• val <number> | <bigint> Величина, записываемая в гистограмму.

histogram.recordDelta()

Вычисляет время (в наносекундах), прошедшее с предыдущего вызова recordDelta(), и записывает это значение в гистограмму.

Примеры

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

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

import { createHook } from 'node:async_hooks';
import { performance, PerformanceObserver } from 'node:perf_hooks';

const set = new Set();
const hook = 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);

const async_hooks = require('node:async_hooks');
const {
  performance,
  PerformanceObserver,
} = require('node: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'] });

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

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

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

import { performance, PerformanceObserver } from 'node:perf_hooks';

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

const timedImport = performance.timerify(async (module) => {
  return await import(module);
});

await timedImport('some-module');

const {
  performance,
  PerformanceObserver,
} = require('node:perf_hooks');
const mod = require('node: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);
  });
  performance.clearMarks();
  performance.clearMeasures();
  obs.disconnect();
});
obs.observe({ entryTypes: ['function'] });

require('some-module');

Измерение времени одного обмена данными по HTTP

Следующий пример используется для отслеживания времени, затраченного HTTP-клиентом (OutgoingMessage) и HTTP-запросом (IncomingMessage). Для HTTP-клиента это интервал времени между началом запроса и получением ответа, а для HTTP-запроса — интервал между получением запроса и отправкой ответа:

import { PerformanceObserver } from 'node:perf_hooks';
import { createServer, get } from 'node:http';

const obs = new PerformanceObserver((items) => {
  items.getEntries().forEach((item) => {
    console.log(item);
  });
});

obs.observe({ entryTypes: ['http'] });

const PORT = 8080;

createServer((req, res) => {
  res.end('ok');
}).listen(PORT, () => {
  get(`http://127.0.0.1:${PORT}`);
});

const { PerformanceObserver } = require('node:perf_hooks');
const http = require('node:http');

const obs = new PerformanceObserver((items) => {
  items.getEntries().forEach((item) => {
    console.log(item);
  });
});

obs.observe({ entryTypes: ['http'] });

const PORT = 8080;

http.createServer((req, res) => {
  res.end('ok');
}).listen(PORT, () => {
  http.get(`http://127.0.0.1:${PORT}`);
});

Измерение времени выполнения net.connect (только для TCP) при успешном подключении

import { PerformanceObserver } from 'node:perf_hooks';
import { connect, createServer } from 'node:net';

const obs = new PerformanceObserver((items) => {
  items.getEntries().forEach((item) => {
    console.log(item);
  });
});
obs.observe({ entryTypes: ['net'] });
const PORT = 8080;
createServer((socket) => {
  socket.destroy();
}).listen(PORT, () => {
  connect(PORT);
});

const { PerformanceObserver } = require('node:perf_hooks');
const net = require('node:net');
const obs = new PerformanceObserver((items) => {
  items.getEntries().forEach((item) => {
    console.log(item);
  });
});
obs.observe({ entryTypes: ['net'] });
const PORT = 8080;
net.createServer((socket) => {
  socket.destroy();
}).listen(PORT, () => {
  net.connect(PORT);
});

Измерение времени выполнения DNS при успешном запросе

import { PerformanceObserver } from 'node:perf_hooks';
import { lookup, promises } from 'node:dns';

const obs = new PerformanceObserver((items) => {
  items.getEntries().forEach((item) => {
    console.log(item);
  });
});
obs.observe({ entryTypes: ['dns'] });
lookup('localhost', () => {});
promises.resolve('localhost');

const { PerformanceObserver } = require('node:perf_hooks');
const dns = require('node:dns');
const obs = new PerformanceObserver((items) => {
  items.getEntries().forEach((item) => {
    console.log(item);
  });
});
obs.observe({ entryTypes: ['dns'] });
dns.lookup('localhost', () => {});
dns.promises.resolve('localhost');