monitor.counter-increase

pub fn counter_increase(samples: &[MetricSample]) -> CounterIncrease

/// The growth of a counter over the samples given.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct CounterIncrease {
    /// total growth, a drop counted as a restart from zero
    pub increase: i64,
    /// how many drops (process restarts) were seen
    pub resets: i64,
    /// increase per second x1000, half-up; null under 2 samples
    pub rate_per_second_milli: Option<i64>,
    /// at of the first sample; null when there are none
    pub first_at: Option<i64>,
    /// at of the last sample; null when there are none
    pub last_at: Option<i64>,
}

fune!(monitor.counter-increase@^1);  // then call counter_increase(…)

use super::funejson::Value;  ← the fune runtime: the JSON value the test vectors use; fune build keeps it only where a signature takes one
use super::monitor_series_window::{samples_from_value, MetricSample};  ← from monitor.series-window ^1.0.0 · built alongside by fune

/// How much a counter grew over the samples, Prometheus-style: a drop means
/// the counter restarted from zero, so the value after it is all increase. No
/// extrapolation to window edges, so the answer is a whole number.
///
/// # Panics
/// Panics on misordered samples or a negative counter value.
pub fn counter_increase(samples: &[MetricSample]) -> CounterIncrease {
    let mut increase: i64 = 0;
    let mut resets: i64 = 0;
    for (i, s) in samples.iter().enumerate() {
        if i > 0 && s.at <= samples[i - 1].at {
            panic!("samples must be in strictly ascending time order: {} follows {}", s.at, samples[i - 1].at);
        }
        if s.value < 0 {
            panic!("counter value must not be negative: {} at {}", s.value, s.at);
        }
        if i == 0 {
            continue;
        }
        let prev = samples[i - 1].value;
        if s.value >= prev {
            increase += s.value - prev;
        } else {
            resets += 1;
            increase += s.value;
        }
    }
    if samples.is_empty() {
        return CounterIncrease { increase: 0, resets: 0, rate_per_second_milli: None, first_at: None, last_at: None };
    }
    let first_at = samples[0].at;
    let last_at = samples[samples.len() - 1].at;
    let rate = if samples.len() >= 2 {
        // increase * 1000 can pass i64 for a large byte counter: i128.
        let n = increase as i128 * 1000;
        let d = (last_at - first_at) as i128;
        Some(((2 * n + d) / (2 * d)) as i64)
    } else {
        None
    };
    CounterIncrease { increase, resets, rate_per_second_milli: rate, first_at: Some(first_at), last_at: Some(last_at) }
}

fn opt(v: Option<i64>) -> Value {
    match v {
        Some(i) => Value::Int(i),
        None => Value::Null,
    }
}

pub fn counter_increase_to_value(c: &CounterIncrease) -> Value {
    Value::obj(vec![
        ("increase", Value::Int(c.increase)),
        ("resets", Value::Int(c.resets)),
        ("ratePerSecondMilli", opt(c.rate_per_second_milli)),
        ("firstAt", opt(c.first_at)),
        ("lastAt", opt(c.last_at)),
    ])
}

pub fn fune_vector(args: &[Value]) -> Value {
    counter_increase_to_value(&counter_increase(&samples_from_value(&args[0])))
}

Install

fune build

With that line in your source, in a Rust project (language rust in fune.project), fune build resolves it and its 1 dependency, pins them in fune.lock, downloads only the Rust package of each, and builds the code above into your project’s .fune/build, one readable file per capability with a header linking back here. A crate’s build.rs runs it before every compile. Or pin a range in fune.project and build in one step:

fune add monitor.counter-increase

The manifest, vectors and README with only the Rust implementation. Install it without the registry with fune add ./monitor.counter-increase-1.0.0-rust.fune, or fetch it from a terminal with fune pull monitor.counter-increase@1.0.0:rust.

The whole function, every language, is one file too: monitor.counter-increase-1.0.0.fune, 13,697 bytes, sha256 72a41bbe93f4216ce749d9f7e52d04f91f95f6126064253f5328ac742ca6b10a. It installs into a project of any language.

// fune: before monitor.counter-increase

// fune: after monitor.counter-increase

// fune: replace monitor.series-window in monitor.counter-increase

// fune: step monitor.counter-increase after <n|label>

More from the author

The rule is Prometheus's: any drop between two consecutive samples means the counter restarted from zero, so the new value is all increase. Samples 100, 160, 20, 50 grew by 60, then 20 (the restart), then 30: 110, with one reset. `last - first` would say -50.

A restart the samples never see is invisible: if a counter at 100 restarts and climbs past 100 before the next sample, the growth before the restart is lost. MetricSample more often than restarts happen.

## No extrapolation

Prometheus's `increase()` and `rate()` extrapolate from the first and last samples out to the edges of the query window, which is why they return fractional increases for a counter of whole requests. This function does not: the increase is exactly what the samples show between the first and the last, and the rate is that increase over `lastAt - firstAt`. Pass the samples of the window you care about (`monitor.series-window` picks them).

`ratePerSecondMilli` is `increase * 1000 / (lastAt - firstAt)` rounded half up, so 1.25 requests a second is 1250. It is null with fewer than two samples, where there is no interval. The multiplication is done in exact integer arithmetic (BigInt, i128), so a byte counter in the trillions still rounds correctly.

## Errors

- `samples must be in strictly ascending time order: 10 follows 10` - `counter value must not be negative: -1 at 10`

## Sources

- Prometheus, Query functions, `resets()`: "Any decrease in the value between two consecutive float samples is interpreted as a counter reset"; `increase()`: "The increase is extrapolated to cover the full time range as specified in the range vector selector", https://prometheus.io/docs/prometheus/latest/querying/functions/ - Prometheus, Metric types: Counter ("a cumulative metric ... whose value can only increase or be reset to zero on restart"), https://prometheus.io/docs/concepts/metric_types/#counter

Files