HdrHistogram.js

Common errors

• ReferenceError: require is not defined

  cause 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

  cause 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

  cause 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).

Warnings

• breaking Version 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.
• gotcha The 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.
• gotcha Choosing 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.
• gotcha The 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.

Install

• npm install hdr-histogram-js npm
• yarn add hdr-histogram-js yarn
• pnpm add hdr-histogram-js pnpm

Imports

• hdr
  wrong:

  import hdr from 'hdr-histogram-js'

  correct:

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

  This is the primary namespace import pattern shown in documentation for ES6+ environments.
• build
  wrong:

  import build from 'hdr-histogram-js'

  correct:

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

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

  import Histogram from 'hdr-histogram-js'

  correct:

  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
  wrong:

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

  correct:

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

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

Quickstart

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`);