Rust OpenTelemetry Exponential Histogram

CI crates.io docs.rs License

An allocation-free, compile-time table-lookup based implementation of the OpenTelemetry Exponential Histogram in Rust.

Exponential histograms provide a compact, high-resolution representation of value distributions using logarithmically-spaced bucket boundaries. This implementation is designed for:

• No heap allocation: Fixed-size bucket storage using const generics (Histogram<N>)
• Send + Sync: All fields are Copy primitives; safe to share across threads with external synchronization
• High performance: Lookup table provides ×ばつ speedup over logarithm-based mapping
• Sub-byte counters: 1-bit bucket counters (B1) maximize resolution; auto-widen on overflow
• Configurable table size: Trade static memory for lookup acceleration at higher scales
• Quantile estimation: CDF-walk with linear interpolation over the bucket distribution
• Compact configuration: 2-byte Settings struct pairs Scale + Width; histograms track both initial and current settings
• no_std compatible: Only the std::error::Error impls require the std feature
• Zero unsafe code: Entirely safe Rust; no unsafe blocks anywhere in the crate
• Zero runtime dependencies: Only a build dependency (expohisto-mapping-gen) for compile-time table generation
• Comprehensive testing: Unit tests and fuzz targets

Minimum Supported Rust Version (MSRV): 1.83

• HistogramNN is positive-only — HistogramNN<N> (aliased as Histogram<N>) implements a single positive bucket set; negative values are rejected. This is suitable for the common case of non-negative measurements (latencies, sizes, counts). For values of any sign, use HistogramPN<K, L> which maintains independent positive and negative bucket ranges with synchronized scales.

use otel_expohisto::Histogram;
// Create a histogram with 16 u64 words (128 bytes) of data pool.
// All 16 words are available for bucket data: 1024 one-bit buckets
// at the default B1 width.
let mut hist: Histogram<16> = Histogram::new();
// Record observations
hist.update(1.5).unwrap();
hist.update(2.7).unwrap();
hist.update(100.0).unwrap();
// Access statistics through a view
let v = hist.view();
let stats = v.stats();
println!("count: {}, sum: {}", stats.count, stats.sum);
println!("scale: {}", v.scale());

Benchmark results — map_to_index over 100 random f64 values (criterion, median):

The lookup table accelerates all scales from 1 up to the compiled maximum. Scales beyond the table maximum are rejected by Scale::new().

Scale features scale-1 through scale-16 control the lookup table size. Each table supports all scales from 1 up to its maximum; higher scales are rejected by Scale::new(). Selected examples:

• Design & Architecture — Exponential scale theory, index mapping algorithms, lookup table design, crate structure
• Implementation Details — Literal mode, sub-byte counters (SWAR), parameter selection, API overview
• Reference — Error handling, thread safety, no_std support, testing, OTel spec compatibility
• Historical Notes — Origins of the lookup table algorithm

See CONTRIBUTING.md for build, test, fuzz, and PR guidelines.

Quick validation:

cargo clippy --all-targets --features bench-all -- -D warnings
cargo test --features bench-all
cargo check --manifest-path fuzz/Cargo.toml --all-targets

Apache-2.0