budget_machines 0.4.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +7 -0
- data/CHANGELOG.md +76 -0
- data/Cargo.lock +307 -0
- data/Cargo.toml +27 -0
- data/LICENSE.txt +21 -0
- data/README.md +306 -0
- data/ext/budget_machines_native/core/CHANGELOG.md +55 -0
- data/ext/budget_machines_native/core/Cargo.toml +17 -0
- data/ext/budget_machines_native/core/README.md +82 -0
- data/ext/budget_machines_native/core/src/ledger.rs +251 -0
- data/ext/budget_machines_native/core/src/lib.rs +180 -0
- data/ext/budget_machines_native/core/src/monitor.rs +424 -0
- data/ext/budget_machines_native/extconf.rb +2 -0
- data/ext/budget_machines_native/ffi/Cargo.toml +21 -0
- data/ext/budget_machines_native/ffi/extconf.rb +14 -0
- data/ext/budget_machines_native/ffi/src/classes.rs +50 -0
- data/ext/budget_machines_native/ffi/src/init.rs +50 -0
- data/ext/budget_machines_native/ffi/src/ledger.rs +117 -0
- data/ext/budget_machines_native/ffi/src/lib.rs +117 -0
- data/ext/budget_machines_native/ffi/src/monitor.rs +216 -0
- data/ext/budget_machines_native/ffi/src/values.rs +226 -0
- data/lib/budget_machines/version.rb +5 -0
- data/lib/budget_machines.rb +158 -0
- data/sig/budget_machines.rbs +183 -0
- metadata +89 -0
data/README.md
ADDED
|
@@ -0,0 +1,306 @@
|
|
|
1
|
+
# BudgetMachines
|
|
2
|
+
|
|
3
|
+
> 99.9% is not a compliment. It is a spending limit. 📉
|
|
4
|
+
|
|
5
|
+
Error-budget arithmetic for Ruby. You tell it your objective and hand it good and total counts. A ledger tells you how many failures the period can still afford, or how far past the limit you are. A monitor takes a long window and a short window per rule and tells you whether the budget is burning fast enough to wake someone, and when it has stopped. All of it in integers, so the answer is the same on every machine, and "we have no data" is never quietly rounded to "we are fine".
|
|
6
|
+
|
|
7
|
+
## Quick Start
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
gem 'budget_machines'
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
```ruby
|
|
14
|
+
BM = BudgetMachines
|
|
15
|
+
|
|
16
|
+
slo = BM::Objective.new(999, 1000) # 99.9% of requests succeed
|
|
17
|
+
|
|
18
|
+
ledger = BM::Ledger.new(slo, 0) # accounted per 30-day period, this is number 0
|
|
19
|
+
ledger.record(0, BM::Counts.new(99_950, 100_000)) # good, total for the window just closed
|
|
20
|
+
ledger.account.standing # => Standing::Within(remaining: 50), 50 failures left
|
|
21
|
+
|
|
22
|
+
monitor = BM::Monitor.new(slo, :hold, 0) # objective, no-data policy, minimum events per window
|
|
23
|
+
monitor.add_rule(BM::Rule.new(14_400, 14_400, 2)) # page: burning at 14.4x, severity 2
|
|
24
|
+
monitor.add_rule(BM::Rule.new(6_000, 6_000, 1)) # ticket: burning at 6x, severity 1
|
|
25
|
+
|
|
26
|
+
now = Process.clock_gettime(Process::CLOCK_MONOTONIC, :nanosecond)
|
|
27
|
+
read = ->(good, total) { BM::Sample::Counts.new(BM::Counts.new(good, total)) }
|
|
28
|
+
verdict = monitor.evaluate(now, [
|
|
29
|
+
BM::Windows.new(read.(98_000, 100_000), read.(9_700, 10_000)), # rule 0: long 1h, short 5m
|
|
30
|
+
BM::Windows.new(read.(598_000, 600_000), read.(49_800, 50_000)) # rule 1: long 6h, short 30m
|
|
31
|
+
])
|
|
32
|
+
verdict.decisions.first.change # => :raised
|
|
33
|
+
verdict.worst # => 0, go page someone
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
Two objects and a handful of frozen values. `BM` is only an alias to keep the lines short; don't `include BudgetMachines` at the top level, where a bare `Monitor` is Ruby's own. Every value has the name and the fields of the Rust type it mirrors: `Objective`, `Counts`, `Rule`, `Sample`, `Windows`, `Account`, `Standing`, `Decision`, `Verdict`. Every number is an Integer, and the instant you pass to `evaluate` is Integer nanoseconds of monotonic time. Burn rates and thresholds are in thousandths: `14_400` is 14.4 times the sustainable rate.
|
|
37
|
+
|
|
38
|
+
## A Message to the Resistance
|
|
39
|
+
|
|
40
|
+
So you have an SLO. Somebody put "99.9%" on a slide, everybody nodded, and then you had to turn it into an alert. You wrote `error_rate > 0.001 for 5m`. It paged you at 3 a.m. for forty failed requests on a night with no traffic. So you raised the threshold. Then a slow leak ate the entire month's budget over nine days at a rate that never crossed it, and you learned about it from a customer.
|
|
41
|
+
|
|
42
|
+
So you read the chapter. Burn rates, two windows per alert, a fast one and a slow one. You wrote it as a query. The query divides one float by another and compares the result to `14.4`, and on the day traffic drops to zero it divides zero by zero, gets `NaN`, compares `NaN > 14.4`, gets false, and resolves the page for an outage that is so complete nothing is being counted any more.
|
|
43
|
+
|
|
44
|
+
The piece you keep rebuilding is small. How many failures does this objective allow in this many events? How fast is this window spending them? Are both windows over the line, and is it still over the line now? And what do you say when a window has nothing in it? That arithmetic is this gem.
|
|
45
|
+
|
|
46
|
+
## Chapter 1: Stardate 2026.316, the AMS Beyer
|
|
47
|
+
|
|
48
|
+
> **AMS Beyer**, NCC-4225, *Beyer*-class reliability tender.
|
|
49
|
+
> A fleet that never spends its budget is flying too slowly. A fleet that never counts it is already out.
|
|
50
|
+
|
|
51
|
+
The tender doesn't repair anything. It keeps the books. Every ship in the fleet has an agreed number of bad jumps per thousand, and the tender knows how many each one has left this cycle and how quickly it is going through them. When a ship stops reporting, the tender does not write down zero failures. It writes down "no report", which is a different column.
|
|
52
|
+
|
|
53
|
+
On a bridge somewhere, a cadet volunteers:
|
|
54
|
+
|
|
55
|
+
```ruby
|
|
56
|
+
def alert?(errors, requests)
|
|
57
|
+
errors / requests.to_f > 0.001
|
|
58
|
+
end
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
"Run it with no requests," says the tender's purser. "Then tell me whether the ship is healthy or missing."
|
|
62
|
+
|
|
63
|
+
## The Flight Plan
|
|
64
|
+
|
|
65
|
+
Each rule in a monitor is in one of three states:
|
|
66
|
+
|
|
67
|
+
```mermaid
|
|
68
|
+
stateDiagram-v2
|
|
69
|
+
[*] --> no_data
|
|
70
|
+
no_data --> quiet: both windows measured, not both burning
|
|
71
|
+
no_data --> firing: both windows at or over the fire threshold
|
|
72
|
+
quiet --> firing: both windows at or over the fire threshold
|
|
73
|
+
firing --> quiet: either window under the clear threshold
|
|
74
|
+
firing --> firing: a window is missing, policy is hold or fire
|
|
75
|
+
quiet --> no_data: a window is missing, policy is reset
|
|
76
|
+
firing --> no_data: a window is missing, policy is reset
|
|
77
|
+
quiet --> firing: a window is missing, policy is fire
|
|
78
|
+
no_data --> firing: a window is missing, policy is fire
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
And the afternoon the payment API started failing one request in fifty:
|
|
82
|
+
|
|
83
|
+
```mermaid
|
|
84
|
+
sequenceDiagram
|
|
85
|
+
participant Q as Your metrics query
|
|
86
|
+
participant M as Monitor
|
|
87
|
+
participant L as Ledger
|
|
88
|
+
participant P as Your pager
|
|
89
|
+
|
|
90
|
+
Q->>M: evaluate(t1, 1h calm, 5m burning 20x)
|
|
91
|
+
M-->>Q: quiet. One window is not enough.
|
|
92
|
+
Q->>M: evaluate(t2, 1h burning 20x, 5m burning 30x)
|
|
93
|
+
M-->>Q: firing, change raised
|
|
94
|
+
Q->>P: page
|
|
95
|
+
Q->>L: record(period, counts)
|
|
96
|
+
L-->>Q: exhausted, 1,900 over
|
|
97
|
+
Note over Q: fix deployed
|
|
98
|
+
Q->>M: evaluate(t3, 1h burning 18x, 5m calm)
|
|
99
|
+
M-->>Q: quiet, change cleared
|
|
100
|
+
Q->>P: resolve
|
|
101
|
+
Note over M: the 1h window is still hot. The 5m one says it's over.
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
## How the Budget Works
|
|
105
|
+
|
|
106
|
+
### The objective
|
|
107
|
+
|
|
108
|
+
An `Objective` is two Integers: `good` of every `per` events. `Counts` is a window: `good` of `total`.
|
|
109
|
+
|
|
110
|
+
```ruby
|
|
111
|
+
slo = BM::Objective.new(999, 1000)
|
|
112
|
+
slo.tolerated # => 1 failure per 1,000
|
|
113
|
+
slo.allowance(100_000) # => 100 failures allowed in 100,000
|
|
114
|
+
slo.burn_milli(BM::Counts.new(9_856, 10_000)) # => 14400, i.e. 14.4x
|
|
115
|
+
slo.burn_milli_of(144, 10_000) # => 14400, from bad and total
|
|
116
|
+
slo.burn_milli(BM::Counts.new(0, 0)) # => nil, no events is not a rate
|
|
117
|
+
slo.burns_at_least(BM::Counts.new(9_856, 10_000), 14_400) # => true, exact, no division
|
|
118
|
+
|
|
119
|
+
BM::Counts.new(995, 1000).bad # => 5
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
A burn rate of `1000` spends the budget exactly as fast as the objective allows. `999, 1000` and `9_990, 10_000` are the same objective. `Objective.new(1000, 1000)` raises `RangeError`: a 100% target has no budget to account. So does `Counts.new(2, 1)`: more good events than events.
|
|
123
|
+
|
|
124
|
+
### Record
|
|
125
|
+
|
|
126
|
+
```ruby
|
|
127
|
+
ledger = BM::Ledger.new(BM::Objective.new(99, 100), 7) # 99%, period 7
|
|
128
|
+
|
|
129
|
+
ledger.record(7, BM::Counts.new(995, 1000)) # => :ok
|
|
130
|
+
ledger.record(6, BM::Counts.new(10, 10)) # => :stale_period, nothing added
|
|
131
|
+
ledger.counts # => Counts(good: 995, total: 1000)
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
`record` adds a window's counts to the current period. The period is a number you choose and advance. Counts for any other period are refused. A sum that would not fit in 64 bits is refused with `:overflow`.
|
|
135
|
+
|
|
136
|
+
When your source gives you the running total instead of a delta, use `replace`:
|
|
137
|
+
|
|
138
|
+
```ruby
|
|
139
|
+
ledger.replace(7, BM::Counts.new(995, 1000)) # => :ok, the period now holds exactly this
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
`record` answers `:ok`, or refuses with `:stale_period` or `:overflow`. `replace` answers `:ok`, or refuses with `:stale_period`.
|
|
143
|
+
|
|
144
|
+
### Account
|
|
145
|
+
|
|
146
|
+
```ruby
|
|
147
|
+
account = ledger.account
|
|
148
|
+
account.counts # => Counts(good: 995, total: 1000)
|
|
149
|
+
account.allowance # => 10 failures 1,000 events may contain at 99%
|
|
150
|
+
account.standing # => Standing::Within(remaining: 5)
|
|
151
|
+
account.consumed_milli # => 500 half the budget
|
|
152
|
+
|
|
153
|
+
case account.standing
|
|
154
|
+
in BM::Standing::Within[remaining:] then "#{remaining} failures left"
|
|
155
|
+
in BM::Standing::Exhausted[overspent:] then "#{overspent} over"
|
|
156
|
+
in :no_data then 'nothing observed'
|
|
157
|
+
end
|
|
158
|
+
|
|
159
|
+
BM::Ledger.new(BM::Objective.new(99, 100), 7).account.standing # => :no_data
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
An `Account` has exactly the fields of the core's: `period`, `counts`, `base`, `allowance`, `standing`, `consumed_milli`. `standing` is one of three values, one per variant of the core's `Standing`: `Standing::Within` carries `remaining`, `Standing::Exhausted` carries `overspent`, and the unit variant `NoData` is the symbol `:no_data`, because an empty period has nothing to report. Ask by matching `standing` (`case account.standing in BM::Standing::Within`), as a Rust caller matches the enum: there are no Ruby-only predicates. An empty period has a `nil` `consumed_milli`.
|
|
163
|
+
|
|
164
|
+
The allowance grows with traffic, so one failure in the first ten requests of a period is exhausted. If you'd rather budget against the traffic you expect:
|
|
165
|
+
|
|
166
|
+
```ruby
|
|
167
|
+
ledger = BM::Ledger.new(BM::Objective.new(999, 1000), 0)
|
|
168
|
+
ledger.record(0, BM::Counts.new(9, 10))
|
|
169
|
+
ledger.account.standing # => Standing::Exhausted(overspent: 1)
|
|
170
|
+
ledger.account_against(100_000).standing # => Standing::Within(remaining: 99)
|
|
171
|
+
ledger.account_against(5) # => :below_observed
|
|
172
|
+
```
|
|
173
|
+
|
|
174
|
+
`account` always answers an `Account`. `account_against` answers an `Account`, or refuses with `:below_observed`.
|
|
175
|
+
|
|
176
|
+
### Roll
|
|
177
|
+
|
|
178
|
+
```ruby
|
|
179
|
+
closed = ledger.roll(1) # => the Account period 0 ended with
|
|
180
|
+
ledger.account.standing # => :no_data
|
|
181
|
+
ledger.roll(1) # => :stale_period
|
|
182
|
+
```
|
|
183
|
+
|
|
184
|
+
`roll` closes the period, hands you its final account, and starts the next one empty. The new period must be greater than the current one. Nothing rolls on its own. `roll` answers the closed `Account`, or refuses with `:stale_period`.
|
|
185
|
+
|
|
186
|
+
### Rules
|
|
187
|
+
|
|
188
|
+
```ruby
|
|
189
|
+
monitor = BM::Monitor.new(BM::Objective.new(999, 1000), :hold, 0)
|
|
190
|
+
monitor.add_rule(BM::Rule.new(14_400, 14_400, 2)) # => 0
|
|
191
|
+
monitor.add_rule(BM::Rule.new(6_000, 3_000, 1)) # => 1
|
|
192
|
+
monitor.rule(1) # => Rule(fire_milli: 6000, clear_milli: 3000, severity: 1)
|
|
193
|
+
monitor.state(1) # => :no_data, never measured
|
|
194
|
+
monitor.size # => 2
|
|
195
|
+
```
|
|
196
|
+
|
|
197
|
+
`Monitor.new` takes the objective, the no-data policy and the minimum events a window needs to count as measured. All three are required, as they are in the core: there is no default policy to forget you chose.
|
|
198
|
+
|
|
199
|
+
A `Rule` is a fire threshold, a clear threshold and a severity. It fires when the long window and the short window both burn at the fire threshold or more. Once firing, it stays firing until either window drops below the clear threshold. Give both the same value for the textbook rule, or a lower clear threshold if you'd like an alert that doesn't flap around the line. A monitor holds `BudgetMachines::CAPACITY` rules, which is 8. `add_rule` answers the new rule's index, or refuses with `:full`.
|
|
200
|
+
|
|
201
|
+
### Evaluate
|
|
202
|
+
|
|
203
|
+
```ruby
|
|
204
|
+
read = ->(good, total) { BM::Sample::Counts.new(BM::Counts.new(good, total)) }
|
|
205
|
+
hot = read.(9_800, 10_000) # burning at 20x
|
|
206
|
+
calm = read.(10_000, 10_000)
|
|
207
|
+
windows = ->(long, short) { BM::Windows.new(long, short) }
|
|
208
|
+
|
|
209
|
+
minute = 60_000_000_000 # instants are Integer nanoseconds
|
|
210
|
+
t0 = Process.clock_gettime(Process::CLOCK_MONOTONIC, :nanosecond)
|
|
211
|
+
|
|
212
|
+
monitor.evaluate(t0, [windows.(hot, calm), windows.(hot, calm)]).decisions.map(&:state)
|
|
213
|
+
# => [:quiet, :quiet]
|
|
214
|
+
|
|
215
|
+
verdict = monitor.evaluate(t0 + minute, [windows.(hot, hot), windows.(hot, hot)])
|
|
216
|
+
page, ticket = verdict.decisions
|
|
217
|
+
page.state # => :firing
|
|
218
|
+
page.change # => :raised
|
|
219
|
+
page.long_milli # => 20000
|
|
220
|
+
page.since == t0 + minute # => true, the instant it started firing
|
|
221
|
+
verdict.worst # => 0, the firing rule with the highest severity
|
|
222
|
+
monitor.last == t0 + minute # => true
|
|
223
|
+
|
|
224
|
+
slower = read.(9_950, 10_000)
|
|
225
|
+
monitor.evaluate(t0 + (2 * minute), [windows.(hot, calm), windows.(hot, slower)]).decisions.map(&:change)
|
|
226
|
+
# => [:cleared, :none] rule 1 is at 5x: under its fire line, over its clear line
|
|
227
|
+
```
|
|
228
|
+
|
|
229
|
+
You pass the instant and one `Windows` per rule, in rule order. A `Windows` is a `long` and a `short` reading, and a reading is the core's `Sample`: a `Sample::Counts` wrapping a `Counts`, or `:no_data`. The instant is Integer nanoseconds from a monotonic clock, `Process.clock_gettime(Process::CLOCK_MONOTONIC, :nanosecond)`; `since` and `last` come back in the same unit. The monitor never sees a window length: you choose the windows and bring their counts. You get a `Verdict`: one `Decision` per rule in `decisions`, and `worst`, the index of the firing rule with the highest severity. `change` is `:raised` or `:cleared` on the evaluation where the alert starts or stops, and `:none` otherwise, so you can page on edges without keeping your own copy of the state.
|
|
230
|
+
|
|
231
|
+
`evaluate` answers a `Verdict`, or refuses with `:time_regression` or `:shape`.
|
|
232
|
+
|
|
233
|
+
### No data
|
|
234
|
+
|
|
235
|
+
A window reading can be `:no_data`. It also counts as missing when its total is zero, or below the `min_total` you configured.
|
|
236
|
+
|
|
237
|
+
```ruby
|
|
238
|
+
monitor = BM::Monitor.new(BM::Objective.new(999, 1000), :hold, 100)
|
|
239
|
+
monitor.add_rule(BM::Rule.new(14_400, 14_400, 2))
|
|
240
|
+
|
|
241
|
+
decision = monitor.evaluate(t0, [BM::Windows.new(read.(9_800, 10_000), :no_data)]).decisions.first
|
|
242
|
+
decision.measured? # => false
|
|
243
|
+
decision.state # => :no_data, it has never been measured
|
|
244
|
+
decision.short_milli # => nil
|
|
245
|
+
```
|
|
246
|
+
|
|
247
|
+
The policy decides what a rule does when it can't be measured:
|
|
248
|
+
|
|
249
|
+
- `:hold` keeps the state it had. A firing alert keeps firing through a scrape gap.
|
|
250
|
+
- `:reset` puts it back to `:no_data`. A firing alert clears, and says so with `:cleared`.
|
|
251
|
+
- `:fire` treats silence as an outage.
|
|
252
|
+
|
|
253
|
+
Whichever you pick, `measured?` is `false` on that decision, so a state the policy chose is never mistaken for one the numbers chose. It is not a stored field: a decision was measured exactly when both burn rates are known, as in the core's `Decision::measured`.
|
|
254
|
+
|
|
255
|
+
### Time only moves forward
|
|
256
|
+
|
|
257
|
+
```ruby
|
|
258
|
+
monitor.evaluate(t0 + minute, [windows.(hot, hot)])
|
|
259
|
+
monitor.evaluate(t0, [windows.(hot, hot)]) # => :time_regression
|
|
260
|
+
monitor.evaluate(t0 + (2 * minute), []) # => :shape, one Windows per rule
|
|
261
|
+
```
|
|
262
|
+
|
|
263
|
+
A refused evaluation changes no alert state. Evaluating the same instant twice is allowed.
|
|
264
|
+
|
|
265
|
+
## The Rules of the Tender
|
|
266
|
+
|
|
267
|
+
- **Time is Integer nanoseconds.** The `now` of `evaluate`, `Decision#since` and `Monitor#last` are instants of a monotonic clock in nanoseconds. A Float or anything else that isn't an Integer raises `TypeError`; negative or past `2**64-1` raises `RangeError`. A ledger period is not time: it is an opaque number you advance.
|
|
268
|
+
- **Everything is an Integer.** Counts, periods and instants are in `0..2**64-1`. Objectives and thresholds are in `0..2**32-1`. Severity is `0..255`. Floats, nil and strings raise `TypeError`, and so does an Array where a `Counts`, `Objective`, `Rule`, `Sample::Counts` or `Windows` belongs, or `nil` where a window reading belongs. Out of range, `good > total`, a 100% objective, a clear threshold above the fire threshold, or a Symbol outside the listed ones (a policy of `:panic`, a window reading of `:quiet`) raises `RangeError` when the value is built, so an invalid one never exists.
|
|
269
|
+
- **Ruby mirrors Rust.** Every `Data` value has the name and the fields, in order, of the core's struct. An enum's unit variant is a symbol and a variant that carries something is a `Data` named after it: the no-data policy is `:hold`, `:reset` or `:fire`; a rule's state is `:no_data`, `:quiet` or `:firing`; a change is `:none`, `:raised` or `:cleared`; a window reading is `:no_data` or a `Sample::Counts`; a standing is `:no_data`, a `Standing::Within` or a `Standing::Exhausted`.
|
|
270
|
+
- **Refusals don't raise.** `:stale_period`, `:overflow`, `:below_observed`, `:full`, `:shape` and `:time_regression` are answers, and the object is exactly as it was before you asked.
|
|
271
|
+
- **Every answer, by method.**
|
|
272
|
+
|
|
273
|
+
| Method | Honoured | Refused |
|
|
274
|
+
| --- | --- | --- |
|
|
275
|
+
| `Ledger#record(period, counts)` | `:ok` | `:stale_period`, `:overflow` |
|
|
276
|
+
| `Ledger#replace(period, counts)` | `:ok` | `:stale_period` |
|
|
277
|
+
| `Ledger#roll(period)` | the closed `Account` | `:stale_period` |
|
|
278
|
+
| `Ledger#account_against(planned_total)` | an `Account` | `:below_observed` |
|
|
279
|
+
| `Monitor#add_rule(rule)` | the rule's index (Integer) | `:full` |
|
|
280
|
+
| `Monitor#evaluate(now, windows)` | a `Verdict` | `:time_regression`, `:shape` |
|
|
281
|
+
|
|
282
|
+
Those six symbols are every variant of the core's `Refusal`, and each is reachable. There is no catch-all symbol.
|
|
283
|
+
- **Which answers record the clock.** Only `Monitor#evaluate` takes a clock. Every honoured `evaluate` records `now` as `Monitor#last`, because every `Verdict` is the rules' state as of `now`: a later evaluation at an earlier instant would judge older readings after newer ones. A refusal records nothing. The ledger has no clock: its period is an opaque number.
|
|
284
|
+
- **Values are valid or do not exist.** Every `Data` value validates through the core when it is built, by you or by the gem: `Counts`, `Objective` and `Rule` through their constructors, `Account`, `Decision` and `Verdict` through constructors that refuse what no ledger or evaluation could produce (an allowance above its base, a standing the counts do not give, a raised edge that isn't firing, a `worst` that names a quiet rule). A wrong type raises `TypeError`, a value the core rejects (including an unknown Symbol) raises `RangeError`. What you pass and what you get back compare `==`. Every value class is sealed: `allocate` is undefined and subclassing raises `TypeError`, so nothing skips the check.
|
|
285
|
+
- **The binding never loses work.** Every conversion happens before the core is called, and the classes are resolved once, at load. Building an answer runs Ruby code (`new`), so `roll` and `evaluate` decide on a copy, build the answer, and keep the copy only if the object is still unfrozen and unchanged: if building raises, nothing is applied; if it freezes the object, `FrozenError`; if it re-enters and changes the object, `RuntimeError`, and the outer call is not applied.
|
|
286
|
+
- **The binding trusts no value it reads.** Sealing stops accidents, not reflection: a named subclass's constant is bound before `inherited` raises, and `Marshal.load` skips `initialize`. So every value passed in must be an instance of exactly the gem's class (a subclass raises `TypeError`), and its fields are rebuilt through the core's constructor (a forged field raises `RangeError`). A forged value never reaches the core.
|
|
287
|
+
- **No floats inside.** Thresholds are compared by cross-multiplying in 128 bits. Reported burn rates are rounded down to the thousandth. Decisions never use the rounded number.
|
|
288
|
+
- **No data is not zero.** An empty window has a `nil` burn rate. An empty period has no standing.
|
|
289
|
+
- **Frozen means frozen.** `freeze` a ledger or a monitor and anything that would change it raises `FrozenError`. Reading still works.
|
|
290
|
+
|
|
291
|
+
## What You Think You're Doing vs Reality
|
|
292
|
+
|
|
293
|
+
### You Think: "Zero errors in the window, so the alert can clear."
|
|
294
|
+
### Reality: Zero requests in the window, because the load balancer is on fire.
|
|
295
|
+
|
|
296
|
+
Zero failures out of ten thousand and zero failures out of zero look identical once you've divided. They aren't the same fact. The first is a measurement. The second is the absence of one, and it shows up most reliably during the outages you most wanted to hear about. The monitor keeps them apart and makes you say, once, in the constructor, what silence means for you.
|
|
297
|
+
|
|
298
|
+
## What's Yours
|
|
299
|
+
|
|
300
|
+
This is the initial release of a policy core, and the API will change. It does arithmetic and remembers which alerts are firing. It does not collect metrics, run queries, know what time it is, send pages, or decide what a good request is. You bring the counts for each window, exact, from wherever you keep them, and you choose the window lengths. `window_machines` can give you the window boundaries. You decide when a compliance period ends and call `roll`. State lives in your process and is gone when it exits, so persist what you can't afford to recompute. If an empty budget should shed load or open a breaker, that is your coordinator reading an `Account` and telling `shed_machines` or `breaker_machines` what to do. This gem will not do it behind your back.
|
|
301
|
+
|
|
302
|
+
## License
|
|
303
|
+
|
|
304
|
+
MIT License. See [LICENSE.txt](LICENSE.txt) for details.
|
|
305
|
+
|
|
306
|
+
**Remember: the budget is there to be spent. Just not by accident, and not all on a Tuesday.**
|
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
## [0.6.1](https://github.com/seuros/budget_machines/compare/budget-machines-v0.6.0...budget-machines-v0.6.1) (2026-11-16)
|
|
4
|
+
|
|
5
|
+
|
|
6
|
+
### Bug Fixes
|
|
7
|
+
|
|
8
|
+
* deny runtime indexing in the budget core and use matryona registry! ([7144843](https://github.com/seuros/budget_machines/commit/71448431417b61e69606e791738ff7747cc90c57))
|
|
9
|
+
|
|
10
|
+
## [0.6.0](https://github.com/seuros/budget_machines/compare/budget-machines-v0.5.0...budget-machines-v0.6.0) (2026-11-14)
|
|
11
|
+
|
|
12
|
+
|
|
13
|
+
### âš BREAKING CHANGES
|
|
14
|
+
|
|
15
|
+
* build the binding on matryona-machines 0.2; read every value from the struct; compiler-checked state, change, policy and refusal symbols
|
|
16
|
+
|
|
17
|
+
### Features
|
|
18
|
+
|
|
19
|
+
* build the binding on matryona-machines 0.2; read every value from the struct; compiler-checked state, change, policy and refusal symbols ([9fbe6ac](https://github.com/seuros/budget_machines/commit/9fbe6ac909a740ad330633d27ad9128d41745449))
|
|
20
|
+
|
|
21
|
+
## [0.5.0](https://github.com/seuros/budget_machines/compare/budget-machines-v0.4.0...budget-machines-v0.5.0) (2026-11-14)
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
### âš BREAKING CHANGES
|
|
25
|
+
|
|
26
|
+
* seal and validate every value, private Account/Decision fields, derive Decision#measured?, clone-then-keep roll/evaluate
|
|
27
|
+
|
|
28
|
+
### Features
|
|
29
|
+
|
|
30
|
+
* seal and validate every value, private Account/Decision fields, derive Decision#measured?, clone-then-keep roll/evaluate ([8ccb894](https://github.com/seuros/budget_machines/commit/8ccb894896018e4b531361f5e2a1f321cf1a13cd))
|
|
31
|
+
|
|
32
|
+
## [0.4.0](https://github.com/seuros/budget_machines/compare/budget-machines-v0.3.0...budget-machines-v0.4.0) (2026-11-13)
|
|
33
|
+
|
|
34
|
+
|
|
35
|
+
### âš BREAKING CHANGES
|
|
36
|
+
|
|
37
|
+
* see CONVENTIONS: one exhaustive Refusal per crate, Result from every mutator, honoured idempotent repeats, Ruby mirrors the core. No compatibility aliases. Ruby gains Objective, Counts, Rule, Windows, Verdict, Standing and Sample values; Monitor arguments are required; times are Integer nanoseconds.
|
|
38
|
+
|
|
39
|
+
### Features
|
|
40
|
+
|
|
41
|
+
* Refusal without alias, Duration evaluation instants, Ruby mirrors the core types ([0f2792d](https://github.com/seuros/budget_machines/commit/0f2792d88b01d6f7f331f1383aa5c779010f7a24))
|
|
42
|
+
|
|
43
|
+
## [0.3.0](https://github.com/seuros/budget_machines/compare/budget-machines-v0.2.0...budget-machines-v0.3.0) (2026-11-13)
|
|
44
|
+
|
|
45
|
+
|
|
46
|
+
### Features
|
|
47
|
+
|
|
48
|
+
* rename Refused to Refusal, keep deprecated alias ([cca679d](https://github.com/seuros/budget_machines/commit/cca679ddb53a8a45d626d141965cd255e45d6b7c))
|
|
49
|
+
|
|
50
|
+
## [0.2.0](https://github.com/seuros/budget_machines/compare/budget-machines-v0.1.0...budget-machines-v0.2.0) (2026-11-12)
|
|
51
|
+
|
|
52
|
+
|
|
53
|
+
### Features
|
|
54
|
+
|
|
55
|
+
* initial extraction ([8a0d71a](https://github.com/seuros/budget_machines/commit/8a0d71a7a80ccb3c2fda733ed1aaf0623e88c4c5))
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
[package]
|
|
2
|
+
name = "budget-machines"
|
|
3
|
+
version = "0.6.1"
|
|
4
|
+
edition.workspace = true
|
|
5
|
+
rust-version.workspace = true
|
|
6
|
+
license.workspace = true
|
|
7
|
+
description = "SLO error-budget accounting and multi-window burn-rate alert decisions from supplied counts"
|
|
8
|
+
readme = "README.md"
|
|
9
|
+
exclude = ["src/**/tests.rs", "src/tests/", "tests/"]
|
|
10
|
+
keywords = ["slo", "error-budget", "burn-rate", "alerting", "no-std"]
|
|
11
|
+
categories = ["no-std", "algorithms"]
|
|
12
|
+
|
|
13
|
+
[dev-dependencies]
|
|
14
|
+
matryona-machines = { workspace = true, features = ["testing"] }
|
|
15
|
+
|
|
16
|
+
[lints]
|
|
17
|
+
workspace = true
|
|
@@ -0,0 +1,82 @@
|
|
|
1
|
+
# budget-machines
|
|
2
|
+
|
|
3
|
+
> **AMS Beyer**, NCC-4225, *Beyer*-class reliability tender.
|
|
4
|
+
|
|
5
|
+
Engine-room flight manual: count what the objective tolerates, and say when it
|
|
6
|
+
is being spent too fast.
|
|
7
|
+
|
|
8
|
+
Allocation-free `no_std` SLO error-budget accounting and multi-window burn-rate
|
|
9
|
+
alerting. All arithmetic is integer: objectives are exact ratios, burn rates
|
|
10
|
+
are thousandths (`MILLI`), and every threshold comparison is a division-free
|
|
11
|
+
128-bit cross-multiplication, so two machines never disagree about an alert.
|
|
12
|
+
|
|
13
|
+
The caller supplies everything: exact good/total counts for each window, the
|
|
14
|
+
instant of each evaluation, and the number of the compliance period. The crate
|
|
15
|
+
has no clock, no storage and no query engine, and it never rolls a period over
|
|
16
|
+
on its own.
|
|
17
|
+
|
|
18
|
+
- `Objective` is `good` of every `per` events. A 100% objective is refused: it
|
|
19
|
+
has no budget to account.
|
|
20
|
+
- `Ledger` accumulates one compliance period. `record` adds a window, `replace`
|
|
21
|
+
takes an authoritative reading, `roll` closes the period. A stale period or
|
|
22
|
+
an overflowing sum is refused and changes nothing. `account` reports the
|
|
23
|
+
whole bad events tolerated, what is left or overspent, and the consumed
|
|
24
|
+
fraction; `account_against` does it against a planned period total.
|
|
25
|
+
- `Monitor<R>` holds up to `R` rules. A `Rule` fires when the long and the
|
|
26
|
+
short window both burn at its threshold or more, and clears when either
|
|
27
|
+
falls below its clear threshold. `evaluate` returns one `Decision` per rule
|
|
28
|
+
and the worst firing rule; a backwards instant or the wrong number of window
|
|
29
|
+
pairs is refused and changes nothing.
|
|
30
|
+
- Time is a `core::time::Duration` since an epoch the caller picks: the `now`
|
|
31
|
+
of `evaluate`, `Monitor::last` and `Decision::since`. The monitor never sees
|
|
32
|
+
a window length; the caller chooses the windows and brings their counts. A
|
|
33
|
+
ledger period is an opaque `u64` the caller advances, not a clock.
|
|
34
|
+
|
|
35
|
+
`Account`, `Decision` and `Verdict` are what the core returns. Their fields
|
|
36
|
+
are private behind readers, and each also has a validating `new` that answers
|
|
37
|
+
`None` for fields no ledger or evaluation could produce, so a binding can hold
|
|
38
|
+
a rebuilt value to the same rule: an
|
|
39
|
+
account's base covers its observed total, its allowance does not exceed the
|
|
40
|
+
base, its standing is the one its counts and allowance give and its consumed
|
|
41
|
+
fraction is consistent with both; a decision's edge lands in the right state
|
|
42
|
+
at a recorded instant and one with both burn rates was measured, so it is
|
|
43
|
+
`Quiet` or `Firing`; a verdict holds
|
|
44
|
+
at most `R` decisions and its `worst` names a firing one exactly when one
|
|
45
|
+
fires. The allowance is computed in 64 bits without narrowing, so nothing
|
|
46
|
+
saturates there.
|
|
47
|
+
|
|
48
|
+
`evaluate` records `now` whenever it is honoured: every verdict is the rules'
|
|
49
|
+
state as of that instant. A refusal records nothing. The ledger has no clock.
|
|
50
|
+
|
|
51
|
+
No data is a state, not a zero. An empty period stands at `Standing::NoData`. A
|
|
52
|
+
window that is `Sample::NoData`, empty, or below the monitor's minimum total is
|
|
53
|
+
not measured, and the monitor's `OnNoData` policy (`Hold`, `Reset`, `Fire`)
|
|
54
|
+
decides the rule's state; `Decision::measured` says which happened. It is not
|
|
55
|
+
a stored flag: a decision was measured exactly when both burn rates are known.
|
|
56
|
+
|
|
57
|
+
```rust
|
|
58
|
+
use core::time::Duration;
|
|
59
|
+
|
|
60
|
+
use budget_machines::{Counts, Ledger, Monitor, Objective, OnNoData, Rule, Sample, Standing, Windows};
|
|
61
|
+
|
|
62
|
+
let slo = Objective::new(999, 1000).expect("below 100%");
|
|
63
|
+
|
|
64
|
+
let mut ledger = Ledger::new(slo, 0);
|
|
65
|
+
assert_eq!(ledger.account().standing(), Standing::NoData);
|
|
66
|
+
ledger.record(0, Counts::new(99_950, 100_000).expect("good <= total")).expect("current period");
|
|
67
|
+
assert_eq!(ledger.account().standing(), Standing::Within { remaining: 50 });
|
|
68
|
+
|
|
69
|
+
let mut monitor = Monitor::<4>::new(slo, OnNoData::Hold, 0);
|
|
70
|
+
let page = monitor.add_rule(Rule::new(14_400, 14_400, 2).expect("thresholds")).expect("room");
|
|
71
|
+
let window = |good, total| Sample::Counts(Counts::new(good, total).expect("good <= total"));
|
|
72
|
+
let burning = Windows { long: window(98_000, 100_000), short: window(9_700, 10_000) };
|
|
73
|
+
// `now` is monotonic time since an epoch the caller picks.
|
|
74
|
+
let now = Duration::from_secs(60);
|
|
75
|
+
let verdict = monitor.evaluate(now, &[burning]).expect("time moved forward");
|
|
76
|
+
assert_eq!(verdict.worst(), Some(page));
|
|
77
|
+
assert_eq!(verdict.decisions()[page].since(), Some(now));
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
This is a policy core. It does not collect metrics, page anyone, or decide what
|
|
81
|
+
a good event is. Shedding load or opening a breaker because a budget is gone is
|
|
82
|
+
a coordinator's decision, made outside this crate.
|