ic-metrics 0.8.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
120
121
122
123
124
125

use crate::MeasurementAggregate;

use super::{MeasurementMeanError, MeasurementSummary};

#[test]
fn summary_mean_preserves_recording_and_saturation_contracts() {
    let mut summary = MeasurementSummary::EMPTY;
    assert_eq!(summary.mean(), Ok(None));
    summary.record(0);
    assert_eq!(summary.mean(), Ok(Some(0)));
    summary.record(9);
    assert_eq!(summary.mean(), Ok(Some(4)));
    summary.record(u64::MAX - 9);
    assert_eq!(summary.total(), u128::from(u64::MAX));
    assert_eq!(summary.mean(), Ok(Some(u128::from(u64::MAX) / 3)));
    assert!(!summary.aggregate().total_saturated());
    summary.record(1);
    assert_eq!(summary.mean(), Ok(Some((u128::from(u64::MAX) + 1) / 4)));
    assert!(!summary.aggregate().total_saturated());
    assert_eq!(summary.latest(), Some(1));
    let mut saturated_count =
        MeasurementSummary::from_parts(maximum_zero_count(), Some(0)).unwrap();
    assert_eq!(saturated_count.mean(), Ok(Some(0)));
    saturated_count.record(9);
    assert_eq!(
        saturated_count.mean(),
        Err(MeasurementMeanError::SaturatedSamples)
    );
}

#[test]
fn summary_means_are_available_in_constant_evaluation() {
    const PROJECTIONS: (MeasurementSummary, Option<u128>, Option<u128>) = {
        let mut summary = MeasurementSummary::EMPTY;
        summary.record(9);
        summary.record(0);
        let Ok(mean) = summary.mean() else {
            panic!("exact mean")
        };
        let Ok(scaled) = summary.scaled_mean(10) else {
            panic!("exact scaled mean")
        };
        (summary, mean, scaled)
    };
    assert_eq!((PROJECTIONS.1, PROJECTIONS.2), (Some(4), Some(45)));
    assert_eq!(PROJECTIONS.0.samples(), 2);
    assert_eq!(PROJECTIONS.0.total(), 9);
    assert_eq!(PROJECTIONS.0.latest(), Some(0));
    assert_eq!(PROJECTIONS.0.maximum(), Some(9));
    let mut summary = MeasurementSummary::EMPTY;
    assert_eq!(summary.scaled_mean(10), Ok(None));
    summary.record(0);
    assert_eq!(summary.scaled_mean(10), Ok(Some(0)));
    summary = MeasurementSummary::from_parts(maximum_zero_count(), Some(0)).unwrap();
    assert_eq!(summary.scaled_mean(u64::MAX), Ok(Some(0)));
    summary.record(0);
    assert_eq!(
        summary.scaled_mean(0),
        Err(MeasurementMeanError::SaturatedSamples)
    );
}

#[test]
fn empty_and_measured_zero_are_distinct() {
    let mut summary = MeasurementSummary::EMPTY;
    assert_eq!(summary, MeasurementSummary::default());
    assert_eq!(summary.samples(), 0);
    assert_eq!(summary.total(), 0);
    assert_eq!(summary.latest(), None);
    assert_eq!(summary.maximum(), None);

    summary.record(0);
    assert_eq!(summary.samples(), 1);
    assert_eq!(summary.total(), 0);
    assert_eq!(summary.latest(), Some(0));
    assert_eq!(summary.maximum(), Some(0));
}

#[test]
fn latest_and_maximum_follow_individual_observations() {
    let mut summary = MeasurementSummary::EMPTY;
    for value in [7, 12, 3, 0] {
        summary.record(value);
    }
    assert_eq!(summary.samples(), 4);
    assert_eq!(summary.total(), 22);
    assert_eq!(summary.latest(), Some(0));
    assert_eq!(summary.maximum(), Some(12));
}

#[test]
fn total_saturation_preserves_count_latest_and_maximum() {
    let mut aggregate = MeasurementAggregate::EMPTY;
    for _ in 0..64 {
        aggregate.merge(aggregate);
        aggregate.record(u64::MAX);
    }
    aggregate.record(u64::MAX);
    aggregate.record(u64::MAX);
    let mut summary = MeasurementSummary::from_parts(aggregate, Some(u64::MAX)).unwrap();
    assert_eq!(summary.total(), u128::MAX);
    assert!(!summary.aggregate().total_saturated());
    summary.record(1);
    summary.record(2);
    assert_eq!(summary.samples(), u64::MAX);
    assert_eq!(summary.total(), u128::MAX);
    assert!(summary.aggregate().samples_saturated());
    assert!(summary.aggregate().total_saturated());
    assert_eq!(summary.latest(), Some(2));
    assert_eq!(summary.maximum(), Some(u64::MAX));
}

#[test]
fn count_saturation_does_not_freeze_other_observations() {
    let mut summary = MeasurementSummary::from_parts(maximum_zero_count(), Some(0)).unwrap();
    summary.record(4);
    assert_eq!(summary.samples(), u64::MAX);
    assert_eq!(summary.total(), 4);
    assert_eq!(summary.latest(), Some(4));
    assert_eq!(summary.maximum(), Some(4));
}

fn maximum_zero_count() -> MeasurementAggregate {
    MeasurementAggregate::from_parts(u64::MAX, 0, Some(0), false, false).unwrap()
}