Registry / observability / hdr-histogram-js

hdr-histogram-js

library3.0.1jsnpmunverified

HdrHistogram.js is a TypeScript port of the HdrHistogram library, designed for high-fidelity recording and analysis of latency and other value distributions in both Node.js and web browser environments. The library is currently stable at version 3.0.1, with a history of regular updates including significant architectural changes. A key differentiator since version 2 is the introduction of an optional WebAssembly (WASM) implementation, leveraging AssemblyScript to provide substantial performance gains for recording and processing histograms, though this is not enabled by default. It supports core HdrHistogram features such as regular and coordinated omission-corrected latency recording, resizable and memory-optimized 'packed' histograms, and the ability to add, subtract, encode, and decode compressed histograms. It also includes client-side data visualization tools for browser-based analysis. Release cadence appears to be driven by feature enhancements and performance optimizations, with major versions often introducing substantial improvements.

observability serialization

npm install hdr-histogram-js

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · HDR-HISTOGRAM-JS

hdr-histogram-js

observabilityjavascriptv3.0.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

hdr

✓ import * as hdr from 'hdr-histogram-js'

✗ import hdr from 'hdr-histogram-js'

This is the primary namespace import pattern shown in documentation for ES6+ environments.

build

✓ import { build } from 'hdr-histogram-js'

✗ import build from 'hdr-histogram-js'

The `build` function is a named export for creating histogram instances. Avoid default import syntax.

Histogram

✓ import { Histogram } from 'hdr-histogram-js'

✗ import Histogram from 'hdr-histogram-js'

The `Histogram` class is a named export, primarily used for type annotation or direct class instantiation if not using the `build` factory.

CommonJS require

✓ const hdr = require('hdr-histogram-js')

✗ const hdr = require('hdr-histogram-js').default

While the library supports CommonJS, modern Node.js projects (>=14) and bundlers typically favor ES Modules. Use direct `require` without `.default` for namespace import.

Demonstrates how to build a histogram, record values, and retrieve basic percentile metrics, including an example of coordinated omission correction.

import { build, Histogram } from 'hdr-histogram-js'; // Build a default histogram with auto-resizing, tracking values from 1 to 2, and 3 significant digits. // WebAssembly is not enabled by default for maximum compatibility. const histogram: Histogram = build({ lowestDiscernibleValue: 1, highestTrackableValue: 10000000000, // 10 billion numberOfSignificantValueDigits: 3, useWebAssembly: false // Explicitly set to false, true for performance if available }); // Record some values representing latencies in microseconds histogram.recordValue(1000); histogram.recordValue(5000); histogram.recordValue(100); for (let i = 0; i < 1000; i++) { histogram.recordValue(Math.floor(Math.random() * 9000) + 1000); } histogram.recordValue(9999); console.log(`Total count: ${histogram.totalCount}`); console.log(`90th percentile: ${histogram.getValueAtPercentile(90)} µs`); console.log(`99th percentile: ${histogram.getValueAtPercentile(99)} µs`); console.log(`Max value: ${histogram.maxValue} µs`); // Example of coordinated omission correction const histogramWithCoordinatedOmissions = build({ lowestDiscernibleValue: 1, highestTrackableValue: 10000000000, numberOfSignificantValueDigits: 3 }); histogramWithCoordinatedOmissions.recordValueWithExpectedInterval(100, 10); // Record a value of 100, expecting 10ms interval console.log(` Histogram with coordinated omissions (total count: ${histogramWithCoordinatedOmissions.totalCount}):`); console.log(`90th percentile (corrected): ${histogramWithCoordinatedOmissions.getValueAtPercentile(90)} µs`);

Debug

Known issues

breakingVersion 2.0.0 introduced significant architectural changes and the optional WebAssembly (WASM) implementation. While not strictly 'breaking' for API compatibility, performance characteristics and default behaviors changed.

fix

Review the WebAssembly section in the documentation (since hdrhistogramjs v2) to understand performance implications and how to opt-in to WASM. The `useWebAssembly` option on `build()` is `false` by default.

affects: >=2.0.0

gotchaThe WebAssembly implementation, introduced in v2.0.0, offers significant performance benefits but is not enabled by default. Users must explicitly opt-in if they wish to use it.

fix

When building a histogram, set `useWebAssembly: true` in the options object passed to `hdr.build()`. Ensure your execution environment supports WebAssembly.

affects: >=2.0.0

gotchaChoosing the correct `bitBucketSize` or using the `'packed'` option influences both memory footprint and performance. 'packed' histograms use less memory but are significantly slower.

fix

Carefully evaluate your use case. For high-performance, higher-throughput scenarios, avoid `bitBucketSize: 'packed'`. For minimal memory usage with infrequent updates, 'packed' may be suitable. The default `bitBucketSize` is usually a good balance.

affects: >=1.2.0

gotchaThe library explicitly lists a Node.js engine requirement of `>=14`.

fix

Ensure your Node.js environment is version 14 or higher to guarantee compatibility and access to modern JavaScript features and WebAssembly support.

affects: >=2.0.0

Errors

Common errors & fixes

ReferenceError: require is not defined

Attempting to use CommonJS `require()` syntax in an ES Module context (e.g., a file with `"type": "module"` in `package.json` or `.mjs` extension).

fix

Convert `require('hdr-histogram-js')` to `import * as hdr from 'hdr-histogram-js'` or `import { build } from 'hdr-histogram-js'`.

TypeError: build is not a function

Attempting to import the `build` function as a default import (e.g., `import build from 'hdr-histogram-js'`) when it is a named export.

fix

Use named import syntax: `import { build } from 'hdr-histogram-js'`.

WebAssembly is not available in this environment

The `useWebAssembly: true` option was provided when building a histogram, but the current runtime environment (e.g., an older browser, specific Node.js configuration) does not support WebAssembly or has it disabled.

fix

Either remove `useWebAssembly: true` to fall back to the TypeScript implementation, or ensure the execution environment fully supports WebAssembly (e.g., update browser, use a compatible Node.js version).

Upgrade

Version history

3.0.1latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

14 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/HdrHistogram/HdrHistogramJS ↗

packagehttps://www.npmjs.com/package/hdr-histogram-js ↗

homepagehttp://hdrhistogram.org ↗