|
| 1 | +Service-Level Objectives (SLO) |
| 2 | +============================== |
| 3 | + |
| 4 | +The framework emits raw signals (``observability`` metrics, ``run_history`` |
| 5 | +durations) but had no operational layer turning them into an SLO, an error |
| 6 | +budget, or burn-rate alerts. This adds that: compute the SLI over a window of |
| 7 | +outcome records, the error budget against a target, and the **multi-window |
| 8 | +multi-burn-rate** alerts from the Google SRE workbook. |
| 9 | + |
| 10 | +Records are plain data (``[{"timestamp": float, "ok": bool}, ...]``) so the |
| 11 | +whole thing is offline and deterministic; the clock is injectable. Pure |
| 12 | +standard library; imports no ``PySide6``. |
| 13 | + |
| 14 | +Headless API |
| 15 | +------------ |
| 16 | + |
| 17 | +.. code-block:: python |
| 18 | +
|
| 19 | + from je_auto_control import evaluate_slo, burn_alerts |
| 20 | +
|
| 21 | + report = evaluate_slo(records, target=0.99) |
| 22 | + # {"sli": 0.995, "good": 995, "total": 1000, "target": 0.99, |
| 23 | + # "budget_total": 10.0, "budget_remaining": 5.0, |
| 24 | + # "budget_remaining_fraction": 0.5, "burn_rate": 0.5} |
| 25 | +
|
| 26 | + for alert in burn_alerts(records, target=0.99): |
| 27 | + page_oncall(alert) # severity, threshold, long/short burn rates |
| 28 | +
|
| 29 | +``evaluate_slo`` computes the SLI (good / total), the error budget |
| 30 | +(``(1 - target) * total`` events) and the burn rate (``bad_rate / (1 - |
| 31 | +target)`` — 1.0 means spending budget exactly on pace, > 1 means too fast). |
| 32 | +``burn_rate`` is the bare number over a window. ``burn_alerts`` evaluates the |
| 33 | +canonical Google SRE tiers from :func:`default_burn_rules` — page at 14.4× over |
| 34 | +1h (and 5m), page at 6× over 6h (and 30m), ticket at 1× over 3d (and 6h) — and |
| 35 | +fires a tier only when **both** its long and short windows exceed the |
| 36 | +threshold, which gives fast reset and few false positives. Supply your own |
| 37 | +``rules`` (``BurnRule`` list) to customise. |
| 38 | + |
| 39 | +Executor commands |
| 40 | +----------------- |
| 41 | + |
| 42 | +``AC_evaluate_slo`` takes ``records`` (a list or JSON string), a ``target`` and |
| 43 | +optional ``window_s``, and returns the SLI/budget report. ``AC_burn_alerts`` |
| 44 | +returns ``{alerts, firing}``. Both are exposed as MCP tools |
| 45 | +(``ac_evaluate_slo`` / ``ac_burn_alerts``) and as Script Builder commands under |
| 46 | +**Report**. |
0 commit comments