slokit 0.2.0

SLO and error-budget engine for Rust: compute error budgets and burn rates, and generate multi-window multi-burn-rate Prometheus alert rules from sloth-compatible specs.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125

//! Error-budget math: how much failure an SLO permits, and how much is left.

use crate::burn_rate::BurnRate;
use crate::window::Window;

/// A concrete error budget: the allowable failures for a known event volume
/// over an SLO period.
///
/// Create one with [`crate::Slo::error_budget`].
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct ErrorBudget {
    total_events: f64,
    budget_ratio: f64,
}

impl ErrorBudget {
    /// Build a budget directly from a total event count and the budget ratio
    /// (`1 - objective`).
    pub fn new(total_events: f64, budget_ratio: f64) -> Self {
        Self {
            total_events,
            budget_ratio,
        }
    }

    /// Total events observed (or projected) over the period.
    pub fn total_events(&self) -> f64 {
        self.total_events
    }

    /// The budget ratio, i.e. `1 - objective`.
    pub fn budget_ratio(&self) -> f64 {
        self.budget_ratio
    }

    /// The number of events that may fail before the budget is exhausted.
    pub fn allowed_bad_events(&self) -> f64 {
        self.total_events * self.budget_ratio
    }

    /// Events of budget remaining after `observed_bad` failures. May be
    /// negative when the budget is overspent.
    pub fn remaining_events(&self, observed_bad: f64) -> f64 {
        self.allowed_bad_events() - observed_bad
    }

    /// Fraction of the budget already consumed by `observed_bad` failures
    /// (`0.0` = untouched, `1.0` = exactly exhausted, `> 1.0` = overspent).
    pub fn consumed_ratio(&self, observed_bad: f64) -> f64 {
        let allowed = self.allowed_bad_events();
        if allowed <= 0.0 {
            return f64::INFINITY;
        }
        observed_bad / allowed
    }

    /// Fraction of the budget still available (`1.0` = untouched, `0.0` =
    /// exhausted). Clamped at zero on the low end.
    pub fn remaining_ratio(&self, observed_bad: f64) -> f64 {
        (1.0 - self.consumed_ratio(observed_bad)).max(0.0)
    }

    /// Time until the budget is exhausted, given a sustained burn rate and the
    /// SLO period.
    ///
    /// Returns `None` when the burn rate is zero or negative (the budget is
    /// never exhausted at that rate).
    pub fn time_to_exhaustion(
        &self,
        observed_bad: f64,
        burn_rate: BurnRate,
        period: Window,
    ) -> Option<std::time::Duration> {
        burn_rate.time_to_exhaustion(self.remaining_ratio(observed_bad), period)
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    fn budget_999() -> ErrorBudget {
        // 99.9% over a period with 1,000,000 events: 1,000 allowed failures.
        ErrorBudget::new(1_000_000.0, 0.001)
    }

    #[test]
    fn allowed_bad_events_is_total_times_budget() {
        assert!((budget_999().allowed_bad_events() - 1_000.0).abs() < 1e-6);
    }

    #[test]
    fn consumed_and_remaining_are_complementary() {
        let b = budget_999();
        assert!((b.consumed_ratio(250.0) - 0.25).abs() < 1e-12);
        assert!((b.remaining_ratio(250.0) - 0.75).abs() < 1e-12);
    }

    #[test]
    fn overspend_clamps_remaining_to_zero() {
        let b = budget_999();
        assert_eq!(b.remaining_ratio(5_000.0), 0.0);
        assert!(b.remaining_events(5_000.0) < 0.0);
    }

    #[test]
    fn time_to_exhaustion_scales_with_burn_rate() {
        let b = budget_999();
        let period = Window::days(30);
        // Fresh budget, burn rate 1.0: exhausts in exactly one period.
        let ttx = b
            .time_to_exhaustion(0.0, BurnRate::new(1.0), period)
            .unwrap();
        assert_eq!(ttx.as_secs(), period.as_secs());
        // Burn rate 10x: exhausts in a tenth of the period.
        let fast = b
            .time_to_exhaustion(0.0, BurnRate::new(10.0), period)
            .unwrap();
        assert_eq!(fast.as_secs(), period.as_secs() / 10);
        // No burn: never.
        assert!(b
            .time_to_exhaustion(0.0, BurnRate::new(0.0), period)
            .is_none());
    }
}