Alert Runbooks

Operator-facing runbooks для каждого alert правила из tools/observability/alerts/angarabase_alerts.yaml (RM-0.6.3.8 S7). Каждый alert содержит annotations.runbook_url со ссылкой на одну из страниц ниже — это binding между observability surface и operator remediation path.

Контракт repo-reproducibility (G2-FIX cycle 2 / F-DOC-1): для каждого runbook_url в alert YAML существует backing markdown в этом каталоге. Verifier:

python3 - <<'PY'
import re, pathlib
rules = pathlib.Path("tools/observability/alerts/angarabase_alerts.yaml").read_text()
slugs = re.findall(r"runbooks/([a-z0-9-]+)", rules)
root = pathlib.Path("angarabook/src/operations/runbooks")
missing = [s for s in slugs if not (root / f"{s}.md").exists()]
print("OK" if not missing else f"MISSING: {missing}")
PY

По alert правилам

Соглашение об URL

Production angarabook deployment мапит /operations/runbooks/<slug> → angarabook/src/operations/runbooks/<slug>.md. Если ваш build использует другой layout, обновите runbook_url в alert YAML соответственно (источник истины — alert файл, не сами runbooks).

Шаблон новой runbook страницы

Каждая runbook страница содержит:

1. Что означает (обязательно) — короткое объяснение alert семантики + PromQL ссылка.
2. Severity — critical / warning / info.
3. Initial response (≤ 5 минут) — что сделать прямо сейчас.
4. Diagnostics — конкретные команды (curl, psql, iostat, …).
5. Mitigation — таблица “симптом → действие”.
6. Escalation — когда и как эскалировать.
7. Связанные — ссылки на смежные runbooks и reference docs.

Связанные

• Runbooks index — общий каталог operator runbooks.
• Observability metrics checklist — minimal набор метрик.