Histogram

histogram.burnRate(sloTarget): number

Returns the SLO burn rate: ewmaErrorRate / (1 - sloTarget). A burn rate of 1 means the error budget will be exactly exhausted over the SLO window. A burn rate greater than 1 means it is being consumed faster than allowed. Requires the histogram to have been created with both halfLife and threshold options.

const { createHistogram } = require('node:perf_hooks');

// Track latency with a 200ms SLO threshold, half-life of 100 samples
const h = createHistogram({ halfLife: 100, threshold: 200_000_000 });

// ... record latency values ...

// Check burn rate against a 99.9% SLO
const rate = h.burnRate(0.999);
if (rate > 1) {
  console.log(`SLO burn rate: ${rate.toFixed(2)}x — error budget depleting`);
}

The number of samples recorded by the histogram.

The number of samples recorded by the histogram.

histogram.ccdf(value): number

Returns the complementary cumulative distribution function (CCDF) value for the given value, representing the probability that a recorded value will exceed value. Equivalent to 1 - histogram.cdf(value).

histogram.cdf(value): number

Returns the cumulative distribution function (CDF) value for the given value, representing the probability that a recorded value will be less than or equal to value. This is the inverse operation of histogram.percentile().

histogram.cliffsD(other): number

Computes Cliff's delta, a non-parametric effect size measure. Returns the probability that a random value from this histogram exceeds a random value from other, minus the reverse probability. A value of 1 means every value in this histogram exceeds every value in other; -1 means the opposite; 0 means no tendency in either direction.

histogram.cohensD(other): number

Computes Cohen's d effect size, the standardized difference between the means of this histogram and other, using the pooled standard deviation. Positive values indicate this histogram has a higher mean. By convention, |d| < 0.2 is a small effect, 0.5 is medium, and 0.8 or greater is large. Both histograms must have at least 2 recorded values; otherwise returns 0.

histogram.countAt(value): number

Returns the number of recorded values that fall within the equivalent value range of the given value.

The number of times the event loop delay exceeded the maximum 1 hour event loop delay threshold.

The number of times the event loop delay exceeded the maximum 1 hour event loop delay threshold.

histogram.export(): Uint8Array

Serializes the histogram to a CBOR-encoded (RFC 8949) Uint8Array suitable for transmission or persistent storage. The encoding uses a delta-encoded sparse representation of the bucket counts, so the output size scales with the number of distinct recorded values rather than the total bucket count.

The output includes all histogram configuration, bucket data, and EWMA state (when enabled). It can be reconstructed into a new histogram using perf_hooks.importHistogram().

The CBOR payload is a map with integer keys:

Any standard CBOR decoder can parse the output.

The exponentially weighted moving average of recorded values. Only active when the histogram was created with a halfLife option greater than 0. Returns 0 when EWMA is disabled or no values have been recorded.

The exponentially weighted moving standard deviation. Only active when the histogram was created with a halfLife option greater than 0. Returns 0 when EWMA is disabled or no values have been recorded.

The EWMA-smoothed probability of a recorded value exceeding the configured threshold. Only active when the histogram was created with both halfLife and threshold options. Returns 0 when not enabled or no values have been recorded.

histogram.ksTest(other): number

Computes the Kolmogorov-Smirnov test statistic comparing this histogram's distribution to other. A value of 0 indicates identical distributions; values close to 1 indicate completely disjoint distributions. Useful for detecting performance regressions by comparing before/after histograms.

The excess kurtosis of the recorded values. Measures the heaviness of the distribution's tails relative to a normal distribution. Positive values indicate heavier tails (more extreme outliers); negative values indicate lighter tails.

histogram.linearBuckets(stepSize): Map

Returns the histogram data rebucketed into linearly-spaced intervals of stepSize. Useful for visualization and export.

histogram.logBuckets(firstBucket, base): Map

Returns the histogram data rebucketed into logarithmically-spaced intervals, where each bucket's width is multiplied by base. Useful for visualization and export.

histogram.mannWhitneyTest(other): Object

Performs a Mann-Whitney U test comparing whether this histogram tends to produce larger or smaller values than other. Unlike welchTest(), this is a non-parametric test that makes no assumptions about the shape of the distributions. Uses the normal approximation with tie correction for the p-value.

The maximum recorded event loop delay.

The maximum recorded event loop delay.

The mean of the recorded event loop delays.

histogram.meanCI(options?): Object

Returns a two-sided confidence interval for the mean using Student's t-distribution and the sample standard error. A higher confidence level produces a wider interval. This interval assumes that samples are independent and approximately normally distributed, although the approximation is robust for sufficiently large samples.

The result reflects the histogram's configured precision and is calculated from the values represented by its buckets. With fewer than two recorded values, lower and upper are NaN. When all recorded values are equal, lower and upper equal mean.

const { createHistogram } = require('node:perf_hooks');

const h = createHistogram();
for (let i = 1; i <= 100; i++) h.record(i);

const { mean, lower, upper } = h.meanCI();
console.log(`mean=${mean}, 95% CI=[${lower}, ${upper}]`);

The minimum recorded event loop delay.

The minimum recorded event loop delay.

histogram.percentile(percentile): number

Returns the value at the given percentile.

histogram.percentileBigInt(percentile): bigint

Returns the value at the given percentile.

histogram.percentileCI(percentile, options?): Object

Returns a confidence interval for the given percentile using the exact binomial method. With fewer samples, the interval will be wider, reflecting the greater uncertainty in the percentile estimate. Requires at least 2 recorded values; with fewer than 2, lower and upper will equal value.

const { createHistogram } = require('node:perf_hooks');

const h = createHistogram();
for (let i = 0; i < 1000; i++) {
  h.record(Math.floor(Math.random() * 100));
}

const ci = h.percentileCI(99);
console.log(ci.value);  // The p99 point estimate
console.log(ci.lower);  // The lower bound (95% confidence)
console.log(ci.upper);  // The upper bound (95% confidence)

Returns a Map object detailing the accumulated percentile distribution.

Returns a Map object detailing the accumulated percentile distribution.

histogram.percentilesAt(percentiles): Map

Returns the values at the specified percentiles, computed in a single efficient pass over the histogram data. More efficient than calling histogram.percentile() multiple times.

histogram.reset(): void

Resets the collected histogram data.

The skewness of the recorded values. Measures the asymmetry of the distribution. A positive value indicates a right-skewed distribution (longer right tail, common for latency data); a negative value indicates a left-skewed distribution.

The standard deviation of the recorded event loop delays.

histogram.welchTest(other, options?): Object

Performs Welch's t-test comparing the means of this histogram and other. The p-value indicates the probability of observing a difference at least this extreme under the null hypothesis that the two distributions have the same mean. Both histograms must have at least 2 recorded values; otherwise the result has pValue 1 and tStatistic 0.