Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท node:sqlite and Runtime Services

Node.js performance.timerify() method

Reference for performance.timerify() in Node.js: wrap a function so every call is timed and reported to a PerformanceObserver or a histogram.

performance.timerify(fn) returns a wrapper around fn. The wrapper behaves like the original: same arguments, same return value, same this. But each call is also timed, and the timing is published as a performance entry of type function that a PerformanceObserver can receive.

It is a low-friction way to profile a function without editing its body or adding performance.now() calls by hand. You can also pass a histogram to collect the durations into a distribution.

NODE
import { PerformanceObserver } from 'node:perf_hooks';

const timed = performance.timerify(function work() { /* ... */ });

Try it

Node.js Observing timed calls

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 Collecting durations in a histogram

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
performance.timerify<T extends Function>(fn: T, options?: {
  histogram?: RecordableHistogram,
}): T
Name Description
fn The function to wrap. A normal function, an arrow function or a class constructor.
options.histogram A histogram created with createHistogram(). Each call's duration (in nanoseconds, as an integer) is recorded into it.

Returns: a wrapper function. The entries it produces have entryType: 'function', the original function's name as name, and the call arguments in detail.

Errors: a TypeError with code ERR_INVALID_ARG_TYPE if fn is not a function, or if histogram is not a recordable histogram.

Usage notes

  • Nothing is reported without an observer or histogram. Calling the wrapper with neither attached costs a little and produces no visible output.
  • Entries are delivered asynchronously. An observer's callback runs after the current work finishes, so do not expect output between calls in synchronous code.
  • Asynchronous functions: the duration covers the time until the function returns. For an async function that is when it returns its promise, not when the promise settles. Time awaited work with performance.now() before and after the await.
  • Use the histogram for many calls. Receiving an entry per call is expensive in hot code. A histogram aggregates in place and you read percentile(), mean and max afterwards.
  • Wrap once, call many times. Create the wrapper at startup; wrapping inside a loop adds overhead and creates new function objects.
  • The wrapper is a different function object, so identity comparisons with the original fail, and its name is the original name with a timerified prefix. The entries, however, carry the original name.