interval-align 0.1.0

Align timestamped samples onto intervals: time-weighted means, sums, or counter deltas, with coverage and no interpolation.
Documentation
  • Coverage
  • 100%
    36 out of 36 items documented3 out of 13 items with examples
  • Size
  • Source code size: 37.7 kB This is the summed size of all the files inside the crates.io package for this release.
  • Documentation size: 403.6 kB This is the summed size of all files generated by rustdoc for all configured targets
  • Ø build duration
  • this release: 6s Average build duration of successful builds.
  • all releases: 6s Average build duration of successful builds in releases after 2024-10-23.
  • Links
  • Homepage
  • Volt-Labs-Technology/interval-align
    0 0 13
  • crates.io
  • Dependencies
  • Versions
  • Owners
  • scull7

interval-align

What this is

A small, dependency-light Rust crate that aligns timestamped samples onto intervals and returns one number per metric: a time-weighted mean for power-like metrics, a sum for energy rows, or a rise for monotone counters — each with a coverage figure and nothing interpolated.

Who it is for

Rust programs that ingest metering or monitoring feeds at irregular rates and need to summarize them over fixed intervals without inventing data.

How to use it

Add the crate to a Rust project:

cargo add interval-align

That writes this line into Cargo.toml:

interval-align = "0.1.0"

Minimal example (synthetic data):

use std::collections::BTreeMap;

use interval_align::{align, Duration, Interval, Kind, Reading, Rules, Sample};

// Timestamps are seconds since the Unix epoch, as `i64`.
let start = 1_772_949_600;
let interval = Interval {
    start,
    length: Duration::seconds(900).expect("a positive length"),
};

// Fifteen minutes is only this example's length. Any positive length works.
let samples = [
    Sample::new("hall.kw", start, 100.0, Kind::Power).expect("finite"),
    Sample::new("hall.kw", start + 300, 200.0, Kind::Power).expect("finite"),
    Sample::new("hall.kw", start + 720, 100.0, Kind::Power).expect("finite"),
];

let readings: BTreeMap<String, Reading> =
    align(&samples, interval, &Rules { min_coverage_pct: 80 }).expect("all samples inside");

// hall.kw was held at 100 for five minutes, then 200 for seven, then 100
// until the end. The time-weighted mean is 158.333… over 80 % coverage.
assert!(matches!(
    readings["hall.kw"],
    Reading::Value { coverage_pct: 80, .. }
));

The rules in one place:

  • A sample declares its Kind; nothing is inferred from a unit string. Kind::Power is the interval's time-weighted mean (each sample held until the next; the last opens no span), Kind::Energy is the sum of the values inside the interval, and Kind::Counter is the last value minus the first.
  • Coverage for power and counter metrics is the span from the first sample to the last, over the interval's length, as a percent. Fewer than two samples means zero coverage. One energy sample covers the whole interval.
  • Coverage below the configured minimum, or zero coverage, yields Reading::Missing { coverage_pct } and no value. Nothing is interpolated or filled, ever.
  • Two samples of one metric at one instant is a replay: the later one in caller order wins, and the discard is counted in duplicates.
  • A sample outside the interval, or a counter that falls, is a typed error rather than a row quietly dropped.
  • A metric with no samples at all is absent from the returned map rather than Missing. The map is a BTreeMap, so the same input always yields the same iteration order.

What it deliberately does not do

This crate deliberately does not interpolate between samples, convert time zones, read files or the network, or decide what a good coverage threshold is — a caller supplies min_coverage_pct, and its own meaning of a local day. Timestamps are plain seconds since the Unix epoch as i64; the crate does no time-zone work, never reads a clock, and treats fifteen minutes as an example interval length, not a built-in.

Version 0.x: the API may change before 1.0.