HdrHistogram (Rust)

HdrHistogram for Rust is a native port of Gil Tene’s HdrHistogram that records and analyzes sampled value counts across a large, configurable value range while maintaining a fixed, user-chosen precision. It is designed for latency- and performance-sensitive applications where you need accurate percentile analysis of the extreme tail of a distribution without paying for allocations at record time.

A histogram’s memory footprint is constant and depends only on the configured dynamic range and precision, not on the number of samples recorded. Recording a value is a constant-time operation that computes a storage index directly, making it suitable for hot paths such as request handlers and benchmarking loops.

What You Get

• A generic Histogram<T> type with configurable significant digits, bounds, and optional auto-resizing
• Constant-time, allocation-free record and record_correct methods, the latter correcting for coordinated omission
• Rich quantile, percentile, mean, max, and count queries plus a family of iterators over recorded values
• Optional serialization (compressed and interval-log formats) and synchronized recording behind feature flags
• Extensive test suite and runnable CLI example for exploring the API

Common Use Cases

• Measuring and reporting request/response latency percentiles in servers and clients
• Collecting benchmark timing distributions with accurate tail analysis
• Aggregating histograms recorded across distributed nodes for centralized analysis
• Tracking value distributions in performance-sensitive hot paths without allocation overhead

Under The Hood

Architecture - The crate centers on a generic Histogram<T: Counter> defined in src/core, which maps recorded values to bucket/sub-bucket indices computed arithmetically from the configured significant digits, so recording never searches or allocates. Supporting modules split cleanly into iterators (linear, logarithmic, recorded, percentile walks), serialization (compressed V2 encoding and interval logs, feature-gated), sync (channel-backed recorder), and errors for typed failure modes.

Tech Stack - Written in Rust targeting the 2024 edition (rust-version 1.88), with a small dependency surface: num-traits and byteorder are always required, while flate2, nom, and base64 back the optional serialization feature and crossbeam-channel backs the optional sync feature. Default features enable serialization and sync; both can be disabled for a minimal build.

Code Quality - Testing is thorough: unit tests live under src/tests (index and value calculation, init, subtract) and integration tests under tests/ cover auto-resize, data access, iterators, quantiles, serialization, and sync, with benches/ for performance. Error handling is explicit via Result/Option return types, with panicking AddAssign/SubAssign forms clearly documented as unwrap equivalents.

API Design - The public API is compact and idiomatic: three new constructors express the range/precision trade-off, record/record_correct cover the coordinated-omission case, and query methods read naturally (value_at_quantile, len, mean). Extensive rustdoc, a cli example, and README walkthroughs keep the learning curve manageable for anyone familiar with percentile analysis.