com.eignex.kumulant/stat/quantile/BucketHistogramStat

BucketHistogramStat

class BucketHistogramStat(edges: DoubleArray, val concurrency: Concurrency = Concurrency.None) : SeriesStat<SparseHistogramResult> (source)

Weighted histogram over fixed, caller-chosen bucket edges.

For edges [e0, e1, ..., eK] (strictly increasing) the stat keeps K + 2 buckets: (-inf, e0], (e(i-1), e(i)] for each consecutive pair, and (eK, +inf). Each bucket includes its upper edge, the le convention of Prometheus-style latency buckets. linear builds evenly spaced edges.

Counts are additive, so a negative weight downdates its bucket and a count can go negative; callers must not read one as a population.

Merge adds an interval of the incoming snapshot to the bucket holding its midpoint (or its finite end, for an open interval). A snapshot over the same edges merges exactly; one from another layout, such as SketchResult.toSparseHistogram, is rebinned approximately.

Use cases: distribution-shape monitoring with caller-chosen bin edges, SLO latency buckets, calibration and probability histograms over a known range. Reach for DDSketchStat for unbounded values with logarithmic resolution.

Memory: O(K); one double cell per bucket.

Update: O(log K); binary search over the edges, single atomic add into the bucket.

Concurrency: Per-bucket atomic adds. Exact under every Concurrency level since each update touches exactly one cell.

Constructors

BucketHistogramStat

constructor(edges: DoubleArray, concurrency: Concurrency = Concurrency.None)(source)

Types

Companion

object Companion

Factories for common edge layouts.

Properties

bucketEdges

val bucketEdges: List<Double>(source)

Bucket edges, in increasing order.

concurrency

open override val concurrency: Concurrency(source)

Thread-safety mode fixed at construction. See Concurrency for the shared contract and the implementation's KDoc for its cell and lock strategy.

Functions

create

open override fun create(concurrency: Concurrency? = null): BucketHistogramStat(source)

Create an independent accumulator at the configured baseline. A null concurrency preserves this accumulator's mode; a non-null value overrides it. Modality subtypes narrow the return type to preserve the input shape.

merge

open override fun merge(values: SparseHistogramResult, timestampNanos: Long = currentTimeNanos())(source)

Fold a compatible snapshot values into this accumulator at timestampNanos. Implementations document whether the combine is exact or approximate and which state the snapshot omits. The source accumulator is unaffected.

Time-dependent statistics, such as windows, place the snapshot at timestampNanos, which must share the clock the caller uses for updates and reads. Time-independent statistics ignore it.

read

open override fun read(timestampNanos: Long = currentTimeNanos()): SparseHistogramResult(source)

Return the current result evaluated at timestampNanos. Time-independent statistics ignore the timestamp. Reading does not add an observation.

Snapshot consistency depends on the implementation's synchronisation. Locks protect coupled state under Concurrency.Strict and Concurrency.HighWrite; independently updated cells and JVM striped adders can still yield a best-effort snapshot. Concurrency.Relaxed permits drift across coupled cells.

reset

open override fun reset()(source)

Restore the configured baseline, including any prior seed. Preserves the configuration and concurrency.

update

open fun update(value: Double, weight: Double = 1.0)

Record value with weight at the current monotonic time.

open override fun update(value: Double, timestampNanos: Long, weight: Double = 1.0)

Record value with weight at timestampNanos.

validateMerge

open fun validateMerge(values: SparseHistogramResult)

Validate values for merge without changing accumulator state. Containers validate every child before merging any of them. Successful validation checks compatibility; it does not make a concurrent merge transactional.

update

open override fun update(value: Double, timestampNanos: Long, weight: Double = 1.0)(source)

Record value with weight at timestampNanos.