Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท Web APIs in Node.js

Node.js PerformanceObserver class

Reference for PerformanceObserver in Node.js: subscribe to mark, measure, function, gc and http entries, buffered delivery, entry types and cleanup.

PerformanceObserver lets you subscribe to performance entries as they are recorded, instead of polling performance.getEntries(). You create an observer with a callback, tell it which entry types to watch, and Node.js calls the callback with a list of new entries.

It is a global and also exported from node:perf_hooks. The entry types you meet most often are mark and measure (user timing, see performance.mark() and measure()), function (functions wrapped with performance.timerify()), gc (garbage collections), http and http2 (server and client request timings), net, dns and resource.

NODE
const observer = new PerformanceObserver((list) => {
  for (const entry of list.getEntries()) console.log(entry.name);
});
observer.observe({ entryTypes: ['measure'] });

Try it

Node.js Watching marks and measures

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Node.js Timing a function with timerify

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Syntax

NODE
const observer = new PerformanceObserver(callback);
observer.observe({ entryTypes: [...] });          // several types, no buffering
observer.observe({ type: 'measure', buffered: true }); // one type per call
observer.disconnect();
observer.takeRecords();                           // PerformanceEntry[]
PerformanceObserver.supportedEntryTypes;          // string[]

callback(list, observer)
list.getEntries();
list.getEntriesByName(name[, type]);
list.getEntriesByType(type);
Name Description
callback Called with a PerformanceObserverEntryList and the observer itself. Delivery is asynchronous and batched.
entryTypes Array of entry type names to watch. Cannot be combined with type.
type A single entry type. Allows buffered.
buffered With type, also delivers entries recorded before observe() was called.
takeRecords() Returns and clears the entries queued but not yet delivered.

Returns: observe() and disconnect() return undefined.

Errors: entry types the runtime does not support are skipped; calling observe() with both entryTypes and type throws a TypeError with code ERR_INVALID_ARG_VALUE.

Usage notes

  • Callbacks are asynchronous. The observer runs after the code that created the entries, so output from your synchronous code appears first, as in the first example.
  • Disconnect when done. An observer on a busy type such as gc or http keeps getting entries for as long as it exists. disconnect() stops it.
  • entryTypes versus type. entryTypes watches several types but never delivers old entries. type handles one type per call and supports buffered: true. Calling observe() again with entryTypes replaces the earlier subscription; with type it adds one.
  • gc entries have a detail object (kind and flags), useful for spotting long collections without tracing flags.
  • http entries come from http.createServer and http.request. Each has name ('HttpRequest' or 'HttpClient') and a duration.
  • Durations vary between runs. Assert on structure, not on exact milliseconds, in tests.
  • Entries are not kept forever. The global timeline holds marks and measures until you call performance.clearMarks() and clearMeasures().