ic-metrics 0.9.2

Allocation-free, dependency-free measurement arithmetic
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119

//! Saturating arithmetic without sampling or attribution policy.

use crate::{MeasurementAggregate, MeasurementMeanError, MeasurementStateError};

#[cfg(test)]
mod tests;

/// Ordered observations with a mergeable aggregate and a separate latest value.
///
/// Count and total saturate independently, tracking actual overflow. An exactly
/// reached numeric cap remains exact; inspect the aggregate's overflow flags
/// before using raw counts/totals for exact arithmetic. Latest and maximum remain
/// individual observations after overflow. Empty and measured zero are distinct.
/// Consumers own units, identity, ordering and reset boundaries.
#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
pub struct MeasurementSummary {
    aggregate: MeasurementAggregate,
    latest: u64,
}

impl MeasurementSummary {
    /// Restore an admitted aggregate and its latest ordered observation.
    ///
    /// The caller establishes identity and ordering; this validates numeric fields.
    ///
    /// # Errors
    /// Rejects absent/nonempty latest values, values above the maximum and
    /// observations inconsistent with the aggregate's exact total. With an exact
    /// count, the other observations cannot contribute more than their maximum.
    pub const fn from_parts(
        aggregate: MeasurementAggregate,
        latest: Option<u64>,
    ) -> Result<Self, MeasurementStateError> {
        if aggregate.samples() == 0 {
            return if latest.is_none() {
                Ok(Self::EMPTY)
            } else {
                Err(MeasurementStateError::InvalidLatest)
            };
        }
        let (Some(latest), Some(maximum)) = (latest, aggregate.maximum()) else {
            return Err(MeasurementStateError::InvalidLatest);
        };
        if latest > maximum
            || (latest < maximum && aggregate.total() < latest as u128 + maximum as u128)
            || (!aggregate.samples_overflowed()
                && aggregate.total()
                    > (aggregate.samples() - 1) as u128 * maximum as u128 + latest as u128)
        {
            return Err(MeasurementStateError::InvalidLatest);
        }
        Ok(Self { aggregate, latest })
    }

    /// Empty summary, with no latest or maximum observation.
    pub const EMPTY: Self = Self {
        aggregate: MeasurementAggregate::EMPTY,
        latest: 0,
    };

    /// Record one completed observation, including zero, in the existing unit.
    pub const fn record(&mut self, value: u64) {
        self.aggregate.record(value);
        self.latest = value;
    }

    /// Mergeable count/total/maximum snapshot without observation ordering.
    #[must_use]
    pub const fn aggregate(self) -> MeasurementAggregate {
        self.aggregate
    }

    /// Sample count, clipped at `u64::MAX`; overflow is in [`Self::aggregate`].
    #[must_use]
    pub const fn samples(self) -> u64 {
        self.aggregate.samples()
    }

    /// Observation total, clipped at `u128::MAX`; overflow is in [`Self::aggregate`].
    #[must_use]
    pub const fn total(self) -> u128 {
        self.aggregate.total()
    }

    /// Floor-rounded mean, or `None` when empty. An exactly reached cap is valid.
    ///
    /// # Errors
    /// Returns [`MeasurementMeanError::SampleCountOverflow`] on actual count overflow.
    pub const fn mean(self) -> Result<Option<u128>, MeasurementMeanError> {
        self.aggregate.mean()
    }

    /// Compute `floor(total * scale / samples)`, retaining fractional information.
    ///
    /// Uses the aggregate's checked projection; a scale of ten reports tenths.
    /// Empty remains `None`, and scale zero does not conceal actual overflow.
    ///
    /// # Errors
    /// Returns [`MeasurementMeanError::SampleCountOverflow`] on actual count overflow.
    pub const fn scaled_mean(self, scale: u64) -> Result<Option<u128>, MeasurementMeanError> {
        self.aggregate.scaled_mean(scale)
    }

    /// Latest observation, or `None` when empty. Summaries cannot be merged.
    #[must_use]
    pub const fn latest(self) -> Option<u64> {
        if self.samples() == 0 {
            None
        } else {
            Some(self.latest)
        }
    }

    /// Largest observation, or `None` when empty, including after overflow.
    #[must_use]
    pub const fn maximum(self) -> Option<u64> {
        self.aggregate.maximum()
    }
}