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.
const observer = new PerformanceObserver((list) => { for (const entry of list.getEntries()) console.log(entry.name); }); observer.observe({ entryTypes: ['measure'] });
Try it
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.
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
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
gcorhttpkeeps getting entries for as long as it exists.disconnect()stops it. entryTypesversustype.entryTypeswatches several types but never delivers old entries.typehandles one type per call and supportsbuffered: true. Callingobserve()again withentryTypesreplaces the earlier subscription; withtypeit adds one.gcentries have adetailobject (kind and flags), useful for spotting long collections without tracing flags.httpentries come fromhttp.createServerandhttp.request. Each hasname('HttpRequest'or'HttpClient') and aduration.- 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()andclearMeasures().