Skip to main content

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}