{"id":9807,"library":"hdrhistogram","title":"HdrHistogram Python Wrapper","description":"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.","status":"active","version":"0.10.3","language":"en","source_language":"en","source_url":"https://github.com/HdrHistogram/HdrHistogram_py","tags":["histogram","metrics","performance","latency","statistics"],"install":[{"cmd":"pip install hdrhistogram","lang":"bash","label":"Default installation"}],"dependencies":[],"imports":[{"symbol":"HdrHistogram","correct":"from hdrhistogram import HdrHistogram"}],"quickstart":{"code":"from hdrhistogram import HdrHistogram\n\n# Create a histogram with a precision of 3 significant digits,\n# a max value of 1,000,000 (1 second), and a min value of 1 (1 microsecond).\n# The internal C library will auto-adjust max value if exceeded.\nh = HdrHistogram(1, 1_000_000, 3)\n\n# Record some values (e.g., latencies in microseconds)\nh.record_value(100)\nh.record_value(150)\nh.record_value(1000)\nh.record_value(1000)\nh.record_value(1000)\nh.record_value(5000)\nh.record_value(100_000) # This will exceed the initial max, but the histogram self-adjusts\n\nprint(f\"Total count: {h.total_count}\")\nprint(f\"Min value: {h.min_value}\")\nprint(f\"Max value: {h.max_value}\")\nprint(f\"Mean value: {h.mean_value:.2f}\")\nprint(f\"Std Deviation: {h.std_deviation:.2f}\")\n\nprint(\"\\nPercentiles:\")\nprint(f\"50th percentile: {h.get_value_at_percentile(50):.2f}\")\nprint(f\"90th percentile: {h.get_value_at_percentile(90):.2f}\")\nprint(f\"99th percentile: {h.get_value_at_percentile(99):.2f}\")\nprint(f\"99.9th percentile: {h.get_value_at_percentile(99.9):.2f}\")\n\n# You can also iterate through percentiles\nprint(\"\\nPercentile distribution:\")\nfor p, v in h.get_percentile_to_value_list():\n    if p % 10 == 0 or p > 99: # print every 10th percentile and high percentiles\n        print(f\"{p:>6.2f}th percentile: {v:>10.2f}\")\n\n# Reset the histogram\nh.reset()\nprint(f\"\\nAfter reset, total count: {h.total_count}\")","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade your project's Python interpreter to Python 3.x (3.6+ is generally recommended for current Python libraries).","message":"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.","severity":"breaking","affected_versions":">=0.10.0"},{"fix":"Upgrade to `hdrhistogram==0.10.3` or newer to ensure the `dump_hdrh` script is correctly installed and available in your PATH.","message":"The `dump_hdrh` command-line utility was not correctly installed with `pip` in versions 0.10.0 through 0.10.2.","severity":"gotcha","affected_versions":"0.10.0 - 0.10.2"},{"fix":"Upgrade to `hdrhistogram==0.10.0` or newer to remove the vulnerable `future` dependency and ensure better Python 3 compatibility.","message":"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.","severity":"deprecated","affected_versions":"<0.10.0"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"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))`.","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.","error":"TypeError: an integer is required (got type float)"},{"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.","cause":"The `hdrhistogram` package is not installed in the current Python environment, or the environment is not correctly activated.","error":"ModuleNotFoundError: No module named 'hdrhistogram'"},{"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)`.","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`.","error":"TypeError: HdrHistogram() argument 2 must be an integer, not tuple"}]}