slo-guard 0.1.0__tar.gz

slo_guard-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,26 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+      - name: Lint
+        run: ruff check src tests
+      - name: Test
+        run: pytest --cov=slo_guard --cov-report=term-missing

slo_guard-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,24 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # required for PyPI trusted publishing
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install build tool
+        run: pip install build
+      - name: Build sdist and wheel
+        run: python -m build
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

slo_guard-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.pyc
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+build/
+dist/
+.coverage
+htmlcov/
+.venv/
+venv/
+*.egg
+.DS_Store

slo_guard-0.1.0/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+## [0.1.0] - 2026-08-29
+
+### Added
+- Core `SLO` model with error-budget and budget-remaining calculations.
+- Multi-window, multi-burn-rate policy engine (`evaluate_policy`), generalized
+  so it reproduces the standard Google SRE Workbook constants (14.4 / 6 / 1)
+  for a 99.9%/30-day SLO and scales correctly for other targets/periods.
+- Prometheus alerting rule generator (`build_alert_group`, `render_yaml`).
+- YAML-based SLO config loader.
+- CLI (`slo-guard rules`, `slo-guard budget`).
+- Full test suite (pytest) covering core math, burn-rate policy, rule
+  generation, and config loading.

slo_guard-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,42 @@
+# Contributing to slo-guard
+
+Thanks for considering a contribution! This project is small and focused,
+so contributions of any size are welcome — bug reports, docs fixes,
+new burn-rate policy presets, additional rule-generator backends
+(e.g. Datadog, Grafana Alerting), etc.
+
+## Setup
+
+```bash
+git clone https://github.com/itsmejoshi/slo-guard
+cd slo-guard
+pip install -e ".[dev]"
+```
+
+## Running tests
+
+```bash
+pytest --cov=slo_guard --cov-report=term-missing
+```
+
+## Linting
+
+```bash
+ruff check src tests
+```
+
+## Submitting changes
+
+1. Fork the repo and create a branch off `main`.
+2. Add tests for any new behavior — PRs without tests for new logic will be
+   asked to add them.
+3. Make sure `pytest` and `ruff check` pass locally.
+4. Open a PR with a clear description of the change and why it's needed.
+
+## Design principles
+
+- Keep the core math (`core.py`, `burnrate.py`) dependency-free and provable
+  from first principles — no hard-coded magic numbers.
+- Keep the library usable both as a CLI and as an importable Python API.
+- Prefer clarity over cleverness; this is infrastructure tooling that people
+  will read during an incident.

slo_guard-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sai Joshitha Kathari
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

slo_guard-0.1.0/PKG-INFO

