Struct MeasurementHistogram 

pub struct MeasurementHistogram<const N: usize> { /* private fields */ }

Canonical shared arithmetic for local diagnostic summaries and distributions.

Re-exported so callers can name returned summaries without selecting a separate Metrics dependency. This is the shared type, with no local wrapper or arithmetic. Fixed-size histogram of observations in one consumer-selected unit.

N strictly increasing inclusive upper bounds define N disjoint buckets. The first bucket includes zero; later buckets exclude the preceding bound. Values above the last bound go into a separate overflow bucket. With no bounds, every observation goes into overflow. A final bound of u64::MAX is valid and leaves overflow empty.

Each observation updates one bucket and the accompanying MeasurementSummary. Bucket counts saturate independently at u64::MAX. Treat a count at that value as unavailable for exact arithmetic, even when reached exactly. Unsaturated bucket counts remain useful after the summary’s total saturates. Saturation can prevent bucket counts from summing to the summary’s sample count. Buckets describe ranges, not exact percentiles.

Storage is fixed arrays, one overflow count and one summary, with no heap allocation. Recording searches at most N bounds. Consumers choose bounds, units, sample admission, identity and reset boundaries. Bounds are immutable after construction; cumulative reporting and persistence remain consumer-owned.

use ic_metrics::MeasurementHistogram;

let mut histogram = MeasurementHistogram::new([10, 100])?;
for value in [0, 10, 11, 101] {
    histogram.record(value);
}
assert_eq!(histogram.bucket_counts(), &[2, 1]);
assert_eq!(histogram.overflow(), 1);
assert_eq!(histogram.summary().samples(), 4);

Implementations

impl<const N: usize> MeasurementHistogram<N>

pub const fn new( upper_bounds: [u64; N], ) -> Result<MeasurementHistogram<N>, HistogramBoundsError>

Construct an empty histogram with inclusive upper bounds.

Bounds and observations must use the same unit. A bound of zero and an empty bounds array are valid.

Errors

Returns HistogramBoundsError for the first duplicate or descending bound. The error identifies the right-hand bound in that pair.

pub const fn record(&mut self, value: u64)

Record one completed observation, including zero.

Updates the summary and exactly one disjoint bucket. Every observation must use the same unit as the bounds and earlier observations.

pub const fn upper_bounds(&self) -> &[u64; N]

Immutable inclusive upper bounds corresponding to Self::bucket_counts.

pub const fn bucket_counts(&self) -> &[u64; N]

Disjoint bucket counts, each saturating independently at u64::MAX.

These exclude overflow and are not cumulative counts.

pub const fn overflow(&self) -> u64

Count above the last bound, saturating independently at u64::MAX.

With no bounds, this counts all observations.

pub const fn summary(&self) -> MeasurementSummary

Summary of all observations, including overflow.

Trait Implementations

impl<const N: usize> Clone for MeasurementHistogram<N>

fn clone(&self) -> MeasurementHistogram<N>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<const N: usize> Copy for MeasurementHistogram<N>

impl<const N: usize> Debug for MeasurementHistogram<N>

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl<const N: usize> Eq for MeasurementHistogram<N>

impl<const N: usize> PartialEq for MeasurementHistogram<N>

fn eq(&self, other: &MeasurementHistogram<N>) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl<const N: usize> StructuralPartialEq for MeasurementHistogram<N>