Skip to main content

Crate interval_align

Crate interval_align 

Source
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::Power is 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::Energy is 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::Counter is the rise from the first sample to the last. A counter that falls is AlignError::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§

AlignError
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.