- Assertion testing
- Asynchronous context tracking
- Async hooks
- Buffer
- C++ addons
- C/C++ addons with Node-API
- C++ embedder API
- Child processes
- Cluster
- Command-line options
- Console
- Corepack
- Crypto
- Debugger
- Deprecated APIs
- Diagnostics Channel
- DNS
- Domain
- Errors
- Events
- File system
- Globals
- HTTP
- HTTP/2
- HTTPS
- Inspector
- Internationalization
- Modules: CommonJS modules
- Modules: ECMAScript modules
- Modules:
node:module
API - Modules: Packages
- Net
- OS
- Path
- Performance hooks
- Permissions
- Process
- Punycode
- Query strings
- Readline
- REPL
- Report
- Single executable applications
- Stream
- String decoder
- Test runner
- Timers
- TLS/SSL
- Trace events
- TTY
- UDP/datagram
- URL
- Utilities
- V8
- VM
- WASI
- Web Crypto API
- Web Streams API
- Worker threads
- Zlib
Node.js v21.0.0-nightly202304192e0152ccf1 documentation
- Node.js v21.0.0-nightly202304192e0152ccf1
-
►
Table of contents
- Performance measurement APIs
perf_hooks.performance
performance.clearMarks([name])
performance.clearMeasures([name])
performance.clearResourceTimings([name])
performance.eventLoopUtilization([utilization1[, utilization2]])
performance.getEntries()
performance.getEntriesByName(name[, type])
performance.getEntriesByType(type)
performance.mark(name[, options])
performance.markResourceTiming(timingInfo, requestedUrl, initiatorType, global, cacheMode)
performance.measure(name[, startMarkOrOptions[, endMark]])
performance.nodeTiming
performance.now()
performance.setResourceTimingBufferSize(maxSize)
performance.timeOrigin
performance.timerify(fn[, options])
performance.toJSON()
- Class:
PerformanceEntry
- Class:
PerformanceMark
- Class:
PerformanceMeasure
- Class:
PerformanceNodeEntry
- Class:
PerformanceNodeTiming
- Class:
PerformanceResourceTiming
performanceResourceTiming.workerStart
performanceResourceTiming.redirectStart
performanceResourceTiming.redirectEnd
performanceResourceTiming.fetchStart
performanceResourceTiming.domainLookupStart
performanceResourceTiming.domainLookupEnd
performanceResourceTiming.connectStart
performanceResourceTiming.connectEnd
performanceResourceTiming.secureConnectionStart
performanceResourceTiming.requestStart
performanceResourceTiming.responseEnd
performanceResourceTiming.transferSize
performanceResourceTiming.encodedBodySize
performanceResourceTiming.decodedBodySize
performanceResourceTiming.toJSON()
- Class:
PerformanceObserver
- Class:
PerformanceObserverEntryList
perf_hooks.createHistogram([options])
perf_hooks.monitorEventLoopDelay([options])
- Class:
Histogram
histogram.count
histogram.countBigInt
histogram.exceeds
histogram.exceedsBigInt
histogram.max
histogram.maxBigInt
histogram.mean
histogram.min
histogram.minBigInt
histogram.percentile(percentile)
histogram.percentileBigInt(percentile)
histogram.percentiles
histogram.percentilesBigInt
histogram.reset()
histogram.stddev
- Class:
IntervalHistogram extends Histogram
- Class:
RecordableHistogram extends Histogram
- Examples
- Performance measurement APIs
-
►
Index
- Assertion testing
- Asynchronous context tracking
- Async hooks
- Buffer
- C++ addons
- C/C++ addons with Node-API
- C++ embedder API
- Child processes
- Cluster
- Command-line options
- Console
- Corepack
- Crypto
- Debugger
- Deprecated APIs
- Diagnostics Channel
- DNS
- Domain
- Errors
- Events
- File system
- Globals
- HTTP
- HTTP/2
- HTTPS
- Inspector
- Internationalization
- Modules: CommonJS modules
- Modules: ECMAScript modules
- Modules:
node:module
API - Modules: Packages
- Net
- OS
- Path
- Performance hooks
- Permissions
- Process
- Punycode
- Query strings
- Readline
- REPL
- Report
- Single executable applications
- Stream
- String decoder
- Test runner
- Timers
- TLS/SSL
- Trace events
- TTY
- UDP/datagram
- URL
- Utilities
- V8
- VM
- WASI
- Web Crypto API
- Web Streams API
- Worker threads
- Zlib
- ► Other versions
- ► Options
Table of contents
- Performance measurement APIs
perf_hooks.performance
performance.clearMarks([name])
performance.clearMeasures([name])
performance.clearResourceTimings([name])
performance.eventLoopUtilization([utilization1[, utilization2]])
performance.getEntries()
performance.getEntriesByName(name[, type])
performance.getEntriesByType(type)
performance.mark(name[, options])
performance.markResourceTiming(timingInfo, requestedUrl, initiatorType, global, cacheMode)
performance.measure(name[, startMarkOrOptions[, endMark]])
performance.nodeTiming
performance.now()
performance.setResourceTimingBufferSize(maxSize)
performance.timeOrigin
performance.timerify(fn[, options])
performance.toJSON()
- Class:
PerformanceEntry
- Class:
PerformanceMark
- Class:
PerformanceMeasure
- Class:
PerformanceNodeEntry
- Class:
PerformanceNodeTiming
- Class:
PerformanceResourceTiming
performanceResourceTiming.workerStart
performanceResourceTiming.redirectStart
performanceResourceTiming.redirectEnd
performanceResourceTiming.fetchStart
performanceResourceTiming.domainLookupStart
performanceResourceTiming.domainLookupEnd
performanceResourceTiming.connectStart
performanceResourceTiming.connectEnd
performanceResourceTiming.secureConnectionStart
performanceResourceTiming.requestStart
performanceResourceTiming.responseEnd
performanceResourceTiming.transferSize
performanceResourceTiming.encodedBodySize
performanceResourceTiming.decodedBodySize
performanceResourceTiming.toJSON()
- Class:
PerformanceObserver
- Class:
PerformanceObserverEntryList
perf_hooks.createHistogram([options])
perf_hooks.monitorEventLoopDelay([options])
- Class:
Histogram
histogram.count
histogram.countBigInt
histogram.exceeds
histogram.exceedsBigInt
histogram.max
histogram.maxBigInt
histogram.mean
histogram.min
histogram.minBigInt
histogram.percentile(percentile)
histogram.percentileBigInt(percentile)
histogram.percentiles
histogram.percentilesBigInt
histogram.reset()
histogram.stddev
- Class:
IntervalHistogram extends Histogram
- Class:
RecordableHistogram extends Histogram
- Examples
Performance measurement APIs#
Source Code: lib/perf_hooks.js
This module provides an implementation of a subset of the W3C Web Performance APIs as well as additional APIs for Node.js-specific performance measurements.
Node.js supports the following Web Performance APIs:
const { PerformanceObserver, performance } = require('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');
});
perf_hooks.performance
#
An object that can be used to collect performance metrics from the current
Node.js instance. It is similar to window.performance
in browsers.
performance.clearMarks([name])
#
name
<string>
If name
is not provided, removes all PerformanceMark
objects from the
Performance Timeline. If name
is provided, removes only the named mark.
performance.clearMeasures([name])
#
name
<string>
If name
is not provided, removes all PerformanceMeasure
objects from the
Performance Timeline. If name
is provided, removes only the named measure.
performance.clearResourceTimings([name])
#
name
<string>
If name
is not provided, removes all PerformanceResourceTiming
objects from
the Resource Timeline. If name
is provided, removes only the named resource.
performance.eventLoopUtilization([utilization1[, utilization2]])
#
utilization1
<Object> The result of a previous call toeventLoopUtilization()
.utilization2
<Object> The result of a previous call toeventLoopUtilization()
prior toutilization1
.- Returns <Object>
The eventLoopUtilization()
method returns an object that contains the
cumulative duration of time the event loop has been both idle and active as a
high resolution milliseconds timer. The utilization
value is the calculated
Event Loop Utilization (ELU).
If bootstrapping has not yet finished on the main thread the properties have
the value of 0
. The ELU is immediately available on Worker threads since
bootstrap happens within the event loop.
Both utilization1
and utilization2
are optional parameters.
If utilization1
is passed, then the delta between the current call's active
and idle
times, as well as the corresponding utilization
value are
calculated and returned (similar to process.hrtime()
).
If utilization1
and utilization2
are both passed, then the delta is
calculated between the two arguments. This is a convenience option because,
unlike process.hrtime()
, calculating the ELU is more complex than a
single subtraction.
ELU is similar to CPU utilization, except that it only measures event loop
statistics and not CPU usage. It represents the percentage of time the event
loop has spent outside the event loop's event provider (e.g. epoll_wait
).
No other CPU idle time is taken into consideration. The following is an example
of how a mostly idle process will have a high 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);
});
Although the CPU is mostly idle while running this script, the value of
utilization
is 1
. This is because the call to
child_process.spawnSync()
blocks the event loop from proceeding.
Passing in a user-defined object instead of the result of a previous call to
eventLoopUtilization()
will lead to undefined behavior. The return values
are not guaranteed to reflect any correct state of the event loop.
performance.getEntries()
#
- Returns: <PerformanceEntry[]>
Returns a list of PerformanceEntry
objects in chronological order with
respect to performanceEntry.startTime
. If you are only interested in
performance entries of certain types or that have certain names, see
performance.getEntriesByType()
and performance.getEntriesByName()
.
performance.getEntriesByName(name[, type])
#
name
<string>type
<string>- Returns: <PerformanceEntry[]>
Returns a list of PerformanceEntry
objects in chronological order
with respect to performanceEntry.startTime
whose performanceEntry.name
is
equal to name
, and optionally, whose performanceEntry.entryType
is equal to
type
.
performance.getEntriesByType(type)
#
type
<string>- Returns: <PerformanceEntry[]>
Returns a list of PerformanceEntry
objects in chronological order
with respect to performanceEntry.startTime
whose performanceEntry.entryType
is equal to type
.
performance.mark(name[, options])
#
Creates a new PerformanceMark
entry in the Performance Timeline. A
PerformanceMark
is a subclass of PerformanceEntry
whose
performanceEntry.entryType
is always 'mark'
, and whose
performanceEntry.duration
is always 0
. Performance marks are used
to mark specific significant moments in the Performance Timeline.
The created PerformanceMark
entry is put in the global Performance Timeline
and can be queried with performance.getEntries
,
performance.getEntriesByName
, and performance.getEntriesByType
. When the
observation is performed, the entries should be cleared from the global
Performance Timeline manually with performance.clearMarks
.
performance.markResourceTiming(timingInfo, requestedUrl, initiatorType, global, cacheMode)
#
timingInfo
<Object> Fetch Timing InforequestedUrl
<string> The resource urlinitiatorType
<string> The initiator name, e.g: 'fetch'global
<Object>cacheMode
<string> The cache mode must be an empty string ('') or 'local'
This property is an extension by Node.js. It is not available in Web browsers.
Creates a new PerformanceResourceTiming
entry in the Resource Timeline. A
PerformanceResourceTiming
is a subclass of PerformanceEntry
whose
performanceEntry.entryType
is always 'resource'
. Performance resources
are used to mark moments in the Resource Timeline.
The created PerformanceMark
entry is put in the global Resource Timeline
and can be queried with performance.getEntries
,
performance.getEntriesByName
, and performance.getEntriesByType
. When the
observation is performed, the entries should be cleared from the global
Performance Timeline manually with performance.clearResourceTimings
.
performance.measure(name[, startMarkOrOptions[, endMark]])
#
name
<string>startMarkOrOptions
<string> | <Object> Optional.detail
<any> Additional optional detail to include with the measure.duration
<number> Duration between start and end times.end
<number> | <string> Timestamp to be used as the end time, or a string identifying a previously recorded mark.start
<number> | <string> Timestamp to be used as the start time, or a string identifying a previously recorded mark.
endMark
<string> Optional. Must be omitted ifstartMarkOrOptions
is an <Object>.
Creates a new PerformanceMeasure
entry in the Performance Timeline. A
PerformanceMeasure
is a subclass of PerformanceEntry
whose
performanceEntry.entryType
is always 'measure'
, and whose
performanceEntry.duration
measures the number of milliseconds elapsed since
startMark
and endMark
.
The startMark
argument may identify any existing PerformanceMark
in the
Performance Timeline, or may identify any of the timestamp properties
provided by the PerformanceNodeTiming
class. If the named startMark
does
not exist, an error is thrown.
The optional endMark
argument must identify any existing PerformanceMark
in the Performance Timeline or any of the timestamp properties provided by the
PerformanceNodeTiming
class. endMark
will be performance.now()
if no parameter is passed, otherwise if the named endMark
does not exist, an
error will be thrown.
The created PerformanceMeasure
entry is put in the global Performance Timeline
and can be queried with performance.getEntries
,
performance.getEntriesByName
, and performance.getEntriesByType
. When the
observation is performed, the entries should be cleared from the global
Performance Timeline manually with performance.clearMeasures
.
performance.nodeTiming
#
This property is an extension by Node.js. It is not available in Web browsers.
An instance of the PerformanceNodeTiming
class that provides performance
metrics for specific Node.js operational milestones.
performance.now()
#
- Returns: <number>
Returns the current high resolution millisecond timestamp, where 0 represents
the start of the current node
process.
performance.setResourceTimingBufferSize(maxSize)
#
Sets the global performance resource timing buffer size to the specified number of "resource" type performance entry objects.
By default the max buffer size is set to 250.
performance.timeOrigin
#
The timeOrigin
specifies the high resolution millisecond timestamp at
which the current node
process began, measured in Unix time.
performance.timerify(fn[, options])
#
fn
<Function>options
<Object>histogram
<RecordableHistogram> A histogram object created usingperf_hooks.createHistogram()
that will record runtime durations in nanoseconds.
This property is an extension by Node.js. It is not available in Web browsers.
Wraps a function within a new function that measures the running time of the
wrapped function. A PerformanceObserver
must be subscribed to the 'function'
event type in order for the timing details to be accessed.
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();
If the wrapped function returns a promise, a finally handler will be attached to the promise and the duration will be reported once the finally handler is invoked.
performance.toJSON()
#
An object which is JSON representation of the performance
object. It
is similar to window.performance.toJSON
in browsers.
Event: 'resourcetimingbufferfull'
#
The 'resourcetimingbufferfull'
event is fired when the global performance
resource timing buffer is full. Adjust resource timing buffer size with
performance.setResourceTimingBufferSize()
or clear the buffer with
performance.clearResourceTimings()
in the event listener to allow
more entries to be added to the performance timeline buffer.
Class: PerformanceEntry
#
The constructor of this class is not exposed to users directly.
performanceEntry.duration
#
The total number of milliseconds elapsed for this entry. This value will not be meaningful for all Performance Entry types.
performanceEntry.entryType
#
The type of the performance entry. It may be one of:
'node'
(Node.js only)'mark'
(available on the Web)'measure'
(available on the Web)'gc'
(Node.js only)'function'
(Node.js only)'http2'
(Node.js only)'http'
(Node.js only)
performanceEntry.name
#
The name of the performance entry.
performanceEntry.startTime
#
The high resolution millisecond timestamp marking the starting time of the Performance Entry.
Class: PerformanceMark
#
- Extends: <PerformanceEntry>
Exposes marks created via the Performance.mark()
method.
performanceMark.detail
#
Additional detail specified when creating with Performance.mark()
method.
Class: PerformanceMeasure
#
- Extends: <PerformanceEntry>
Exposes measures created via the Performance.measure()
method.
The constructor of this class is not exposed to users directly.
performanceMeasure.detail
#
Additional detail specified when creating with Performance.measure()
method.
Class: PerformanceNodeEntry
#
- Extends: <PerformanceEntry>
This class is an extension by Node.js. It is not available in Web browsers.
Provides detailed Node.js timing data.
The constructor of this class is not exposed to users directly.
performanceNodeEntry.detail
#
Additional detail specific to the entryType
.
performanceNodeEntry.flags
#
performanceNodeEntry.detail
instead.When performanceEntry.entryType
is equal to 'gc'
, the performance.flags
property contains additional information about garbage collection operation.
The value may be one of:
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
#
performanceNodeEntry.detail
instead.When performanceEntry.entryType
is equal to 'gc'
, the performance.kind
property identifies the type of garbage collection operation that occurred.
The value may be one of:
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
Garbage Collection ('gc') Details#
When performanceEntry.type
is equal to 'gc'
, the
performanceNodeEntry.detail
property will be an <Object> with two properties:
kind
<number> One of: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> One of: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') Details#
When performanceEntry.type
is equal to 'http'
, the
performanceNodeEntry.detail
property will be an <Object> containing
additional information.
If performanceEntry.name
is equal to HttpClient
, the detail
will contain the following properties: req
, res
. And the req
property
will be an <Object> containing method
, url
, headers
, the res
property
will be an <Object> containing statusCode
, statusMessage
, headers
.
If performanceEntry.name
is equal to HttpRequest
, the detail
will contain the following properties: req
, res
. And the req
property
will be an <Object> containing method
, url
, headers
, the res
property
will be an <Object> containing statusCode
, statusMessage
, headers
.
This could add additional memory overhead and should only be used for diagnostic purposes, not left turned on in production by default.
HTTP/2 ('http2') Details#
When performanceEntry.type
is equal to 'http2'
, the
performanceNodeEntry.detail
property will be an <Object> containing
additional performance information.
If performanceEntry.name
is equal to Http2Stream
, the detail
will contain the following properties:
bytesRead
<number> The number ofDATA
frame bytes received for thisHttp2Stream
.bytesWritten
<number> The number ofDATA
frame bytes sent for thisHttp2Stream
.id
<number> The identifier of the associatedHttp2Stream
timeToFirstByte
<number> The number of milliseconds elapsed between thePerformanceEntry
startTime
and the reception of the firstDATA
frame.timeToFirstByteSent
<number> The number of milliseconds elapsed between thePerformanceEntry
startTime
and sending of the firstDATA
frame.timeToFirstHeader
<number> The number of milliseconds elapsed between thePerformanceEntry
startTime
and the reception of the first header.
If performanceEntry.name
is equal to Http2Session
, the detail
will
contain the following properties:
bytesRead
<number> The number of bytes received for thisHttp2Session
.bytesWritten
<number> The number of bytes sent for thisHttp2Session
.framesReceived
<number> The number of HTTP/2 frames received by theHttp2Session
.framesSent
<number> The number of HTTP/2 frames sent by theHttp2Session
.maxConcurrentStreams
<number> The maximum number of streams concurrently open during the lifetime of theHttp2Session
.pingRTT
<number> The number of milliseconds elapsed since the transmission of aPING
frame and the reception of its acknowledgment. Only present if aPING
frame has been sent on theHttp2Session
.streamAverageDuration
<number> The average duration (in milliseconds) for allHttp2Stream
instances.streamCount
<number> The number ofHttp2Stream
instances processed by theHttp2Session
.type
<string> Either'server'
or'client'
to identify the type ofHttp2Session
.
Timerify ('function') Details#
When performanceEntry.type
is equal to 'function'
, the
performanceNodeEntry.detail
property will be an <Array> listing
the input arguments to the timed function.
Net ('net') Details#
When performanceEntry.type
is equal to 'net'
, the
performanceNodeEntry.detail
property will be an <Object> containing
additional information.
If performanceEntry.name
is equal to connect
, the detail
will contain the following properties: host
, port
.
DNS ('dns') Details#
When performanceEntry.type
is equal to 'dns'
, the
performanceNodeEntry.detail
property will be an <Object> containing
additional information.
If performanceEntry.name
is equal to lookup
, the detail
will contain the following properties: hostname
, family
, hints
, verbatim
,
addresses
.
If performanceEntry.name
is equal to lookupService
, the detail
will
contain the following properties: host
, port
, hostname
, service
.
If performanceEntry.name
is equal to queryxxx
or getHostByAddr
, the detail
will
contain the following properties: host
, ttl
, result
. The value of result
is
same as the result of queryxxx
or getHostByAddr
.
Class: PerformanceNodeTiming
#
- Extends: <PerformanceEntry>
This property is an extension by Node.js. It is not available in Web browsers.
Provides timing details for Node.js itself. The constructor of this class is not exposed to users.
performanceNodeTiming.bootstrapComplete
#
The high resolution millisecond timestamp at which the Node.js process completed bootstrapping. If bootstrapping has not yet finished, the property has the value of -1.
performanceNodeTiming.environment
#
The high resolution millisecond timestamp at which the Node.js environment was initialized.
performanceNodeTiming.idleTime
#
The high resolution millisecond timestamp of the amount of time the event loop
has been idle within the event loop's event provider (e.g. epoll_wait
). This
does not take CPU usage into consideration. If the event loop has not yet
started (e.g., in the first tick of the main script), the property has the
value of 0.
performanceNodeTiming.loopExit
#
The high resolution millisecond timestamp at which the Node.js event loop
exited. If the event loop has not yet exited, the property has the value of -1.
It can only have a value of not -1 in a handler of the 'exit'
event.
performanceNodeTiming.loopStart
#
The high resolution millisecond timestamp at which the Node.js event loop started. If the event loop has not yet started (e.g., in the first tick of the main script), the property has the value of -1.
performanceNodeTiming.nodeStart
#
The high resolution millisecond timestamp at which the Node.js process was initialized.
performanceNodeTiming.v8Start
#
The high resolution millisecond timestamp at which the V8 platform was initialized.
Class: PerformanceResourceTiming
#
- Extends: <PerformanceEntry>
Provides detailed network timing data regarding the loading of an application's resources.
The constructor of this class is not exposed to users directly.
performanceResourceTiming.workerStart
#
The high resolution millisecond timestamp at immediately before dispatching
the fetch
request. If the resource is not intercepted by a worker the property
will always return 0.
performanceResourceTiming.redirectStart
#
The high resolution millisecond timestamp that represents the start time of the fetch which initiates the redirect.
performanceResourceTiming.redirectEnd
#
The high resolution millisecond timestamp that will be created immediately after receiving the last byte of the response of the last redirect.
performanceResourceTiming.fetchStart
#
The high resolution millisecond timestamp immediately before the Node.js starts to fetch the resource.
performanceResourceTiming.domainLookupStart
#
The high resolution millisecond timestamp immediately before the Node.js starts the domain name lookup for the resource.
performanceResourceTiming.domainLookupEnd
#
The high resolution millisecond timestamp representing the time immediately after the Node.js finished the domain name lookup for the resource.
performanceResourceTiming.connectStart
#
The high resolution millisecond timestamp representing the time immediately before Node.js starts to establish the connection to the server to retrieve the resource.
performanceResourceTiming.connectEnd
#
The high resolution millisecond timestamp representing the time immediately after Node.js finishes establishing the connection to the server to retrieve the resource.
performanceResourceTiming.secureConnectionStart
#
The high resolution millisecond timestamp representing the time immediately before Node.js starts the handshake process to secure the current connection.
performanceResourceTiming.requestStart
#
The high resolution millisecond timestamp representing the time immediately before Node.js receives the first byte of the response from the server.
performanceResourceTiming.responseEnd
#
The high resolution millisecond timestamp representing the time immediately after Node.js receives the last byte of the resource or immediately before the transport connection is closed, whichever comes first.
performanceResourceTiming.transferSize
#
A number representing the size (in octets) of the fetched resource. The size includes the response header fields plus the response payload body.
performanceResourceTiming.encodedBodySize
#
A number representing the size (in octets) received from the fetch (HTTP or cache), of the payload body, before removing any applied content-codings.
performanceResourceTiming.decodedBodySize
#
A number representing the size (in octets) received from the fetch (HTTP or cache), of the message body, after removing any applied content-codings.
performanceResourceTiming.toJSON()
#
Returns a object
that is the JSON representation of the
PerformanceResourceTiming
object
Class: PerformanceObserver
#
PerformanceObserver.supportedEntryTypes
#
Get supported types.
new PerformanceObserver(callback)
#
callback
<Function>list
<PerformanceObserverEntryList>observer
<PerformanceObserver>
PerformanceObserver
objects provide notifications when new
PerformanceEntry
instances have been added to the Performance Timeline.
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');
Because PerformanceObserver
instances introduce their own additional
performance overhead, instances should not be left subscribed to notifications
indefinitely. Users should disconnect observers as soon as they are no
longer needed.
The callback
is invoked when a PerformanceObserver
is
notified about new PerformanceEntry
instances. The callback receives a
PerformanceObserverEntryList
instance and a reference to the
PerformanceObserver
.
performanceObserver.disconnect()
#
Disconnects the PerformanceObserver
instance from all notifications.
performanceObserver.observe(options)
#
options
<Object>type
<string> A single <PerformanceEntry> type. Must not be given ifentryTypes
is already specified.entryTypes
<string[]> An array of strings identifying the types of <PerformanceEntry> instances the observer is interested in. If not provided an error will be thrown.buffered
<boolean> If true, the observer callback is called with a list globalPerformanceEntry
buffered entries. If false, onlyPerformanceEntry
s created after the time point are sent to the observer callback. Default:false
.
Subscribes the <PerformanceObserver> instance to notifications of new
<PerformanceEntry> instances identified either by options.entryTypes
or 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}`);
Class: PerformanceObserverEntryList
#
The PerformanceObserverEntryList
class is used to provide access to the
PerformanceEntry
instances passed to a PerformanceObserver
.
The constructor of this class is not exposed to users.
performanceObserverEntryList.getEntries()
#
- Returns: <PerformanceEntry[]>
Returns a list of PerformanceEntry
objects in chronological order
with respect to 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
* },
* PerformanceEntry {
* name: 'meow',
* entryType: 'mark',
* startTime: 81.860064,
* duration: 0
* }
* ]
*/
performance.clearMarks();
performance.clearMeasures();
observer.disconnect();
});
obs.observe({ type: 'mark' });
performance.mark('test');
performance.mark('meow');
performanceObserverEntryList.getEntriesByName(name[, type])
#
name
<string>type
<string>- Returns: <PerformanceEntry[]>
Returns a list of PerformanceEntry
objects in chronological order
with respect to performanceEntry.startTime
whose performanceEntry.name
is
equal to name
, and optionally, whose performanceEntry.entryType
is equal to
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
* }
* ]
*/
console.log(perfObserverList.getEntriesByName('nope')); // []
console.log(perfObserverList.getEntriesByName('test', 'mark'));
/**
* [
* PerformanceEntry {
* name: 'test',
* entryType: 'mark',
* startTime: 63.518931,
* duration: 0
* }
* ]
*/
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>- Returns: <PerformanceEntry[]>
Returns a list of PerformanceEntry
objects in chronological order
with respect to performanceEntry.startTime
whose performanceEntry.entryType
is equal to 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
* },
* PerformanceEntry {
* name: 'meow',
* entryType: 'mark',
* startTime: 56.350146,
* duration: 0
* }
* ]
*/
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> The lowest discernible value. Must be an integer value greater than 0. Default:1
.highest
<number> | <bigint> The highest recordable value. Must be an integer value that is equal to or greater than two timeslowest
. Default:Number.MAX_SAFE_INTEGER
.figures
<number> The number of accuracy digits. Must be a number between1
and5
. Default:3
.
- Returns <RecordableHistogram>
Returns a <RecordableHistogram>.
perf_hooks.monitorEventLoopDelay([options])
#
options
<Object>resolution
<number> The sampling rate in milliseconds. Must be greater than zero. Default:10
.
- Returns: <IntervalHistogram>
This property is an extension by Node.js. It is not available in Web browsers.
Creates an IntervalHistogram
object that samples and reports the event loop
delay over time. The delays will be reported in nanoseconds.
Using a timer to detect approximate event loop delay works because the execution of timers is tied specifically to the lifecycle of the libuv event loop. That is, a delay in the loop will cause a delay in the execution of the timer, and those delays are specifically what this API is intended to detect.
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));
Class: Histogram
#
histogram.count
#
The number of samples recorded by the histogram.
histogram.countBigInt
#
The number of samples recorded by the histogram.
histogram.exceeds
#
The number of times the event loop delay exceeded the maximum 1 hour event loop delay threshold.
histogram.exceedsBigInt
#
The number of times the event loop delay exceeded the maximum 1 hour event loop delay threshold.
histogram.max
#
The maximum recorded event loop delay.
histogram.maxBigInt
#
The maximum recorded event loop delay.
histogram.mean
#
The mean of the recorded event loop delays.
histogram.min
#
The minimum recorded event loop delay.
histogram.minBigInt
#
The minimum recorded event loop delay.
histogram.percentile(percentile)
#
Returns the value at the given percentile.
histogram.percentileBigInt(percentile)
#
Returns the value at the given percentile.
histogram.percentiles
#
Returns a Map
object detailing the accumulated percentile distribution.
histogram.percentilesBigInt
#
Returns a Map
object detailing the accumulated percentile distribution.
histogram.reset()
#
Resets the collected histogram data.
histogram.stddev
#
The standard deviation of the recorded event loop delays.
Class: IntervalHistogram extends Histogram
#
A Histogram
that is periodically updated on a given interval.
histogram.disable()
#
- Returns: <boolean>
Disables the update interval timer. Returns true
if the timer was
stopped, false
if it was already stopped.
histogram.enable()
#
- Returns: <boolean>
Enables the update interval timer. Returns true
if the timer was
started, false
if it was already started.
Cloning an IntervalHistogram
#
<IntervalHistogram> instances can be cloned via <MessagePort>. On the receiving
end, the histogram is cloned as a plain <Histogram> object that does not
implement the enable()
and disable()
methods.
Class: RecordableHistogram extends Histogram
#
histogram.add(other)
#
other
<RecordableHistogram>
Adds the values from other
to this histogram.
histogram.record(val)
#
histogram.recordDelta()
#
Calculates the amount of time (in nanoseconds) that has passed since the
previous call to recordDelta()
and records that amount in the histogram.
Examples#
Measuring the duration of async operations#
The following example uses the Async Hooks and Performance APIs to measure the actual duration of a Timeout operation (including the amount of time it took to execute the 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'], buffered: true });
setTimeout(() => {}, 1000);
Measuring how long it takes to load dependencies#
The following example measures the duration of require()
operations to load
dependencies:
'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'], buffered: true });
require('some-module');
Measuring how long one HTTP round-trip takes#
The following example is used to trace the time spent by HTTP client
(OutgoingMessage
) and HTTP request (IncomingMessage
). For HTTP client,
it means the time interval between starting the request and receiving the
response, and for HTTP request, it means the time interval between receiving
the request and sending the response:
'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}`);
});
Measuring how long the net.connect
(only for TCP) takes when the connection is successful#
'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);
});
Measuring how long the DNS takes when the request is successful#
'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');