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>

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

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

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

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

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

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

'use strict';
const { eventLoopUtilization } = require('node:perf_hooks').performance;
const { spawnSync } = require('node:child_process');

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

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

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

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)

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

Это свойство является расширением 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(), который записывает длительность выполнения в наносекундах.

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

Создает новую функцию-обертку, которая измеряет время выполнения оборачиваемой функции. Чтобы получить доступ к сведениям о времени, необходимо подписать PerformanceObserver на тип события 'function'.

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

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

const wrapped = performance.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(); copy

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

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>

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

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 на временную шкалу производительности.

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'); copy

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

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

performanceObserver.disconnect()

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

performanceObserver.observe(options)

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

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

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

performanceObserver.takeRecords()

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

Класс: PerformanceObserverEntryList

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

performanceObserverEntryList.getEntries()

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

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

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'); copy

performanceObserverEntryList.getEntriesByName(name[, type])

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

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

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'); copy

performanceObserverEntryList.getEntriesByType(type)

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

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

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'); copy

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.monitorEventLoopDelay([options])

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

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

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

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

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)); copy

Класс: 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, если он уже был запущен.

Клонирование 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 (включая время выполнения callback).

'use strict';
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); copy

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

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

'use strict';
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'); copy

Измерение времени одного цикла HTTP-запроса и ответа

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

'use strict';
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}`);
}); copy

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

'use strict';
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);
}); copy

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

'use strict';
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'); copy