|
| 1 | +//! Module implementing an Open Metrics histogram. |
| 2 | +//! |
| 3 | +//! See [`Summary`] for details. |
| 4 | +
|
| 5 | +use super::{MetricType, TypedMetric}; |
| 6 | +//use owning_ref::OwningRef; |
| 7 | +//use std::iter::{self, once}; |
| 8 | +use std::sync::{Arc, Mutex}; |
| 9 | +use std::time::{Duration, Instant}; |
| 10 | + |
| 11 | +use quantiles::ckms::CKMS; |
| 12 | + |
| 13 | +/// Open Metrics [`Summary`] to measure distributions of discrete events. |
| 14 | +#[derive(Debug)] |
| 15 | +pub struct Summary { |
| 16 | + target_quantile: Vec<f64>, |
| 17 | + target_error: f64, |
| 18 | + max_age_buckets: u64, |
| 19 | + max_age_seconds: u64, |
| 20 | + stream_duration: Duration, |
| 21 | + inner: Arc<Mutex<InnerSummary>>, |
| 22 | +} |
| 23 | + |
| 24 | +impl Clone for Summary { |
| 25 | + fn clone(&self) -> Self { |
| 26 | + Summary { |
| 27 | + target_quantile: self.target_quantile.clone(), |
| 28 | + target_error: self.target_error, |
| 29 | + max_age_buckets: self.max_age_buckets, |
| 30 | + max_age_seconds: self.max_age_seconds, |
| 31 | + stream_duration: self.stream_duration, |
| 32 | + inner: self.inner.clone(), |
| 33 | + } |
| 34 | + } |
| 35 | +} |
| 36 | + |
| 37 | +#[derive(Debug)] |
| 38 | +pub(crate) struct InnerSummary { |
| 39 | + sum: f64, |
| 40 | + count: u64, |
| 41 | + quantile_streams: Vec<CKMS<f64>>, |
| 42 | + // head_stream is like a cursor which carries the index |
| 43 | + // of the stream in the quantile_streams that we want to query. |
| 44 | + head_stream_idx: u64, |
| 45 | + // timestamp at which the head_stream_idx was last rotated. |
| 46 | + last_rotated_timestamp: Instant, |
| 47 | +} |
| 48 | + |
| 49 | +impl Summary { |
| 50 | + /// Create a new [`Summary`]. |
| 51 | + pub fn new(max_age_buckets: u64, max_age_seconds: u64, target_quantile: Vec<f64>, target_error: f64) -> Self { |
| 52 | + let mut streams: Vec<CKMS<f64>> = Vec::new(); |
| 53 | + for _ in 0..max_age_buckets { |
| 54 | + streams.push(CKMS::new(target_error)); |
| 55 | + } |
| 56 | + |
| 57 | + let stream_duration = Duration::from_secs(max_age_seconds / max_age_buckets); |
| 58 | + let last_rotated_timestamp = Instant::now(); |
| 59 | + |
| 60 | + if target_quantile.iter().any(|&x| x > 1.0 || x < 0.0) { |
| 61 | + panic!("Quantile value out of range"); |
| 62 | + } |
| 63 | + |
| 64 | + Summary{ |
| 65 | + max_age_buckets, |
| 66 | + max_age_seconds, |
| 67 | + stream_duration, |
| 68 | + target_quantile, |
| 69 | + target_error, |
| 70 | + inner: Arc::new(Mutex::new(InnerSummary { |
| 71 | + sum: Default::default(), |
| 72 | + count: Default::default(), |
| 73 | + quantile_streams: streams, |
| 74 | + head_stream_idx: 0, |
| 75 | + last_rotated_timestamp, |
| 76 | + })) |
| 77 | + } |
| 78 | + } |
| 79 | + |
| 80 | + /// Observe the given value. |
| 81 | + pub fn observe(&self, v: f64) { |
| 82 | + self.rotate_buckets(); |
| 83 | + |
| 84 | + let mut inner = self.inner.lock().unwrap(); |
| 85 | + inner.sum += v; |
| 86 | + inner.count += 1; |
| 87 | + |
| 88 | + // insert quantiles into all streams/buckets. |
| 89 | + for stream in inner.quantile_streams.iter_mut() { |
| 90 | + stream.insert(v); |
| 91 | + } |
| 92 | + } |
| 93 | + |
| 94 | + /// Retrieve the values of the summary metric. |
| 95 | + pub fn get(&self) -> (f64, u64, Vec<(f64, f64)>) { |
| 96 | + self.rotate_buckets(); |
| 97 | + |
| 98 | + let inner = self.inner.lock().unwrap(); |
| 99 | + let sum = inner.sum; |
| 100 | + let count = inner.count; |
| 101 | + let mut quantile_values: Vec<(f64, f64)> = Vec::new(); |
| 102 | + |
| 103 | + for q in self.target_quantile.iter() { |
| 104 | + match inner.quantile_streams[inner.head_stream_idx as usize].query(*q) { |
| 105 | + Some((_, v)) => quantile_values.push((*q, v)), |
| 106 | + None => continue, |
| 107 | + }; |
| 108 | + } |
| 109 | + (sum, count, quantile_values) |
| 110 | + } |
| 111 | + |
| 112 | + fn rotate_buckets(&self) { |
| 113 | + let mut inner = self.inner.lock().unwrap(); |
| 114 | + if inner.last_rotated_timestamp.elapsed() >= self.stream_duration { |
| 115 | + inner.last_rotated_timestamp = Instant::now(); |
| 116 | + if inner.head_stream_idx == self.max_age_buckets { |
| 117 | + inner.head_stream_idx = 0; |
| 118 | + } else { |
| 119 | + inner.head_stream_idx += 1; |
| 120 | + } |
| 121 | + }; |
| 122 | + } |
| 123 | +} |
| 124 | + |
| 125 | +impl TypedMetric for Summary { |
| 126 | + const TYPE: MetricType = MetricType::Summary; |
| 127 | +} |
| 128 | + |
| 129 | +#[cfg(test)] |
| 130 | +mod tests { |
| 131 | + use super::*; |
| 132 | + |
| 133 | + #[test] |
| 134 | + fn summary() { |
| 135 | + let summary = Summary::new(5, 10, vec![0.5, 0.9, 0.99], 0.01); |
| 136 | + summary.observe(1.0); |
| 137 | + summary.observe(5.0); |
| 138 | + summary.observe(10.0); |
| 139 | + |
| 140 | + let (s, c, q) = summary.get(); |
| 141 | + assert_eq!(16.0, s); |
| 142 | + assert_eq!(3, c); |
| 143 | + assert_eq!(vec![(0.5, 5.0), (0.9, 10.0), (0.99, 10.0)], q); |
| 144 | + } |
| 145 | + |
| 146 | + #[test] |
| 147 | + #[should_panic(expected="Quantile value out of range")] |
| 148 | + fn summary_panic() { |
| 149 | + Summary::new(5, 10, vec![1.0, 5.0, 9.0], 0.01); |
| 150 | + } |
| 151 | +} |
0 commit comments