A fixed-layout, allocation-free histogram backed by an :counters array.

Percentiles are the one measurement you cannot compute from a plain counter, and computing them the obvious way — keeping the samples — costs an allocation on every event. Kepler instead keeps a bucketed distribution: a value is mapped to a bucket with a handful of integer operations, and recording it is a single atomic increment.

Layout

Buckets are log-linear, the same scheme HdrHistogram uses. Values below 16 land in their own exact bucket; above that, each power of two is split into 16 sub-buckets. That bounds the relative error at 1/16 — under 6.25% — across the whole range, while needing only 960 slots to cover every positive 64-bit integer.

A bucket's reported value is its upper bound, so "p99 = 2431" reads as "99% of samples were at or below 2431" — never an undershoot, which is the semantic you want when the number is feeding a threshold.

Reading

Counters only ever increase, so a tick reads the whole array and subtracts the previous read. delta/2 does that, and percentile/3 interpolates over the result.

iex> ref = :counters.new(Kepler.Histogram.slots(), [:write_concurrency])
iex> Enum.each([100, 120, 5_000], &Kepler.Histogram.record(ref, &1))
iex> {counts, total} = Kepler.Histogram.delta(Kepler.Histogram.snapshot(ref), Kepler.Histogram.zeros())
iex> total
3
iex> Kepler.Histogram.percentile(counts, total, 50) in 120..128
true