Skip to content
Tutorials Center
My learning

Topics

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

Node.js createHistogram() function

Reference for perf_hooks.createHistogram() in Node.js: record integer values, then read count, min, max, mean, stddev and percentiles from a recordable histogram.

createHistogram() from node:perf_hooks returns a recordable histogram: an object that stores a large number of integer measurements in a compact form and can answer statistical questions about them, such as the median or the 99th percentile. It is built on an HDR histogram, so memory use does not grow with the number of samples.

Use it to track latencies, payload sizes or any positive integer quantity in a long-running process, where keeping every value would be wasteful. You feed it with record() and read it with percentile(), mean, max and friends.

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

const h = createHistogram();
h.record(120);
console.log(h.percentile(50));

Try it

Node.js Recording values and reading statistics

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 Limits, bad values and combining histograms

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
createHistogram(options?: {
  lowest?: number | bigint,
  highest?: number | bigint,
  figures?: number,
}): RecordableHistogram
Name Description
lowest Smallest value the histogram can distinguish. Default 1; must be at least 1.
highest Largest value it can track. Default Number.MAX_SAFE_INTEGER; must be at least twice lowest.
figures Number of significant digits of accuracy, from 1 to 5. Default 3.

Members of the returned histogram:

Name Description
record(value) Adds one integer value (a number or a BigInt) of at least 1.
recordDelta() Records the time since the previous recordDelta() call, in nanoseconds. The first call only starts the clock.
add(other) Adds all samples of another histogram.
count, min, max, mean, stddev Summary numbers (countBigInt, minBigInt and maxBigInt give exact BigInt forms).
percentile(p) The value below which p percent of samples fall (p from 0 to 100).
percentiles A Map of percentile to value.
exceeds, exceedsBigInt How many recorded values were above highest.
reset() Clears all samples.

Errors: record() throws a RangeError for 0, negative numbers and fractions, and a TypeError for non-numbers. Values above highest do not throw: they are counted in exceeds and not in count. Invalid options to createHistogram() throw as well.

Usage notes

  • Values must be positive integers. To record milliseconds with fractions, scale them to microseconds or nanoseconds first. Recording 0 is an error.
  • Results are approximate to the number of figures. A percentile may be slightly above or below the exact value.
  • Memory depends on the range and accuracy, not on the sample count. A wider range and more figures use more memory.
  • timerify() can fill a histogram automatically with performance.timerify(fn, { histogram }).
  • Not thread-safe by itself. Each worker has its own histograms; send percentiles or summary numbers back as messages, or merge with add() if the histogram was transferred.
  • monitorEventLoopDelay() returns the same kind of histogram, with enable() and disable() added.
  • Added in Node.js 15.9.0 (later versions added BigInt accessors).