Performance Measurement APIs in Node.js

1. Introduction

The perf_hooks module allows developers to measure performance in Node.js applications. It is similar to window.performance in browsers but includes Node.js-specific extensions.

2. PerformanceObserver

Used to observe performance events:

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

3. Core performance methods

• performance.mark(name[, options]): Creates a performance mark.
• performance.measure(name[, startMark, endMark]): Measures duration between marks.
• performance.clearMarks([name]): Clears marks.
• performance.clearMeasures([name]): Clears measures.
• performance.clearResourceTimings([name]): Clears resource timings.

4. Event Loop Utilization

• performance.eventLoopUtilization(): Reports idle, active, and utilization metrics for the event loop.

5. Retrieving Entries

• performance.getEntries(): Returns all performance entries.
• performance.getEntriesByName(name[, type]): Filters entries by name.
• performance.getEntriesByType(type): Filters entries by type.

6. High Resolution Timing

• performance.now(): Returns the current high-resolution timestamp.
• performance.timeOrigin: Timestamp when the Node.js process started.

7. Node.js-specific extensions

• performance.nodeTiming: Provides metrics for Node.js operational milestones.
• performance.markResourceTiming(): Creates resource timing entries.
• performance.timerify(fn[, options]): Measures execution time of a function.
• performance.setResourceTimingBufferSize(maxSize): Sets buffer size for resource timings.

Conclusion

The perf_hooks module in Node.js is a powerful tool for performance analysis. By marking key points, measuring durations, and monitoring event loop utilization, developers can identify bottlenecks and optimize their applications for efficiency and scalability.

1. performance.toJSON()

Returns a JSON representation of the performance object. Similar to window.performance.toJSON in browsers.

2. Event: resourcetimingbufferfull

Emitted when the resource timing buffer is full. Developers can adjust the buffer size with performance.setResourceTimingBufferSize() or clear it using performance.clearResourceTimings().

3. Class: PerformanceEntry

The base class for all performance entries. Properties include:

• duration: Elapsed time in milliseconds.
• entryType: Type of entry (dns, function, gc, http, http2, mark, measure, net, node, resource).
• name: Name of the entry.
• startTime: High-resolution start timestamp.

4. Class: PerformanceMark

Subclass of PerformanceEntry created via performance.mark(). Property:

• detail: Additional information provided at creation.

5. Class: PerformanceMeasure

Subclass of PerformanceEntry created via performance.measure(). Property:

• detail: Additional information provided at creation.

6. Class: PerformanceNodeEntry

Node.js-specific subclass of PerformanceEntry. Properties include:

• detail: Extra diagnostic information depending on entry type.
• flags and kind: Deprecated properties for Garbage Collection operations.

7. Garbage Collection (gc) Details

When entryType is gc, detail includes:

• kind: Type of GC (major, minor, incremental, weakcb).
• flags: GC status (forced, retained, idle schedule, etc.).

8. HTTP Details

When entryType is http, detail includes:

• req: Method, URL, headers.
• res: Status code, status message, headers.

Useful for diagnostics, but not recommended for production due to memory overhead.

9. HTTP/2 Details

When entryType is http2, detail includes:

• Http2Stream: bytesRead, bytesWritten, id, timeToFirstByte, timeToFirstHeader.
• Http2Session: framesSent, framesReceived, maxConcurrentStreams, pingRTT, streamCount, type (server/client).

10. Timerify (function) Details

When entryType is function, detail lists the input arguments to the timed function.

11. Net Details

When entryType is net, detail includes:

• connect: host and port information.

Conclusion

The PerformanceEntry classes in Node.js provide detailed insights into application performance. By analyzing marks, measures, and Node.js-specific entries such as GC, HTTP/HTTP2, and Net, developers can diagnose issues and optimize applications for efficiency and scalability.

1. DNS ('dns') Details

When performanceEntry.type is dns, the detail property includes:

• lookup: hostname, family, hints, verbatim, addresses.
• lookupService: host, port, hostname, service.
• queryxxx / getHostByAddr: host, ttl, result.

2. Class: PerformanceNodeTiming

Subclass of PerformanceEntry providing Node.js internal timing metrics:

