interval_align/lib.rs
1//! Align timestamped samples onto intervals.
2//!
3//! Feeds arrive at whatever rate they like and the caller works on intervals
4//! of its own choosing. This crate is the step between, and it is a pure
5//! calculation: it reads no clock, opens no file, and takes the interval it
6//! is aligning as an argument.
7//!
8//! # The rules
9//!
10//! A metric's [`Kind`] says how its samples become one number:
11//!
12//! * [`Kind::Power`] is the interval's **time-weighted mean**. Each sample is
13//! held until the next one and weighted by the span it held; the last
14//! sample opens no span and carries no weight. Nothing is back-filled
15//! before the first sample either.
16//! * [`Kind::Energy`] is the **sum** of the values inside the interval. One
17//! energy sample covers the whole interval; zero energy samples leave the
18//! metric absent from the result rather than missing from it.
19//! * [`Kind::Counter`] is the **rise** from the first sample to the last. A
20//! counter that falls is [`AlignError::CounterWentBackwards`], not an
21//! arithmetic guess.
22//!
23//! # Coverage is the sampled span
24//!
25//! A feed does not declare its rate, so "how much of this interval did we
26//! see?" cannot be a fraction of an expected row count. For power and counter
27//! metrics it is the span from the first sample to the last, over the
28//! interval's length; fewer than two samples span nothing, so coverage is
29//! zero. A metric whose coverage is below the configured minimum, or whose
30//! coverage is zero, is [`Reading::Missing`] carrying the coverage it had and
31//! **no value**.
32//!
33//! # Nothing is interpolated
34//!
35//! A gap is reported as a gap. The alternative is a plausible number nobody
36//! can tell from a measured one.
37//!
38//! # What a duplicate is
39//!
40//! Two samples of one metric at one instant is a feed that replayed, not a
41//! measurement that happened twice. The later one in caller order wins and
42//! the discard is counted in the reading's `duplicates`.
43//!
44//! # Timestamps are plain seconds
45//!
46//! A [`Timestamp`] is seconds since the Unix epoch as `i64`. **This crate
47//! does no time-zone work**: it never reads a wall clock and never converts
48//! between zones. Whatever a local day means is the caller's business, and a
49//! day whose clock moved still walks as whole intervals in UTC seconds.
50
51#![deny(missing_docs)]
52
53use std::collections::BTreeMap;
54
55/// Seconds since the Unix epoch.
56pub type Timestamp = i64;
57
58/// How one metric's samples become one number for one interval.
59///
60/// The kind is carried on each [`Sample`] and is never inferred from a unit
61/// string or from the shape of the data.
62#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
63pub enum Kind {
64 /// A power-like metric: the interval's time-weighted mean.
65 Power,
66 /// An energy row already attributed to an instant inside the interval:
67 /// the sum.
68 Energy,
69 /// A monotone cumulative counter: the rise from the first sample to the
70 /// last inside the interval.
71 Counter,
72}
73
74/// One measurement of one metric at one instant.
75///
76/// Build one with [`Sample::new`], which refuses a non-finite value. The
77/// fields are public, so a caller can also write a `Sample` literal directly;
78/// in that case the finite-value check is the caller's to have done.
79#[derive(Debug, Clone, PartialEq)]
80pub struct Sample {
81 /// The metric this sample belongs to.
82 pub metric: String,
83 /// Seconds since the Unix epoch.
84 pub at: Timestamp,
85 /// The measured value.
86 pub value: f64,
87 /// How this sample aggregates.
88 pub kind: Kind,
89}
90
91impl Sample {
92 /// One sample. Refuses a non-finite value.
93 ///
94 /// ```
95 /// use interval_align::{Kind, Sample};
96 ///
97 /// let sample = Sample::new("hall.kw", 1_772_949_600, 100.0, Kind::Power);
98 /// assert!(sample.is_some());
99 /// assert!(Sample::new("hall.kw", 1_772_949_600, f64::NAN, Kind::Power).is_none());
100 /// ```
101 #[must_use]
102 pub fn new(metric: impl Into<String>, at: Timestamp, value: f64, kind: Kind) -> Option<Self> {
103 if value.is_finite() {
104 Some(Self {
105 metric: metric.into(),
106 at,
107 value,
108 kind,
109 })
110 } else {
111 None
112 }
113 }
114}
115
116/// A positive length in seconds.
117///
118/// An interval has to have one, so the constructor refuses zero. The fields
119/// of [`Interval`] are public, so a caller can also write the struct literal
120/// directly; in that case the positive-length check is the caller's to have
121/// done.
122#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
123pub struct Duration {
124 seconds: u64,
125}
126
127impl Duration {
128 /// A positive length in seconds. Refuses zero.
129 ///
130 /// ```
131 /// use interval_align::Duration;
132 ///
133 /// assert!(Duration::seconds(900).is_some());
134 /// assert!(Duration::seconds(0).is_none());
135 /// ```
136 #[must_use]
137 pub fn seconds(seconds: u64) -> Option<Self> {
138 (seconds > 0).then_some(Self { seconds })
139 }
140
141 /// The length in seconds.
142 #[must_use]
143 pub const fn as_secs(&self) -> u64 {
144 self.seconds
145 }
146}
147
148/// A half-open window of time: `[start, start + length)`.
149///
150/// Any length is allowed; fifteen minutes is only this documentation's
151/// example. Start and end are [`Timestamp`]s, seconds since the Unix epoch.
152#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
153pub struct Interval {
154 /// The first second of the interval.
155 pub start: Timestamp,
156 /// How long the interval is.
157 pub length: Duration,
158}
159
160impl Interval {
161 /// The first second past the interval, saturating at `i64::MAX`.
162 #[must_use]
163 pub const fn end(&self) -> Timestamp {
164 self.start.saturating_add(self.length.as_secs() as i64)
165 }
166
167 /// Whether `at` lies inside the interval: `start <= at < end`.
168 #[must_use]
169 pub const fn contains(&self, at: Timestamp) -> bool {
170 at >= self.start && at < self.end()
171 }
172}
173
174/// What alignment is allowed to accept.
175#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
176pub struct Rules {
177 /// The minimum coverage a metric needs before its number is used.
178 pub min_coverage_pct: u8,
179}
180
181/// One metric's verdict for one interval.
182///
183/// [`Reading::Missing`] carries no value on purpose. There is no field a
184/// caller could read "anyway", which is what keeps a thin interval out of a
185/// downstream number.
186#[derive(Debug, Clone, Copy, PartialEq)]
187pub enum Reading {
188 /// The metric was measured well enough to use.
189 Value {
190 /// The aggregated value.
191 value: f64,
192 /// How much of the interval this number was measured over, 0-100.
193 coverage_pct: u8,
194 /// How many duplicate samples were discarded reaching it.
195 duplicates: u32,
196 },
197 /// The metric was sampled too thinly. Nothing is filled in.
198 Missing {
199 /// How much of the interval was seen, 0-100.
200 coverage_pct: u8,
201 },
202}
203
204/// What alignment refuses.
205#[derive(Debug, Clone, PartialEq, thiserror::Error)]
206pub enum AlignError {
207 /// A sample belongs to another interval. This is a bug in the caller,
208 /// not a row worth dropping, so it is a typed error rather than a silent
209 /// skip.
210 #[error("sample of {metric} at {at} is not in the interval being aligned")]
211 SampleOutsideInterval {
212 /// The metric of the offending sample.
213 metric: String,
214 /// The offending sample's instant, seconds since the Unix epoch.
215 at: Timestamp,
216 },
217 /// A counter fell between its first and last sample. A meter that rolled
218 /// over or reset needs a person, not a guess.
219 #[error("counter {metric} went backwards inside one interval")]
220 CounterWentBackwards {
221 /// The metric whose counter fell.
222 metric: String,
223 },
224}
225
226/// Samples of one interval, as one number per metric.
227///
228/// A metric with no sample at all is absent from the map rather than
229/// `Missing`: nothing was expected of it here, and an expectation is the
230/// caller's to hold. The map is a [`BTreeMap`], so the same input always
231/// yields the same iteration order.
232///
233/// A metric's kind is taken from its last sample in caller order; a caller
234/// that mixes kinds for one metric is a caller to fix.
235///
236/// # Errors
237///
238/// Returns [`AlignError::SampleOutsideInterval`] when a sample's timestamp
239/// lies outside `[interval.start, interval.end)`, and
240/// [`AlignError::CounterWentBackwards`] when a counter metric that passed the
241/// coverage gate falls.
242///
243/// ```
244/// use interval_align::{align, Duration, Interval, Kind, Reading, Rules, Sample};
245///
246/// // Synthetic example data.
247/// let start = 1_772_949_600;
248/// let interval = Interval { start, length: Duration::seconds(900).expect("positive") };
249/// let samples = [
250/// Sample::new("hall.kw", start, 100.0, Kind::Power).expect("finite"),
251/// Sample::new("hall.kw", start + 300, 200.0, Kind::Power).expect("finite"),
252/// Sample::new("hall.kw", start + 720, 100.0, Kind::Power).expect("finite"),
253/// ];
254/// let aligned = align(&samples, interval, &Rules { min_coverage_pct: 80 })
255/// .expect("all samples inside the interval");
256/// assert!(matches!(aligned["hall.kw"], Reading::Value { coverage_pct: 80, .. }));
257/// ```
258pub fn align(
259 samples: &[Sample],
260 interval: Interval,
261 rules: &Rules,
262) -> Result<BTreeMap<String, Reading>, AlignError> {
263 for sample in samples {
264 if !interval.contains(sample.at) {
265 return Err(AlignError::SampleOutsideInterval {
266 metric: sample.metric.clone(),
267 at: sample.at,
268 });
269 }
270 }
271
272 // One point per (metric, instant), the later one in caller order winning.
273 // A `BTreeMap` keyed by (metric, instant) keeps each metric's survivors
274 // in time order for free, which is what the aggregations below need.
275 let mut points: BTreeMap<(String, Timestamp), f64> = BTreeMap::new();
276 let mut kind_by_metric: BTreeMap<String, Kind> = BTreeMap::new();
277 let mut brought: BTreeMap<String, u32> = BTreeMap::new();
278 for sample in samples {
279 points.insert((sample.metric.clone(), sample.at), sample.value);
280 kind_by_metric.insert(sample.metric.clone(), sample.kind);
281 *brought.entry(sample.metric.clone()).or_default() += 1;
282 }
283
284 let mut series: BTreeMap<String, Vec<(Timestamp, f64)>> = BTreeMap::new();
285 for ((metric, at), value) in points {
286 series.entry(metric).or_default().push((at, value));
287 }
288
289 let mut readings = BTreeMap::new();
290 for (metric, points) in series {
291 let duplicates = brought[&metric] - points.len() as u32;
292 let kind = kind_by_metric[&metric];
293 let reading = reading_of(
294 &metric,
295 kind,
296 &points,
297 interval,
298 rules.min_coverage_pct,
299 duplicates,
300 )?;
301 readings.insert(metric, reading);
302 }
303 Ok(readings)
304}
305
306/// One metric's verdict: enough coverage and a number, or how little there
307/// was.
308///
309/// The duplicates are already gone; `duplicates` says how many were. The
310/// coverage gate comes before the aggregation, so a counter that falls is
311/// only a typed error when its coverage passed the gate in the first place.
312fn reading_of(
313 metric: &str,
314 kind: Kind,
315 points: &[(Timestamp, f64)],
316 interval: Interval,
317 min_coverage_pct: u8,
318 duplicates: u32,
319) -> Result<Reading, AlignError> {
320 let coverage_pct = coverage_pct_of(points, kind, interval);
321 if coverage_pct == 0 || coverage_pct < min_coverage_pct {
322 return Ok(Reading::Missing { coverage_pct });
323 }
324 let value = match kind {
325 Kind::Energy => points.iter().map(|&(_, value)| value).sum(),
326 Kind::Power => time_weighted_mean(points),
327 Kind::Counter => {
328 let first = points[0].1;
329 let last = points[points.len() - 1].1;
330 if last < first {
331 return Err(AlignError::CounterWentBackwards {
332 metric: metric.to_owned(),
333 });
334 }
335 last - first
336 }
337 };
338 Ok(Reading::Value {
339 value,
340 coverage_pct,
341 duplicates,
342 })
343}
344
345/// How much of the interval these points measured, as a percent 0-100.
346///
347/// An energy feed is different in kind: a row stamped once inside the
348/// interval *is* the interval's energy, and there is no gap between rows to
349/// measure, so one sample covers the interval. A power or counter metric
350/// measures a span, so it is the span from the first sample to the last over
351/// the interval's length; fewer than two samples span nothing.
352fn coverage_pct_of(points: &[(Timestamp, f64)], kind: Kind, interval: Interval) -> u8 {
353 match kind {
354 Kind::Energy => 100,
355 Kind::Power | Kind::Counter => match (points.first(), points.last()) {
356 (Some(&(first, _)), Some(&(last, _))) => {
357 let span = (last - first) as u128;
358 let length = interval.length.as_secs() as u128;
359 (span * 100 / length) as u8
360 }
361 _ => 0,
362 },
363 }
364}
365
366/// Each sample weighted by the span until the next one.
367///
368/// The last sample opens no span and so carries no weight. Callers reach
369/// this only when the span is non-zero, because zero coverage is `Missing`.
370fn time_weighted_mean(points: &[(Timestamp, f64)]) -> f64 {
371 let weighted: f64 = points
372 .windows(2)
373 .map(|pair| pair[0].1 * (pair[1].0 - pair[0].0) as f64)
374 .sum();
375 let span = (points[points.len() - 1].0 - points[0].0) as f64;
376 weighted / span
377}
378
379#[cfg(test)]
380mod tests {
381 use super::*;
382
383 // Synthetic instants; nothing here reads a clock.
384 const START: Timestamp = 1_772_949_600;
385
386 fn duration(secs: u64) -> Duration {
387 Duration::seconds(secs).expect("a positive length")
388 }
389
390 fn sample(metric: &str, offset: i64, value: f64, kind: Kind) -> Sample {
391 Sample::new(metric, START + offset, value, kind).expect("a finite value")
392 }
393
394 #[test]
395 fn a_sample_refuses_a_non_finite_value() {
396 assert!(Sample::new("hall.kw", START, f64::NAN, Kind::Power).is_none());
397 assert!(Sample::new("hall.kw", START, f64::INFINITY, Kind::Power).is_none());
398 assert!(sample("hall.kw", 0, 1.0, Kind::Power).value == 1.0);
399 }
400
401 #[test]
402 fn a_duration_refuses_zero() {
403 assert!(Duration::seconds(0).is_none());
404 assert_eq!(duration(900).as_secs(), 900);
405 }
406
407 #[test]
408 fn an_interval_contains_its_start_but_not_its_end() {
409 let interval = Interval {
410 start: START,
411 length: duration(900),
412 };
413 assert!(interval.contains(START));
414 assert!(interval.contains(START + 899));
415 assert!(!interval.contains(START + 900));
416 assert_eq!(interval.end(), START + 900);
417 }
418
419 #[test]
420 fn an_interval_end_saturates() {
421 let interval = Interval {
422 start: i64::MAX - 10,
423 length: duration(900),
424 };
425 assert_eq!(interval.end(), i64::MAX);
426 }
427
428 #[test]
429 fn empty_input_aligns_to_an_empty_map() {
430 let interval = Interval {
431 start: START,
432 length: duration(900),
433 };
434 let aligned = align(
435 &[],
436 interval,
437 &Rules {
438 min_coverage_pct: 80,
439 },
440 )
441 .expect("empty aligns");
442 assert!(aligned.is_empty());
443 }
444}