HdrHistogram Python Wrapper

0.10.3 · active · verified Fri Apr 17

HdrHistogram is a native Python wrapper for the High Dynamic Range Histogram C library, designed for recording and analyzing sampled data (like latencies) with high precision over a wide dynamic range. It's currently at version 0.10.3 and typically sees maintenance releases as needed, with major changes often aligning with the upstream C library or Python version support.

Common errors

```
TypeError: an integer is required (got type float)
```
cause The `record_value` and similar methods in `hdrhistogram` expect integer values (e.g., microseconds, nanoseconds). Passing floating-point numbers directly will raise a TypeError.

fix Ensure all values passed to `record_value` (and related methods like `record_corrected_value`) are integers. Convert floats to integers by multiplying by an appropriate scaling factor and casting, e.g., `h.record_value(int(latency_in_seconds * 1_000_000))`.
```
ModuleNotFoundError: No module named 'hdrhistogram'
```
cause The `hdrhistogram` package is not installed in the current Python environment, or the environment is not correctly activated.

fix Install the package using pip: `pip install hdrhistogram`. If you are using virtual environments, ensure the correct environment is activated before running your Python script.
```
TypeError: HdrHistogram() argument 2 must be an integer, not tuple
```
cause The `HdrHistogram` constructor was called with incorrect argument types. For example, passing a tuple instead of separate integer arguments for `low_val`, `high_val`, and `significant_figures`.

fix Review the constructor signature. It expects `HdrHistogram(low_val, high_val, significant_figures)`. Ensure all three arguments are integers, like `HdrHistogram(1, 1_000_000, 3)`.

Warnings

breaking Python 2.7 support was dropped in version 0.10.0. Projects still using Python 2.7 will fail to install or run with newer versions.
Fix: Upgrade your project's Python interpreter to Python 3.x (3.6+ is generally recommended for current Python libraries).
gotcha The `dump_hdrh` command-line utility was not correctly installed with `pip` in versions 0.10.0 through 0.10.2.
Fix: Upgrade to `hdrhistogram==0.10.3` or newer to ensure the `dump_hdrh` script is correctly installed and available in your PATH.
deprecated Older versions (pre-0.10.0) had a dependency on the `future` package, which contained a known denial-of-service vulnerability (CVE-2022-40899). This dependency has been removed.
Fix: Upgrade to `hdrhistogram==0.10.0` or newer to remove the vulnerable `future` dependency and ensure better Python 3 compatibility.

Install

pip install hdrhistogram Default installation

Imports

HdrHistogram
```
from hdrhistogram import HdrHistogram
```

Quickstart

Initialize an HdrHistogram, record sample values, and retrieve various statistics including min, max, mean, standard deviation, and specific percentiles. The example also shows how the histogram automatically adjusts to values exceeding its initial maximum.

from hdrhistogram import HdrHistogram

# Create a histogram with a precision of 3 significant digits,
# a max value of 1,000,000 (1 second), and a min value of 1 (1 microsecond).
# The internal C library will auto-adjust max value if exceeded.
h = HdrHistogram(1, 1_000_000, 3)

# Record some values (e.g., latencies in microseconds)
h.record_value(100)
h.record_value(150)
h.record_value(1000)
h.record_value(1000)
h.record_value(1000)
h.record_value(5000)
h.record_value(100_000) # This will exceed the initial max, but the histogram self-adjusts

print(f"Total count: {h.total_count}")
print(f"Min value: {h.min_value}")
print(f"Max value: {h.max_value}")
print(f"Mean value: {h.mean_value:.2f}")
print(f"Std Deviation: {h.std_deviation:.2f}")

print("\nPercentiles:")
print(f"50th percentile: {h.get_value_at_percentile(50):.2f}")
print(f"90th percentile: {h.get_value_at_percentile(90):.2f}")
print(f"99th percentile: {h.get_value_at_percentile(99):.2f}")
print(f"99.9th percentile: {h.get_value_at_percentile(99.9):.2f}")

# You can also iterate through percentiles
print("\nPercentile distribution:")
for p, v in h.get_percentile_to_value_list():
    if p % 10 == 0 or p > 99: # print every 10th percentile and high percentiles
        print(f"{p:>6.2f}th percentile: {v:>10.2f}")

# Reset the histogram
h.reset()
print(f"\nAfter reset, total count: {h.total_count}")

view raw JSON →