• bootstrapComplete: Timestamp when bootstrapping finished.
• environment: Timestamp when environment initialized.
• idleTime: Idle time in the event loop.
• loopStart / loopExit: Start and exit times of the event loop.
• nodeStart: Timestamp when Node.js process initialized.
• uvMetricsInfo: Includes loopCount, events processed, events waiting.
• v8Start: Timestamp when V8 platform initialized.

3. Class: PerformanceResourceTiming

Provides detailed network timing data for resource loading:

• workerStart: Before dispatching the fetch request.
• redirectStart / redirectEnd: Start and end of redirects.
• fetchStart: Before fetching begins.
• domainLookupStart / domainLookupEnd: DNS lookup start and end.
• connectStart / connectEnd: Connection establishment times.
• secureConnectionStart: Start of TLS handshake.
• requestStart / responseEnd: Request initiation and response completion.
• transferSize / encodedBodySize / decodedBodySize: Resource sizes in bytes.

4. Class: PerformanceObserver

Observes new PerformanceEntry instances:

• PerformanceObserver.supportedEntryTypes: Lists supported entry types.
• observe(options): Subscribes to specific entry types.
• disconnect(): Stops observing.
• takeRecords(): Retrieves current entries.

5. Class: PerformanceObserverEntryList

Provides access to entries passed to a PerformanceObserver:

• getEntries(): Returns all entries in chronological order.
• getEntriesByName(name[, type]): Filters entries by name and type.

Conclusion

DNS details, PerformanceNodeTiming, PerformanceResourceTiming, and observer classes in Node.js offer powerful tools for performance monitoring. They enable developers to analyze DNS lookups, event loop behavior, and resource loading, providing deep insights for optimizing and troubleshooting applications.

1. performanceObserverEntryList.getEntriesByType(type)

Returns a list of PerformanceEntry objects filtered by entry type:

const { performance, PerformanceObserver } = require('node:perf_hooks');
const obs = new PerformanceObserver((list, observer) => {
  console.log(list.getEntriesByType('mark'));
  performance.clearMarks();
  performance.clearMeasures();
  observer.disconnect();
});
obs.observe({ type: 'mark' });
performance.mark('test');
performance.mark('meow');

2. perf_hooks.createHistogram([options])

Creates a RecordableHistogram for measuring durations:

• lowest: Minimum discernible value.
• highest: Maximum recordable value.
• figures: Accuracy digits (1–5).

3. perf_hooks.eventLoopUtilization()

Returns idle, active, and utilization metrics for the event loop. Supports delta calculations between calls, similar to process.hrtime().

const { eventLoopUtilization } = require('node:perf_hooks');
setImmediate(() => {
  const elu = eventLoopUtilization();
  console.log(eventLoopUtilization(elu).utilization);
});

4. perf_hooks.monitorEventLoopDelay([options])

Creates an IntervalHistogram to sample event loop delays:

• resolution: Sampling rate in ms (default: 10).

const { monitorEventLoopDelay } = require('node:perf_hooks');
const h = monitorEventLoopDelay({ resolution: 20 });
h.enable();
// ... operations ...
h.disable();
console.log(h.mean, h.max, h.percentile(99));

5. perf_hooks.timerify(fn[, options])

Wraps a function to measure its execution time. Requires a PerformanceObserver subscribed to 'function' entries:

const { timerify, PerformanceObserver } = require('node:perf_hooks');
function hello() { console.log('world'); }
const wrapped = timerify(hello);
const obs = new PerformanceObserver((list) => {
  console.log(list.getEntries()[0].duration);
});
obs.observe({ entryTypes: ['function'] });
wrapped();

6. Histogram Classes

• Histogram: Base class with min, max, mean, stddev, percentiles.
• IntervalHistogram: Extends Histogram, updated periodically.
• RecordableHistogram: Extends Histogram, supports record(), recordDelta(), and add().

7. Example Use Cases

• Measure async operation durations with performance.mark and measure.
• Trace dependency loading times using timerify(require).
• Monitor HTTP round-trip times with 'http' entries.
• Measure TCP connection times with 'net' entries.
• Track DNS lookup durations with 'dns' entries.

Conclusion

The advanced APIs in perf_hooks—including histograms, event loop monitoring, and timerify—give developers precise tools for performance analysis. By combining these with PerformanceObserver, Node.js applications can be profiled and optimized with high accuracy.