@@ -0,0 +1,123 @@
+Metadata-Version: 2.5
+Name: slo-guard
+Version: 0.1.0
+Summary: SLO error-budget tracking and multi-window burn-rate alerting for SRE/DevOps teams
+Project-URL: Homepage, https://github.com/itsmejoshi/slo-guard
+Project-URL: Repository, https://github.com/itsmejoshi/slo-guard
+Project-URL: Issues, https://github.com/itsmejoshi/slo-guard/issues
+Author-email: Sai Joshitha Kathari <kathari.saijoshitha@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: devops,error-budget,monitoring,observability,prometheus,slo,sre
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: System :: Monitoring
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.9
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# slo-guard
+
+Error-budget tracking and **multi-window, multi-burn-rate alerting** for SRE/DevOps teams, built around the technique described in Google's *SRE Workbook* ("Alerting on SLOs").
+
+Instead of alerting the moment error rate ticks up, `slo-guard` computes how fast a service is burning its error budget relative to a uniform, budget-neutral pace — and generates ready-to-use Prometheus alerting rules from a single SLO definition.
+
+## Why burn-rate alerting?
+
+A raw "error rate > X%" alert either fires too late (averaged over a long window) or too often (noisy on a short one). Burn-rate alerting fixes this by pairing a **long window** (to size the alert against your actual error budget) with a **short window** (to confirm the problem hasn't already resolved), at multiple severities:
+
+| Window pair       | Budget consumed | Meaning                          | Typical severity |
+|--------------------|-----------------|-----------------------------------|-------------------|
+| 1h / 5m            | 2% in 1 hour    | Fast, severe burn                 | Page              |
+| 6h / 30m           | 5% in 6 hours   | Sustained, moderate burn          | Page              |
+| 3d / 6h            | 10% in 3 days   | Slow leak worth investigating     | Ticket            |
+
+The exact multipliers are derived from your SLO's target and period, not hard-coded — a 99.9%/30-day SLO reproduces the well-known 14.4 / 6 / 1 burn-rate constants automatically; other targets and periods scale correctly.
+
+## Install
+
+```bash
+pip install slo-guard
+```
+
+## Quick start
+
+**1. Define your SLO** (`slo.yaml`):
+
+```yaml
+name: checkout-availability
+target: 0.999
+period_days: 30
+error_selector: 'http_requests_total{job="checkout",code=~"5.."}'
+total_selector: 'http_requests_total{job="checkout"}'
+```
+
+**2. Generate Prometheus alerting rules:**
+
+```bash
+slo-guard rules --config slo.yaml --out checkout-rules.yml
+```
+
+**3. Check current error-budget status:**
+
+```bash
+slo-guard budget --config slo.yaml --bad-ratio 0.0015
+```
+
+```
+SLO: checkout-availability (target=99.9000%, period=30d)
+Observed bad-event ratio: 0.1500%
+Error budget consumed:    150.00%
+Error budget remaining:   -50.00%
+Remaining budget (time):  -21600.0 minutes
+STATUS: SLO VIOLATED -- error budget exhausted.
+```
+
+**4. Or use it as a library:**
+
+```python
+from slo_guard import SLO, evaluate_policy
+
+slo = SLO(name="checkout-availability", target=0.999, period_days=30)
+print(slo.budget_consumed(bad_event_ratio=0.0005))  # 0.5 (50% of budget used)
+
+for window in evaluate_policy(slo):
+    print(window["name"], window["burn_rate_threshold"])
+```
+
+## Development
+
+```bash
+git clone https://github.com/itsmejoshi/slo-guard
+cd slo-guard
+pip install -e ".[dev]"
+pytest
+```
+
+## Publishing (maintainer notes)
+
+```bash
+python -m build
+twine upload dist/*
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+## Related reading
+
+- Google SRE Workbook, ["Alerting on SLOs"](https://sre.google/workbook/alerting-on-slo/)
+- Similar tools in this space: [Pyrra](https://github.com/pyrra-dev/pyrra), [Sloth](https://github.com/slok/sloth) — `slo-guard` focuses on being a minimal, dependency-light library you can embed directly in Python tooling or CI, rather than a standalone operator.

slo_guard-0.1.0/README.md

@@ -0,0 +1,93 @@
+# slo-guard
+
+Error-budget tracking and **multi-window, multi-burn-rate alerting** for SRE/DevOps teams, built around the technique described in Google's *SRE Workbook* ("Alerting on SLOs").
+
+Instead of alerting the moment error rate ticks up, `slo-guard` computes how fast a service is burning its error budget relative to a uniform, budget-neutral pace — and generates ready-to-use Prometheus alerting rules from a single SLO definition.
+
+## Why burn-rate alerting?
+
+A raw "error rate > X%" alert either fires too late (averaged over a long window) or too often (noisy on a short one). Burn-rate alerting fixes this by pairing a **long window** (to size the alert against your actual error budget) with a **short window** (to confirm the problem hasn't already resolved), at multiple severities:
+
+| Window pair       | Budget consumed | Meaning                          | Typical severity |
+|--------------------|-----------------|-----------------------------------|-------------------|
+| 1h / 5m            | 2% in 1 hour    | Fast, severe burn                 | Page              |
+| 6h / 30m           | 5% in 6 hours   | Sustained, moderate burn          | Page              |
+| 3d / 6h            | 10% in 3 days   | Slow leak worth investigating     | Ticket            |
+
+The exact multipliers are derived from your SLO's target and period, not hard-coded — a 99.9%/30-day SLO reproduces the well-known 14.4 / 6 / 1 burn-rate constants automatically; other targets and periods scale correctly.
+
+## Install
+
+```bash
+pip install slo-guard
+```
+
+## Quick start
+
+**1. Define your SLO** (`slo.yaml`):
+
+```yaml
+name: checkout-availability
+target: 0.999
+period_days: 30
+error_selector: 'http_requests_total{job="checkout",code=~"5.."}'
+total_selector: 'http_requests_total{job="checkout"}'
+```
+
+**2. Generate Prometheus alerting rules:**
+
+```bash
+slo-guard rules --config slo.yaml --out checkout-rules.yml
+```
+
+**3. Check current error-budget status:**
+
+```bash
+slo-guard budget --config slo.yaml --bad-ratio 0.0015
+```
+
+```
+SLO: checkout-availability (target=99.9000%, period=30d)
+Observed bad-event ratio: 0.1500%
+Error budget consumed:    150.00%
+Error budget remaining:   -50.00%
+Remaining budget (time):  -21600.0 minutes
+STATUS: SLO VIOLATED -- error budget exhausted.
+```
+
+**4. Or use it as a library:**
+
+```python
+from slo_guard import SLO, evaluate_policy
+
+slo = SLO(name="checkout-availability", target=0.999, period_days=30)
+print(slo.budget_consumed(bad_event_ratio=0.0005))  # 0.5 (50% of budget used)
+
+for window in evaluate_policy(slo):
+    print(window["name"], window["burn_rate_threshold"])
+```
+
+## Development
+
+```bash
+git clone https://github.com/itsmejoshi/slo-guard
+cd slo-guard
+pip install -e ".[dev]"
+pytest
+```
+
+## Publishing (maintainer notes)
+
+```bash
+python -m build
+twine upload dist/*
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+## Related reading
+
+- Google SRE Workbook, ["Alerting on SLOs"](https://sre.google/workbook/alerting-on-slo/)
+- Similar tools in this space: [Pyrra](https://github.com/pyrra-dev/pyrra), [Sloth](https://github.com/slok/sloth) — `slo-guard` focuses on being a minimal, dependency-light library you can embed directly in Python tooling or CI, rather than a standalone operator.

slo_guard-0.1.0/examples/slo.yaml

@@ -0,0 +1,10 @@
+# Example SLO definition for slo-guard.
+# Copy this file, rename it, and adjust the selectors to match your metrics.
+
+name: checkout-availability
+target: 0.999          # 99.9% of requests must succeed
+period_days: 30         # rolling 30-day compliance window
+
+# PromQL selectors used to compute the bad-event ratio.
+error_selector: 'http_requests_total{job="checkout",code=~"5.."}'
+total_selector: 'http_requests_total{job="checkout"}'

slo_guard-0.1.0/pyproject.toml

@@ -0,0 +1,55 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "slo-guard"
+version = "0.1.0"
+description = "SLO error-budget tracking and multi-window burn-rate alerting for SRE/DevOps teams"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.9"
+authors = [
+    { name = "Sai Joshitha Kathari", email = "kathari.saijoshitha@gmail.com" }
+]
+keywords = ["sre", "slo", "observability", "prometheus", "monitoring", "devops", "error-budget"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Intended Audience :: System Administrators",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: System :: Monitoring",
+    "Topic :: System :: Systems Administration",
+]
+dependencies = [
+    "PyYAML>=6.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "pytest-cov>=4.0",
+    "ruff>=0.4",
+]
+
+[project.urls]
+Homepage = "https://github.com/itsmejoshi/slo-guard"
+Repository = "https://github.com/itsmejoshi/slo-guard"
+Issues = "https://github.com/itsmejoshi/slo-guard/issues"
+
+[project.scripts]
+slo-guard = "slo_guard.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/slo_guard"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100

slo_guard-0.1.0/src/slo_guard/__init__.py

@@ -0,0 +1,28 @@
+"""slo-guard: SLO error-budget tracking and multi-window burn-rate alerting.
+
+Quick start:
+
+    from slo_guard import SLO, evaluate_policy
+
+    slo = SLO(name="checkout-availability", target=0.999, period_days=30)
+    print(slo.budget_consumed(bad_event_ratio=0.0015))
+    print(evaluate_policy(slo))
+"""
+from .burnrate import DEFAULT_POLICY, BurnRateWindow, evaluate_policy
+from .config import SLOConfig, load_config
+from .core import SLO
+from .rules import build_alert_group, render_yaml
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "DEFAULT_POLICY",
+    "SLO",
+    "BurnRateWindow",
+    "SLOConfig",
+    "__version__",
+    "build_alert_group",
+    "evaluate_policy",
+    "load_config",
+    "render_yaml",
+]

slo_guard-0.1.0/src/slo_guard/burnrate.py

@@ -0,0 +1,111 @@
+"""Multi-window, multi-burn-rate alert threshold calculations.
+
+Based on the technique described in the Google SRE Workbook chapter
+"Alerting on SLOs": rather than alerting on raw error ratio, alert on the
+*rate* at which the error budget is being burned relative to a constant,
+budget-neutral pace over the SLO period. A short window catches fast burns
+quickly; a long window (paired with the same threshold) filters out noise
+from brief blips, so both must fire together for a page-worthy alert.
+
+This module computes the burn-rate threshold for an arbitrary window size
+and SLO period from first principles, rather than hard-coding the constants
+(14.4, 6, 1, ...) that appear in the workbook for the 99.9%/30-day case --
+those fall out of this formula automatically.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .core import SLO
+
+
+@dataclass(frozen=True)
+class BurnRateWindow:
+    """One entry in a multi-window alerting policy.
+
+    Attributes:
+        name: Short label, e.g. "fast", "medium", "slow".
+        long_window_hours: The long lookback window, in hours.
+        short_window_hours: The short lookback window, in hours (used to
+            confirm the alert has not already recovered).
+        budget_fraction: Fraction of the *total* error budget this window is
+            allowed to consume before paging, e.g. 0.02 for "2% of budget".
+        for_duration_minutes: How long the condition must hold before firing,
+            to suppress flapping.
+        severity: Free-text severity label, e.g. "page" or "ticket".
+    """
+
+    name: str
+    long_window_hours: float
+    short_window_hours: float
+    budget_fraction: float
+    for_duration_minutes: float
+    severity: str = "page"
+
+    def burn_rate_threshold(self, slo: SLO) -> float:
+        """The burn-rate multiplier that exhausts `budget_fraction` of the
+        error budget in exactly `long_window_hours`.
+
+        burn_rate = budget_fraction / (long_window / period)
+
+        A burn rate of 1.0 means "consuming the budget at exactly the
+        uniform pace needed to exhaust it right at the end of the period".
+        A burn rate of 14.4 means consuming it 14.4x faster than that.
+        """
+        period_hours = slo.period_days * 24
+        window_fraction_of_period = self.long_window_hours / period_hours
+        return self.budget_fraction / window_fraction_of_period
+
+
+# The canonical 3-window policy from the SRE Workbook, generalized so it
+# still produces the well-known 14.4 / 6 / 1 multipliers for a 99.9%/30-day
+# SLO, but adapts correctly to any other target or period.
+DEFAULT_POLICY: tuple[BurnRateWindow, ...] = (
+    BurnRateWindow(
+        name="fast",
+        long_window_hours=1,
+        short_window_hours=5 / 60,
+        budget_fraction=0.02,
+        for_duration_minutes=2,
+        severity="page",
+    ),
+    BurnRateWindow(
+        name="medium",
+        long_window_hours=6,
+        short_window_hours=0.5,
+        budget_fraction=0.05,
+        for_duration_minutes=15,
+        severity="page",
+    ),
+    BurnRateWindow(
+        name="slow",
+        long_window_hours=72,
+        short_window_hours=6,
+        budget_fraction=0.10,
+        for_duration_minutes=60,
+        severity="ticket",
+    ),
+)
+
+
+def evaluate_policy(
+    slo: SLO, policy: tuple[BurnRateWindow, ...] = DEFAULT_POLICY
+) -> list[dict]:
+    """Resolve a policy into concrete thresholds for a given SLO.
+
+    Returns a list of dicts (one per window) ready to feed into a rules
+    generator or to print as a report.
+    """
+    results = []
+    for window in policy:
+        results.append(
+            {
+                "name": window.name,
+                "long_window_hours": window.long_window_hours,
+                "short_window_hours": window.short_window_hours,
+                "burn_rate_threshold": window.burn_rate_threshold(slo),
+                "for_duration_minutes": window.for_duration_minutes,
+                "severity": window.severity,
+            }
+        )
+    return results

slo_guard-0.1.0/src/slo_guard/cli.py

@@ -0,0 +1,67 @@
+"""Command-line interface for slo-guard.
+
+Usage:
+    slo-guard rules --config examples/slo.yaml --out rules.yml
+    slo-guard budget --config examples/slo.yaml --bad-ratio 0.0015
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+
+from .config import load_config
+from .rules import render_yaml
+
+
+def _cmd_rules(args: argparse.Namespace) -> int:
+    cfg = load_config(args.config)
+    text = render_yaml(cfg.slo, cfg.error_selector, cfg.total_selector)
+    if args.out:
+        with open(args.out, "w", encoding="utf-8") as fh:
+            fh.write(text)
+        print(f"Wrote Prometheus rules to {args.out}")
+    else:
+        print(text)
+    return 0
+
+
+def _cmd_budget(args: argparse.Namespace) -> int:
+    cfg = load_config(args.config)
+    slo = cfg.slo
+    consumed = slo.budget_consumed(args.bad_ratio)
+    remaining = slo.budget_remaining(args.bad_ratio)
+    remaining_minutes = slo.budget_remaining_minutes(args.bad_ratio)
+
+    print(f"SLO: {slo.name} (target={slo.target:.4%}, period={slo.period_days}d)")
+    print(f"Observed bad-event ratio: {args.bad_ratio:.4%}")
+    print(f"Error budget consumed:    {consumed:.2%}")
+    print(f"Error budget remaining:   {remaining:.2%}")
+    print(f"Remaining budget (time):  {remaining_minutes:.1f} minutes")
+    if remaining < 0:
+        print("STATUS: SLO VIOLATED -- error budget exhausted.", file=sys.stderr)
+        return 1
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="slo-guard")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p_rules = sub.add_parser("rules", help="Generate Prometheus burn-rate alert rules")
+    p_rules.add_argument("--config", required=True, help="Path to SLO YAML config")
+    p_rules.add_argument("--out", help="Output file (default: stdout)")
+    p_rules.set_defaults(func=_cmd_rules)
+
+    p_budget = sub.add_parser("budget", help="Report current error-budget status")
+    p_budget.add_argument("--config", required=True, help="Path to SLO YAML config")
+    p_budget.add_argument(
+        "--bad-ratio", required=True, type=float, help="Observed bad-event ratio, e.g. 0.0015"
+    )
+    p_budget.set_defaults(func=_cmd_budget)
+
+    args = parser.parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

slo_guard-0.1.0/src/slo_guard/config.py

@@ -0,0 +1,46 @@
+"""Load SLO definitions from a YAML config file.
+
+Example config file (see examples/slo.yaml):
+
+    name: checkout-availability
+    target: 0.999
+    period_days: 30
+    error_selector: 'http_requests_total{job="checkout",code=~"5.."}'
+    total_selector: 'http_requests_total{job="checkout"}'
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+import yaml
+
+from .core import SLO
+
+
+@dataclass(frozen=True)
+class SLOConfig:
+    slo: SLO
+    error_selector: str
+    total_selector: str
+
+
+def load_config(path: str | Path) -> SLOConfig:
+    with open(path, "r", encoding="utf-8") as fh:
+        data = yaml.safe_load(fh)
+
+    required = {"name", "target", "error_selector", "total_selector"}
+    missing = required - data.keys()
+    if missing:
+        raise ValueError(f"Missing required config keys: {sorted(missing)}")
+
+    slo = SLO(
+        name=data["name"],
+        target=float(data["target"]),
+        period_days=int(data.get("period_days", 30)),
+    )
+    return SLOConfig(
+        slo=slo,
+        error_selector=data["error_selector"],
+        total_selector=data["total_selector"],
+    )

slo_guard-0.1.0/src/slo_guard/core.py

@@ -0,0 +1,62 @@
+"""Core SLO and error-budget math.
+
+Implements the error-budget model described in the Google SRE Workbook
+("Implementing SLOs" and "Alerting on SLOs" chapters): an SLO defines an
+acceptable ratio of bad events over a rolling period; the error budget is
+the complementary "allowance" of bad events; and burn rate measures how
+quickly that allowance is being consumed relative to a uniform, budget-neutral
+pace.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class SLO:
+    """A single Service Level Objective.
+
+    Attributes:
+        name: Human-readable identifier, e.g. "checkout-availability".
+        target: The objective as a fraction, e.g. 0.999 for "99.9%".
+        period_days: Rolling compliance window in days (commonly 28 or 30).
+    """
+
+    name: str
+    target: float
+    period_days: int = 30
+
+    def __post_init__(self) -> None:
+        if not (0 < self.target < 1):
+            raise ValueError(f"target must be between 0 and 1, got {self.target}")
+        if self.period_days <= 0:
+            raise ValueError(f"period_days must be positive, got {self.period_days}")
+
+    @property
+    def error_budget(self) -> float:
+        """Fraction of events allowed to be 'bad' over the period."""
+        return 1.0 - self.target
+
+    def budget_consumed(self, bad_event_ratio: float) -> float:
+        """Fraction of the total error budget consumed so far.
+
+        Args:
+            bad_event_ratio: Observed ratio of bad events over the period
+                (e.g. 5xx responses / total responses), between 0 and 1.
+
+        Returns:
+            0.0 means no budget spent; 1.0 means the budget is exhausted;
+            values above 1.0 mean the SLO has already been violated.
+        """
+        if not (0 <= bad_event_ratio <= 1):
+            raise ValueError("bad_event_ratio must be between 0 and 1")
+        return bad_event_ratio / self.error_budget
+
+    def budget_remaining(self, bad_event_ratio: float) -> float:
+        """Fraction of error budget remaining (can go negative if exhausted)."""
+        return 1.0 - self.budget_consumed(bad_event_ratio)
+
+    def budget_remaining_minutes(self, bad_event_ratio: float) -> float:
+        """Convenience: remaining budget expressed in minutes of the period."""
+        total_minutes = self.period_days * 24 * 60
+        return self.budget_remaining(bad_event_ratio) * total_minutes

slo_guard-0.1.0/src/slo_guard/rules.py

@@ -0,0 +1,89 @@
+"""Render burn-rate policies as Prometheus alerting rule YAML."""
+from __future__ import annotations
+
+from typing import Any
+
+import yaml
+
+from .burnrate import DEFAULT_POLICY, BurnRateWindow, evaluate_policy
+from .core import SLO
+
+
+def _hours_to_promql_duration(hours: float) -> str:
+    """Format an hour count as a Prometheus duration string."""
+    if hours < 1:
+        minutes = round(hours * 60)
+        return f"{minutes}m"
+    if hours == int(hours):
+        return f"{int(hours)}h"
+    return f"{hours}h"
+
+
+def _ratio_expr(window_str: str, error_selector: str, total_selector: str) -> str:
+    """Build a PromQL expression for the bad-event ratio over a window."""
+    return (
+        f"(sum(rate({error_selector}[{window_str}])) / "
+        f"sum(rate({total_selector}[{window_str}])))"
+    )
+
+
+def build_alert_group(
+    slo: SLO,
+    error_selector: str,
+    total_selector: str,
+    policy: tuple[BurnRateWindow, ...] = DEFAULT_POLICY,
+    extra_labels: dict[str, str] | None = None,
+) -> dict[str, Any]:
+    """Build a single Prometheus rule group for an SLO's burn-rate alerts.
+
+    Args:
+        slo: The SLO the alerts protect.
+        error_selector: PromQL selector for "bad" events, e.g.
+            'http_requests_total{job="checkout",code=~"5.."}'.
+        total_selector: PromQL selector for all events, e.g.
+            'http_requests_total{job="checkout"}'.
+        policy: The burn-rate windows to alert on.
+        extra_labels: Additional labels merged into every alert rule.
+    """
+    thresholds = evaluate_policy(slo, policy)
+    rules = []
+    for window, threshold in zip(policy, thresholds):
+        long_w = _hours_to_promql_duration(window.long_window_hours)
+        short_w = _hours_to_promql_duration(window.short_window_hours)
+        long_expr = _ratio_expr(long_w, error_selector, total_selector)
+        short_expr = _ratio_expr(short_w, error_selector, total_selector)
+        burn_threshold = threshold["burn_rate_threshold"] * slo.error_budget
+
+        expr = f"{long_expr} > {burn_threshold:.6g} and {short_expr} > {burn_threshold:.6g}"
+
+        labels = {"severity": window.severity, "slo": slo.name}
+        if extra_labels:
+            labels.update(extra_labels)
+
+        rules.append(
+            {
+                "alert": f"{slo.name}_burn_rate_{window.name}",
+                "expr": expr,
+                "for": f"{int(window.for_duration_minutes)}m",
+                "labels": labels,
+                "annotations": {
+                    "summary": (
+                        f"{slo.name}: burning error budget >{threshold['burn_rate_threshold']:.1f}x "
+                        f"over {long_w} (confirmed over {short_w})"
+                    ),
+                    "description": (
+                        f"Error ratio over {long_w} and {short_w} both exceed the "
+                        f"budget-neutral threshold for the {slo.target:.4%} / "
+                        f"{slo.period_days}d SLO. Severity: {window.severity}."
+                    ),
+                },
+            }
+        )
+
+    return {"groups": [{"name": f"{slo.name}-burn-rate", "rules": rules}]}
+
+
+def render_yaml(slo: SLO, error_selector: str, total_selector: str, **kwargs) -> str:
+    """Convenience wrapper: build the alert group and dump it as YAML text."""
+    group = build_alert_group(slo, error_selector, total_selector, **kwargs)
+    return yaml.dump(group, sort_keys=False, default_flow_style=False)

slo_guard-0.1.0/sre-playbook/incident-response.md

@@ -0,0 +1,43 @@
+# Incident Response Runbook
+
+## Severity levels
+
+| Level | Definition | Examples | Response |
+|-------|------------|----------|----------|
+| SEV1 | Full outage or data loss affecting all/most users | Site down, payments failing globally, data corruption | Page on-call immediately, open incident channel, notify leadership within 15 min |
+| SEV2 | Significant degradation affecting a subset of users or a core feature | Elevated error rate on checkout, regional outage, major feature broken | Page on-call, open incident channel within 15 min |
+| SEV3 | Minor issue, workaround available, limited user impact | Non-critical feature degraded, isolated errors | Ticket + fix during business hours, no page |
+| SEV4 | Cosmetic or negligible impact | UI glitch, log noise | Backlog |
+
+## Roles during an incident
+
+- **Incident Commander (IC):** Owns the response. Coordinates, makes calls, does not personally debug.
+- **Communications Lead:** Owns status page updates and stakeholder comms so the IC and responders can focus on mitigation.
+- **Subject Matter Expert(s) (SMEs):** Debug and mitigate. Report status to the IC, don't self-direct comms.
+
+Small teams can combine IC + Comms; never combine IC + primary debugger on a SEV1/SEV2 — the person mitigating shouldn't also be fielding Slack questions.
+
+## Response sequence
+
+1. **Acknowledge.** Ack the page within the on-call SLA (commonly 5 minutes). Silence is the worst signal you can send.
+2. **Assess and declare.** Confirm real impact (check dashboards/SLO burn-rate alerts, not just the page text), assign a severity, and declare the incident in the incident channel/tool.
+3. **Stabilize before you diagnose.** If a recent deploy or config change correlates with the start of the incident, roll it back first and investigate root cause after service is restored. Mitigation beats explanation during an active incident.
+4. **Communicate on a cadence.** Post an update at a fixed interval (e.g. every 30 minutes for SEV1) even if the update is "still investigating, no new info" — silence reads as "IC lost control."
+5. **Confirm recovery.** Watch the relevant SLO/error-budget burn-rate alert clear (not just "error rate looks lower") before declaring resolved; burn-rate alerts are designed to require confirmation over a second window precisely to avoid premature all-clears.
+6. **Resolve and schedule the postmortem.** Resolving the page is not resolving the incident — schedule the postmortem within 1-2 business days while memory is fresh.
+
+## Using burn-rate alerts during an incident
+
+Multi-window burn-rate alerts (see `slo-guard`) are designed to answer two questions responders always ask:
+
+- **"How bad is this, really?"** — the burn-rate multiplier tells you how many times faster than "acceptable" the service is failing, independent of raw error-rate noise.
+- **"Is it actually over?"** — because the alert requires both a long window and a short window to clear, a flapping recovery won't falsely signal "all clear."
+
+If only the fast-burn (short-window) alert is firing and the slow-burn one is not, the issue is likely new and acute. If the slow-burn alert is firing but fast-burn is not, you likely have a longer-running, lower-grade leak worth a ticket rather than an all-hands page.
+
+## Anti-patterns to avoid
+
+- Debugging in the incident channel with no IC — it becomes noise no one can follow.
+- Making the on-call engineer also write the customer-facing status update during a SEV1.
+- Declaring resolution the instant the error graph dips, without waiting for the burn-rate confirmation window.
+- Skipping the postmortem because "we know what happened" — the point is the process, not just the notes.

slo_guard-0.1.0/sre-playbook/oncall-escalation.md

@@ -0,0 +1,31 @@
+# On-Call & Escalation Guide
+
+## On-call expectations
+
+- **Ack SLA:** acknowledge a page within 5 minutes during on-call hours.
+- **Handoff:** primary on-call reviews open incidents, muted alerts, and any in-flight action items with the incoming on-call at shift change. A handoff with no verbal/written summary is not a handoff.
+- **Alert fatigue is a bug, not a fact of life.** If an alert fires and the response is consistently "ignore it," fix or delete the alert — don't normalize ignoring pages. Multi-window burn-rate alerting (long + short window agreement) exists specifically to cut this kind of noise; a page-worthy alert should page rarely and mean something when it does.
+
+## Escalation path
+
+1. **Primary on-call** — first responder, owns triage and initial mitigation.
+2. **Secondary on-call** — paged automatically if primary doesn't ack within the SLA, or pulled in by primary for a second pair of hands on a SEV1/SEV2.
+3. **Team lead / EM** — looped in for SEV1, for incidents needing cross-team coordination, or for customer-impacting incidents needing executive comms.
+4. **Incident Commander pool** (for orgs with a dedicated IC rotation) — takes the IC role for SEV1 so the primary responder can stay heads-down on mitigation.
+
+Escalate early. Pulling in a second person 10 minutes into a SEV1 that resolves in 5 more minutes costs little; waiting 45 minutes to escalate a SEV1 that needed a second team from the start costs a lot.
+
+## Alert -> action mapping
+
+| Alert type | What it means | First action |
+|------------|----------------|--------------|
+| Fast-burn (short+long window, high multiplier) | Severe, acute error-budget burn | Page immediately, treat as candidate SEV1/SEV2, check recent deploys first |
+| Medium-burn | Sustained, moderate burn | Page, investigate within the hour |
+| Slow-burn | Slow leak over days | Ticket, no page; review during business hours |
+| Single-window-only fast alert (long window not yet confirmed) | Possible early signal or noise | Watch, don't page yet — this is why multi-window exists |
+
+## Runbook hygiene
+
+- Every alert should link to a runbook (or explicitly note "no runbook needed, self-explanatory").
+- Runbooks should be reviewed whenever the underlying service's architecture changes materially — a stale runbook during an incident is worse than no runbook, because it costs time to discover it's wrong.
+- Keep runbooks in version control alongside the alerting rules that reference them, so they change together.

slo_guard-0.1.0/sre-playbook/postmortem-template.md

@@ -0,0 +1,64 @@
+# Postmortem: [Incident Title]
+
+**Date of incident:** YYYY-MM-DD
+**Severity:** SEV1 / SEV2 / SEV3
+**Duration:** HH:MM (start) — HH:MM (resolved)
+**Authors:** [names]
+**Status:** Draft / In review / Final
+
+> This is a **blameless** postmortem. The goal is to understand systemic
+> conditions that allowed the incident to happen, not to assign fault to
+> an individual. Assume everyone involved made reasonable decisions given
+> what they knew at the time.
+
+## Summary
+
+One paragraph: what broke, who/what was affected, how it was resolved.
+
+## Impact
+
+- Users/requests affected (rough %, or absolute count if known)
+- Error budget consumed (reference the relevant SLO and burn-rate alert that fired)
+- Revenue/SLA impact if applicable
+- Duration of user-visible impact vs. total incident duration
+
+## Timeline
+
+All times in UTC.
+
+| Time | Event |
+|------|-------|
+| 14:02 | Deploy of service X v1.4.2 begins |
+| 14:05 | Fast-burn alert fires for `checkout-availability` SLO |
+| 14:07 | On-call acknowledges page |
+| 14:12 | IC declared, incident channel opened |
+| 14:20 | Root cause identified as v1.4.2 config regression |
+| 14:23 | Rollback initiated |
+| 14:31 | Burn-rate alert clears (both windows) |
+| 14:35 | Incident resolved |
+
+## Root cause
+
+What was the actual mechanism of failure? Go one or two levels past the immediate trigger — "a bad deploy" is a trigger, not a root cause; "the deploy pipeline had no automated check for X" is closer to root cause.
+
+## What went well
+
+- Concrete, specific things — not "good communication" but "IC posted updates every 15 minutes, which kept stakeholders from pinging individually."
+
+## What went poorly
+
+- Concrete, specific things — e.g. "the burn-rate alert fired but the runbook link in the alert annotation was stale."
+
+## Where we got lucky
+
+Things that could have made this worse but didn't, by chance rather than by design. Worth turning into real safeguards.
+
+## Action items
+
+| Action | Owner | Priority | Ticket |
+|--------|-------|----------|--------|
+| Add automated config validation to deploy pipeline | @owner | P1 | LINK |
+| Update runbook link in alert annotation | @owner | P2 | LINK |
+| Add canary stage before full rollout | @owner | P1 | LINK |
+
+Every action item needs an owner and a ticket — "we should be more careful" is not an action item.

slo_guard-0.1.0/tests/test_burnrate.py

@@ -0,0 +1,63 @@
+import pytest
+
+from slo_guard.burnrate import DEFAULT_POLICY, evaluate_policy
+from slo_guard.core import SLO
+
+
+def test_default_policy_matches_known_constants_for_999_30d():
+    """For a 99.9% / 30-day SLO, the default policy should reproduce the
+    well-known 14.4 / 6 / 1 burn-rate multipliers from the Google SRE
+    Workbook's 'Alerting on SLOs' chapter."""
+    slo = SLO(name="checkout", target=0.999, period_days=30)
+    results = {r["name"]: r["burn_rate_threshold"] for r in evaluate_policy(slo)}
+
+    assert results["fast"] == pytest.approx(14.4, rel=1e-9)
+    assert results["medium"] == pytest.approx(6.0, rel=1e-9)
+    assert results["slow"] == pytest.approx(1.0, rel=1e-9)
+
+
+def test_burn_rate_scales_with_different_period():
+    """A 90-day period should scale burn-rate thresholds proportionally
+    (same budget fraction consumed in the same window is a faster burn
+    relative to a longer total period)."""
+    slo_30 = SLO(name="a", target=0.999, period_days=30)
+    slo_90 = SLO(name="b", target=0.999, period_days=90)
+
+    fast_30 = evaluate_policy(slo_30)[0]["burn_rate_threshold"]
+    fast_90 = evaluate_policy(slo_90)[0]["burn_rate_threshold"]
+
+    assert fast_90 == pytest.approx(fast_30 * 3, rel=1e-9)
+
+
+def test_burn_rate_scales_with_different_target():
+    """A looser target (larger error budget) means the same window burns a
+    smaller fraction of a bigger budget for the same multiplier -- so at a
+    fixed budget_fraction, the multiplier itself is independent of target;
+    it only depends on window/period. This test locks in that invariant."""
+    slo_tight = SLO(name="tight", target=0.999, period_days=30)
+    slo_loose = SLO(name="loose", target=0.99, period_days=30)
+
+    thresholds_tight = [r["burn_rate_threshold"] for r in evaluate_policy(slo_tight)]
+    thresholds_loose = [r["burn_rate_threshold"] for r in evaluate_policy(slo_loose)]
+
+    assert thresholds_tight == pytest.approx(thresholds_loose)
+
+
+def test_policy_windows_ordered_fast_to_slow():
+    windows = [w.long_window_hours for w in DEFAULT_POLICY]
+    assert windows == sorted(windows)
+
+
+def test_evaluate_policy_returns_all_fields():
+    slo = SLO(name="x", target=0.995, period_days=28)
+    results = evaluate_policy(slo)
+    assert len(results) == len(DEFAULT_POLICY)
+    for r in results:
+        assert set(r.keys()) == {
+            "name",
+            "long_window_hours",
+            "short_window_hours",
+            "burn_rate_threshold",
+            "for_duration_minutes",
+            "severity",
+        }

slo_guard-0.1.0/tests/test_config.py

@@ -0,0 +1,48 @@
+import textwrap
+
+import pytest
+
+from slo_guard.config import load_config
+
+
+def _write_config(tmp_path, content):
+    path = tmp_path / "slo.yaml"
+    path.write_text(textwrap.dedent(content))
+    return path
+
+
+def test_load_valid_config(tmp_path):
+    path = _write_config(
+        tmp_path,
+        """
+        name: checkout-availability
+        target: 0.999
+        period_days: 30
+        error_selector: 'http_requests_total{job="checkout",code=~"5.."}'
+        total_selector: 'http_requests_total{job="checkout"}'
+        """,
+    )
+    cfg = load_config(path)
+    assert cfg.slo.name == "checkout-availability"
+    assert cfg.slo.target == pytest.approx(0.999)
+    assert cfg.slo.period_days == 30
+
+
+def test_load_config_defaults_period_days(tmp_path):
+    path = _write_config(
+        tmp_path,
+        """
+        name: x
+        target: 0.99
+        error_selector: 'a'
+        total_selector: 'b'
+        """,
+    )
+    cfg = load_config(path)
+    assert cfg.slo.period_days == 30
+
+
+def test_load_config_missing_keys_raises(tmp_path):
+    path = _write_config(tmp_path, "name: x\ntarget: 0.99\n")
+    with pytest.raises(ValueError):
+        load_config(path)

slo_guard-0.1.0/tests/test_core.py

@@ -0,0 +1,49 @@
+import pytest
+
+from slo_guard.core import SLO
+
+
+def test_error_budget():
+    slo = SLO(name="test", target=0.999, period_days=30)
+    assert slo.error_budget == pytest.approx(0.001)
+
+
+def test_budget_consumed_half():
+    slo = SLO(name="test", target=0.999, period_days=30)
+    # Half the budget: bad ratio = error_budget / 2
+    assert slo.budget_consumed(0.0005) == pytest.approx(0.5)
+
+
+def test_budget_remaining():
+    slo = SLO(name="test", target=0.99, period_days=30)
+    assert slo.budget_remaining(0.0) == pytest.approx(1.0)
+    assert slo.budget_remaining(0.01) == pytest.approx(0.0)
+
+
+def test_budget_exhausted_goes_negative():
+    slo = SLO(name="test", target=0.99, period_days=30)
+    assert slo.budget_remaining(0.02) < 0
+
+
+def test_budget_remaining_minutes():
+    slo = SLO(name="test", target=0.999, period_days=30)
+    total_minutes = 30 * 24 * 60
+    assert slo.budget_remaining_minutes(0.0) == pytest.approx(total_minutes)
+
+
+@pytest.mark.parametrize("bad_ratio", [-0.1, 1.1])
+def test_invalid_bad_ratio_raises(bad_ratio):
+    slo = SLO(name="test", target=0.999)
+    with pytest.raises(ValueError):
+        slo.budget_consumed(bad_ratio)
+
+
+@pytest.mark.parametrize("target", [0.0, 1.0, -0.5, 1.5])
+def test_invalid_target_raises(target):
+    with pytest.raises(ValueError):
+        SLO(name="test", target=target)
+
+
+def test_invalid_period_raises():
+    with pytest.raises(ValueError):
+        SLO(name="test", target=0.99, period_days=0)

slo_guard-0.1.0/tests/test_rules.py

@@ -0,0 +1,56 @@
+import yaml
+
+from slo_guard.core import SLO
+from slo_guard.rules import build_alert_group, render_yaml
+
+ERROR_SEL = 'http_requests_total{job="checkout",code=~"5.."}'
+TOTAL_SEL = 'http_requests_total{job="checkout"}'
+
+
+def test_build_alert_group_structure():
+    slo = SLO(name="checkout-availability", target=0.999, period_days=30)
+    group = build_alert_group(slo, ERROR_SEL, TOTAL_SEL)
+
+    assert "groups" in group
+    assert len(group["groups"]) == 1
+    rules = group["groups"][0]["rules"]
+    assert len(rules) == 3
+    names = {r["alert"] for r in rules}
+    assert names == {
+        "checkout-availability_burn_rate_fast",
+        "checkout-availability_burn_rate_medium",
+        "checkout-availability_burn_rate_slow",
+    }
+
+
+def test_alert_expr_contains_selectors_and_and_clause():
+    slo = SLO(name="checkout-availability", target=0.999, period_days=30)
+    group = build_alert_group(slo, ERROR_SEL, TOTAL_SEL)
+    rule = group["groups"][0]["rules"][0]
+    assert ERROR_SEL in rule["expr"]
+    assert TOTAL_SEL in rule["expr"]
+    assert " and " in rule["expr"]
+
+
+def test_alert_labels_include_severity_and_slo():
+    slo = SLO(name="checkout-availability", target=0.999, period_days=30)
+    group = build_alert_group(slo, ERROR_SEL, TOTAL_SEL)
+    for rule in group["groups"][0]["rules"]:
+        assert rule["labels"]["slo"] == "checkout-availability"
+        assert rule["labels"]["severity"] in {"page", "ticket"}
+
+
+def test_render_yaml_is_valid_yaml_and_roundtrips():
+    slo = SLO(name="checkout-availability", target=0.999, period_days=30)
+    text = render_yaml(slo, ERROR_SEL, TOTAL_SEL)
+    parsed = yaml.safe_load(text)
+    assert parsed["groups"][0]["name"] == "checkout-availability-burn-rate"
+
+
+def test_extra_labels_are_merged():
+    slo = SLO(name="checkout-availability", target=0.999, period_days=30)
+    group = build_alert_group(
+        slo, ERROR_SEL, TOTAL_SEL, extra_labels={"team": "payments"}
+    )
+    for rule in group["groups"][0]["rules"]:
+        assert rule["labels"]["team"] == "payments"