Expand description
Align timestamped samples onto intervals.
Feeds arrive at whatever rate they like and the caller works on intervals of its own choosing. This crate is the step between, and it is a pure calculation: it reads no clock, opens no file, and takes the interval it is aligning as an argument.
§The rules
A metric’s Kind says how its samples become one number:
Kind::Poweris the interval’s time-weighted mean. Each sample is held until the next one and weighted by the span it held; the last sample opens no span and carries no weight. Nothing is back-filled before the first sample either.Kind::Energyis the sum of the values inside the interval. One energy sample covers the whole interval; zero energy samples leave the metric absent from the result rather than missing from it.Kind::Counteris the rise from the first sample to the last. A counter that falls isAlignError::CounterWentBackwards, not an arithmetic guess.
§Coverage is the sampled span
A feed does not declare its rate, so “how much of this interval did we
see?” cannot be a fraction of an expected row count. For power and counter
metrics it is the span from the first sample to the last, over the
interval’s length; fewer than two samples span nothing, so coverage is
zero. A metric whose coverage is below the configured minimum, or whose
coverage is zero, is Reading::Missing carrying the coverage it had and
no value.
§Nothing is interpolated
A gap is reported as a gap. The alternative is a plausible number nobody can tell from a measured one.
§What a duplicate is
Two samples of one metric at one instant is a feed that replayed, not a
measurement that happened twice. The later one in caller order wins and
the discard is counted in the reading’s duplicates.
§Timestamps are plain seconds
A Timestamp is seconds since the Unix epoch as i64. This crate
does no time-zone work: it never reads a wall clock and never converts
between zones. Whatever a local day means is the caller’s business, and a
day whose clock moved still walks as whole intervals in UTC seconds.
Structs§
- Duration
- A positive length in seconds.
- Interval
- A half-open window of time:
[start, start + length). - Rules
- What alignment is allowed to accept.
- Sample
- One measurement of one metric at one instant.
Enums§
- Align
Error - What alignment refuses.
- Kind
- How one metric’s samples become one number for one interval.
- Reading
- One metric’s verdict for one interval.
Functions§
- align
- Samples of one interval, as one number per metric.
Type Aliases§
- Timestamp
- Seconds since the Unix epoch.