SLOs and Error Budgets skill for Codex

Gives the Codex app a display name, a one-line description and a starter prompt for this skill.

interface:
  display_name: "SLOs and Error Budgets"
  short_description: "Targets users feel, alerts on burn rate"
  default_prompt: "$slo-error-budgets Define SLOs for our checkout API and generate burn-rate alerts in Prometheus"

#!/usr/bin/env python3
"""Error-budget arithmetic and multiwindow burn-rate Prometheus rules for one SLO.

Examples:
  python3 scripts/burn_rate.py --target 99.9 --window-days 30
  python3 scripts/burn_rate.py --target 99.9 --name checkout_availability \
      --errors 'sum(rate(http_requests_total{service="checkout",code=~"5.."}[{w}]))' \
      --total  'sum(rate(http_requests_total{service="checkout"}[{w}]))' > slo-rules.yml

{w} in --errors/--total is replaced by each window (5m, 30m, 1h, 6h, 3d).
Standard library only. Exits 2 on bad input.
"""
import argparse
import sys

# (severity, long window, short window, burn rate, budget fraction consumed when it fires)
POLICY = [
    ("page", "1h", "5m", 14.4, 0.02),
    ("page", "6h", "30m", 6.0, 0.05),
    ("ticket", "3d", "6h", 1.0, 0.10),
]


def human(minutes: float) -> str:
    if minutes >= 1440:
        return f"{minutes / 1440:.1f} days"
    if minutes >= 60:
        return f"{minutes / 60:.1f} hours"
    if minutes >= 1:
        return f"{minutes:.1f} minutes"
    return f"{minutes * 60:.0f} seconds"


def summary(target: float, days: int) -> str:
    budget = 1 - target / 100
    window_min = days * 1440
    lines = [
        f"SLO target: {target}% over {days} days",
        f"Error budget: {budget:.5%} of events = {human(budget * window_min)} of full outage",
        "",
        f"{'severity':8} {'long':>5} {'short':>6} {'burn':>6} {'error-ratio threshold':>22} {'budget used':>12} {'time to exhaust':>16}",
    ]
    for sev, long_w, short_w, rate, frac in POLICY:
        lines.append(
            f"{sev:8} {long_w:>5} {short_w:>6} {rate:>6.1f} {rate * budget:>22.5%} {frac:>12.0%} {human(window_min / rate):>16}"
        )
    return "\n".join(lines)


def rules(name: str, target: float, errors: str, total: str) -> str:
    budget = 1 - target / 100
    windows = sorted({w for _, l, s, _, _ in POLICY for w in (l, s)}, key=lambda w: {"m": 1, "h": 60, "d": 1440}[w[-1]] * int(w[:-1]))
    out = ["groups:", f"  - name: slo-{name}-recording", "    rules:"]
    for w in windows:
        out += [
            f"      - record: slo:{name}:error_ratio_rate{w}",
            "        expr: |",
            f"          ({errors.replace('{w}', w)})",
            "          /",
            f"          ({total.replace('{w}', w)})",
        ]
    out += [f"  - name: slo-{name}-alerts", "    rules:"]
    for sev, long_w, short_w, rate, frac in POLICY:
        thr = f"{rate} * {budget:.6g}"
        out += [
            f"      - alert: {''.join(p.capitalize() for p in name.split('_'))}BudgetBurn{long_w}",
            "        expr: |",
            f"          slo:{name}:error_ratio_rate{long_w} > ({thr})",
            "          and",
            f"          slo:{name}:error_ratio_rate{short_w} > ({thr})",
            f"        for: {'2m' if sev == 'page' else '15m'}",
            "        labels:",
            f"          severity: {sev}",
            f"          slo: {name}",
            "        annotations:",
            f'          summary: "{name}: burning error budget at {rate}x ({frac:.0%} of {target}% budget in {long_w})"',
            '          runbook_url: "TODO: link the runbook for this SLO"',
        ]
    return "\n".join(out) + "\n"


def main() -> int:
    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
    ap.add_argument("--target", type=float, required=True, help="SLO target in percent, e.g. 99.9")
    ap.add_argument("--window-days", type=int, default=30)
    ap.add_argument("--name", help="snake_case SLO name; with --errors/--total prints Prometheus rules")
    ap.add_argument("--errors", help="PromQL for bad-event rate, with {w} for the window")
    ap.add_argument("--total", help="PromQL for all-event rate, with {w} for the window")
    a = ap.parse_args()
    if not 0 < a.target < 100:
        print("error: --target must be between 0 and 100 (exclusive)", file=sys.stderr)
        return 2
    if a.window_days <= 0:
        print("error: --window-days must be positive", file=sys.stderr)
        return 2
    want_rules = any([a.name, a.errors, a.total])
    if want_rules and not all([a.name, a.errors, a.total]):
        print("error: --name, --errors and --total must be given together", file=sys.stderr)
        return 2
    if want_rules:
        if "{w}" not in a.errors or "{w}" not in a.total:
            print("error: --errors and --total must contain {w}", file=sys.stderr)
            return 2
        print(rules(a.name, a.target, a.errors, a.total), end="")
        print("# " + summary(a.target, a.window_days).replace("\n", "\n# "), file=sys.stderr)
    else:
        print(summary(a.target, a.window_days))
    return 0


if __name__ == "__main__":
    sys.exit(main())