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.
import { createHistogram } from 'node:perf_hooks'; const h = createHistogram(); h.record(120); console.log(h.percentile(50));
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
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
0is 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 withperformance.timerify(fn, { histogram }).- Not thread-safe by itself. Each worker has its own histograms; send
percentilesor summary numbers back as messages, or merge withadd()if the histogram was transferred. monitorEventLoopDelay()returns the same kind of histogram, withenable()anddisable()added.- Added in Node.js 15.9.0 (later versions added
BigIntaccessors).