Measure elapsed execution time
Benchmarking synchronous or asynchronous code paths.
Node.js · Module
node:perf_hooks
node:perf_hooks provides browser-compatible performance APIs and Node.js-specific measurements. It supports high-resolution timing, user and resource timing, observers, function instrumentation, and event-loop utilization.
- Since
- v8.5.0
How it works
The module exposes browser-aligned Performance APIs plus Node-specific measurements. Use the shared performance object for high-resolution timestamps, user-timing marks and measures, timeline queries, resource timing, function instrumentation, and event-loop utilization.
Syntax
const perf_hooks = require('node:perf_hooks');Parameters
| Name | Type | Description |
|---|---|---|
fn | Function | Function to instrument with performance timing. |
name | string | Name assigned to a user-timing mark. |
options | PerformanceMarkOptions | Optional mark configuration. |
startMarkOrOptions | string | PerformanceMeasureOptions | Optional first mark or measure configuration. |
endMark | string | Optional ending mark name. |
Returns
The module exposes performance measurement APIs, including a performance object, timing classes, and PerformanceObserver. Individual methods return timestamps, performance entries, entry collections, utilization objects, or wrapped functions as applicable.
Key points
node:perf_hooksimplements selected Web Performance APIs and adds measurements specific to Node.js.- The exported
performanceobject is the main interface for collecting metrics from the running Node.js instance. performance.mark(name)records a named point that can later be queried or used by a measure.- Performance entries can be queried by retrieving all entries, filtering by name, or filtering by entry type.
- Event-loop utilization exposes active and idle timing as a high-resolution measurement.
Common mistakes
- performance.now() is process-relative, so its value is not a Unix timestamp and should not be compared directly with Date.now().
- Function timing data is available only when a PerformanceObserver subscribes to the function entry type.
- Observed resource-timing entries can remain in the timeline; clear them explicitly when they are no longer needed.
Example: Measure elapsed time
const { performance } = require('node:perf_hooks');
const start = performance.now();
for (let i = 0; i < 1_000_000; i++);
const elapsed = performance.now() - start;
console.log(`Elapsed: ${elapsed.toFixed(2)} ms`);Measures elapsed wall-clock time with a high-resolution timestamp.
When to use it
Instrument user-timing spans
Tracking named application phases with timeline entries.
Monitor event-loop utilization
Diagnosing event-loop saturation in a server.
Observe function performance
Collecting execution durations for selected functions.
Interview questions
QWhat does performance.now() measure?
performance.now() returns a high-resolution millisecond timestamp relative to the start of the current Node.js process. Subtracting two readings gives an elapsed duration without depending on the system wall clock.
Follow-up: How would you time a named operation? Use performance.mark() before and after it, then call performance.measure() and retrieve the resulting entry from the Performance Timeline.
QWhat is the role of PerformanceObserver?
PerformanceObserver receives notifications when new PerformanceEntry objects are added to the Performance Timeline. The observer must be configured with the entry types relevant to the measurements being collected.
Follow-up: How can function execution be observed? Wrap the function with performance.timerify() and observe the resulting function entries using a PerformanceObserver subscribed to the function type.
QWhat does eventLoopUtilization() provide?
eventLoopUtilization() reports cumulative active and idle event-loop time in high-resolution milliseconds. Passing earlier utilization values lets it calculate utilization over an interval rather than only since process start.
Follow-up: Why use interval values? Comparing snapshots isolates a measurement window and avoids confusing lifetime utilization with the period being investigated.
Related
performancePerformanceObserverPerformanceEntryPerformanceMarkPerformanceMeasureperformance.markperformance.measureperformance.now