Module counter 

Increments of a cumulative counter, each classified by what explains it.

A cumulative counter – an energy, gas or water meter’s register, an hour meter, a production or byte counter – is read at increasing times, and what is wanted is how much it advanced between readings. A reading below the one before it has more than one explanation: the register passed its maximum and started again from 0 (a wrap), it was reset or replaced, or the reading is wrong. These functions do not pick one by assumption. Each pair of neighbouring readings is classified:

• IncrementKind::Normal – the value did not fall; the increase is the difference.
• IncrementKind::Declared – the caller declared a reset or a replacement inside the pair (Discontinuity); the increase is counted from the new start value (plus, when the old register’s last value is given, what it advanced before the change).
• IncrementKind::Wrap – the value fell and a known modulus (the value at which the register returns to 0) explains it: the increase is modulus − previous + next. With max_rate, a wrap is accepted only when that increase is one the counter can make in the time between the readings.
• IncrementKind::Unexplained – the value fell and nothing given explains it: the increase is None, not a guess.

Monitoring systems usually read every fall as a reset and count from 0 (Prometheus’ increase() and rate()); that is right for process counters that restart with their process, and wrong for a meter whose readings settle a bill. Classifying, rather than assuming, leaves the choice to the caller, who can see what was not explained.

counter_totals sums the increments over consecutive intervals (a day, a quarter of an hour), with the number of pairs left unexplained in each.

References

• Prometheus documentation, “Query functions”: increase(), rate() – counter resets are compensated by assuming a restart from 0.
• IEC 62056-6-2 (DLMS/COSEM), register objects with a scaler and a wrap-around value – the modulus here.

Structs

CounterIncrement

How much the counter advanced between two neighbouring readings.

CounterOptions

The settings of counter_increments.

CounterTotal

The increments that end in one interval [start, end).

Discontinuity

A reset or replacement of the counter, declared by the caller.

Enums

CounterError

Why readings, settings or intervals were refused.

IncrementKind

What explains an increment (see the module docs).

Functions

counter_increments

The increment between each pair of neighbouring readings, classified.

counter_totals

The increments summed over consecutive intervals [edges[j], edges[j+1]).