Trim documentation to active runbooks
This commit is contained in:
+40
-117
@@ -1,129 +1,52 @@
|
||||
# Alert Rules
|
||||
|
||||
Stand: 2026-05-30
|
||||
Stand: 2026-05-31
|
||||
|
||||
Zentrale Nachschlagetabelle aller Prometheus-Alarmregeln plus Bewertung, ob die
|
||||
Abdeckung sinnvoll und vollstaendig ist.
|
||||
Diese Datei beschreibt die produktiven Alarmwege und wichtigsten Regeln. Die
|
||||
Konfiguration selbst liegt in `monitoring/prometheus/alerts.yml` und in den
|
||||
Skripten unter `services/posture-check/`.
|
||||
|
||||
- **Authoritative Quelle der Regeln:** `monitoring/prometheus/alerts.yml`
|
||||
- **Topic-/Sender-Konvention:** `docs/ALERTING_MAP.md`
|
||||
- Alle Prometheus-Alarme laufen ueber Alertmanager →
|
||||
`monitoring/alertmanager-ntfy-bridge/bridge.py` → ntfy-Topic `homelab-alerts`.
|
||||
## Alarmwege
|
||||
|
||||
> Diese Datei ist **Doku**, nicht die Konfiguration. Wer eine Regel aendert,
|
||||
> aendert `monitoring/prometheus/alerts.yml`, pusht nach Gitea und laesst Komodo
|
||||
> deployen bzw. Prometheus neu laden. Danach diese Tabelle nachziehen.
|
||||
|
||||
## Zwei Alarm-Pfade nebeneinander
|
||||
|
||||
Nicht jeder Homelab-Alarm kommt aus Prometheus. Wer "fehlt da was?" beantworten
|
||||
will, muss beide Pfade zusammen lesen:
|
||||
|
||||
| Pfad | Quelle | Beispiele |
|
||||
| Weg | Quelle | Ziel |
|
||||
|---|---|---|
|
||||
| **Prometheus / Alertmanager** | `monitoring/prometheus/alerts.yml` | Erreichbarkeit, Zertifikate, Disk/RAM, Borg-Metriken, Critical-Container |
|
||||
| **Posture-Check / ntfy-direkt** | `services/posture-check/*` | NVMe-SMART, Cert/Token-Check, Compose-Runtime-Drift, Docker `die`/`oom`/`kill`, Authelia-Drift, Borg-Pre-Hook, Restore-Jobs |
|
||||
| Prometheus / Alertmanager | `monitoring/prometheus/alerts.yml` | ntfy `homelab-alerts` |
|
||||
| Posture Check | `services/posture-check/posture-check.sh` | ntfy `homelab-alerts` |
|
||||
| Cert / Token Check | `services/posture-check/cert-token-check.sh` | ntfy `homelab-alerts` |
|
||||
| Compose Runtime Drift | `services/posture-check/compose-runtime-drift.sh` | ntfy `homelab-alerts` |
|
||||
| Docker Critical Events | `services/posture-check/docker-critical-events.sh` | ntfy `homelab-alerts` |
|
||||
| Borg Pre-Hook | `ops/borg-ui/scripts/pre-borg.sh` | ntfy `homelab-alerts` |
|
||||
| Restore Jobs | `ops/restore-tests/run-restore-job-with-ntfy.sh` | Fehler `homelab-alerts`, Erfolg `homelab-info` |
|
||||
|
||||
Beide enden auf `homelab-alerts`. Der Posture-Pfad ist in `docs/ALERTING_MAP.md`
|
||||
tabelliert; er wird hier nur referenziert, nicht dupliziert.
|
||||
## Prometheus-Regeln
|
||||
|
||||
## Prometheus-Regeltabelle
|
||||
|
||||
Severity-Routing der Bridge: `critical` und `warning` gehen beide auf
|
||||
`homelab-alerts` (kein eigenes Topic je Severity).
|
||||
|
||||
### Gruppe `homelab-availability`
|
||||
|
||||
| Alarm | Trigger (PromQL, gekuerzt) | Schwelle / `for` | Severity | Was tun |
|
||||
|---|---|---|---|---|
|
||||
| `HomelabExternalConnectivityDown` | `sum(probe_success{blackbox-http}==0) >= 5` | ≥5 Endpunkte / 8m | warning | WAN/DNS/Provider pruefen, nicht pro Domain jagen — Sammelausfall |
|
||||
| `HomelabEndpointDown` | `probe_success==0` (einzeln, nicht im Sammelausfall) | 1 Endpunkt / 8m | critical | Betroffenen Dienst/Traefik-Route pruefen |
|
||||
| `HomelabEndpointSlow` | `probe_duration_seconds > 5` | >5s / 5m | warning | Dienst-/Backend-Last pruefen, oft transient |
|
||||
| `HomelabCertificateExpiresSoon` | Restlaufzeit 7–21 Tage | <21d & >7d / 30m | warning | ACME/Traefik-Renewal beobachten |
|
||||
| `HomelabCertificateExpiresCritical` | Restlaufzeit ≤7 Tage (oder abgelaufen) | ≤7d / 15m | critical | Renewal sofort erzwingen/pruefen |
|
||||
|
||||
### Gruppe `homelab-host`
|
||||
|
||||
| Alarm | Trigger (PromQL, gekuerzt) | Schwelle / `for` | Severity | Was tun |
|
||||
|---|---|---|---|---|
|
||||
| `HomelabDiskAlmostFull` | `100*(1-avail/size) > 85` (ohne tmpfs/overlay) | >85% / 10m | warning | Mountpoint aufraeumen / erweitern |
|
||||
| `HomelabDiskCritical` | `100*(1-avail/size) > 95` (ohne tmpfs/overlay) | >95% / 5m | critical | Sofort Platz schaffen — Writes drohen zu scheitern (DB, appdata, Cache) |
|
||||
| `HomelabHighMemoryUsage` | `100*(1-MemAvailable/MemTotal) > 90` | >90% / 10m | warning | Speicherfresser identifizieren, ggf. Container-Limit (F-19) |
|
||||
| `HomelabTraefik5xx` | `increase(traefik_service_requests_total{5..}[5m]) >= 5` je Service | ≥5 / 2m | warning | Backend des betroffenen Service pruefen |
|
||||
|
||||
### Gruppe `homelab-backup-and-containers`
|
||||
|
||||
| Alarm | Trigger (PromQL, gekuerzt) | Schwelle / `for` | Severity | Was tun |
|
||||
|---|---|---|---|---|
|
||||
| `HomelabTextfileExporterStale` | `time()-last_run > 2h` | >2h / 15m | warning | `export-prometheus-textfile.sh`-Cron auf Host pruefen |
|
||||
| `HomelabBorgMetricsMissing` | `absent(borg_last_completed_ts)` | fehlt / 15m | critical | Textfile-Export oder borg-ui pruefen |
|
||||
| `HomelabBorgBackupStale` | `time()-borg_last_completed_ts > 30h` | >30h / 15m | warning | Letztes Borg-Backup nachholen/pruefen |
|
||||
| `HomelabBorgLastJobFailed` | `borg_last_success != 1` | ≠1 / 15m | critical | Borg-UI-Job-Log pruefen, Backup wiederholen |
|
||||
| `HomelabBorgLastJobCompletedWithWarnings` | `borg_last_job_warning == 1` | =1 / 15m | warning | Warnung im Borg-UI-Job lesen |
|
||||
| `HomelabCriticalContainerDown` | `homelab_critical_container_running == 0` | =0 / 5m | critical | Container neu starten / Komodo-Stack pruefen (`name`-Label) |
|
||||
| Alarm | Ausloeser | Severity | Aktion |
|
||||
|---|---|---|---|
|
||||
| `HomelabExternalConnectivityDown` | mindestens 5 HTTP-Ziele down | warning | WAN/DNS/Provider pruefen, nicht jede Domain einzeln jagen |
|
||||
| `HomelabEndpointDown` | einzelnes HTTP-Ziel down | critical | Dienst, Traefik-Route und Backend pruefen |
|
||||
| `HomelabEndpointSlow` | Endpoint >5s | warning | Dienstlast oder Backend-Latenz pruefen |
|
||||
| `HomelabCertificateExpiresSoon` | Cert <21 Tage | warning | ACME/Traefik-Renewal beobachten |
|
||||
| `HomelabCertificateExpiresCritical` | Cert <=7 Tage | critical | Renewal sofort pruefen |
|
||||
| `HomelabDiskAlmostFull` | Filesystem >85% | warning | Platz schaffen oder Schwelle pruefen |
|
||||
| `HomelabDiskCritical` | Filesystem >95% | critical | Sofort Platz schaffen |
|
||||
| `HomelabHighMemoryUsage` | MemAvailable <10% | warning | Speicherfresser identifizieren |
|
||||
| `HomelabTraefik5xx` | >=5 5xx je Service in 5 Minuten | warning | betroffenes Backend pruefen |
|
||||
| `HomelabTextfileExporterStale` | Textfile-Exporter >2h alt | warning | Host-Cron pruefen |
|
||||
| `HomelabBorgMetricsMissing` | Borg-Metrik fehlt | critical | Textfile-Exporter oder Borg-UI pruefen |
|
||||
| `HomelabBorgBackupStale` | letztes Borg-Backup >30h | warning | Backup-Lauf nachholen/pruefen |
|
||||
| `HomelabBorgLastJobFailed` | letzter Borg-Job fehlgeschlagen | critical | Borg-UI-Job-Log pruefen |
|
||||
| `HomelabBorgLastJobCompletedWithWarnings` | letzter Borg-Job mit Warnungen | warning | Warnung im Borg-UI-Job lesen |
|
||||
| `HomelabCriticalContainerDown` | kritischer Container fehlt | critical | Komodo/Docker-Status pruefen |
|
||||
| `HomelabPrometheusTargetDown` | Scrape-Ziel down | critical | node-exporter/cadvisor/blackbox/traefik pruefen |
|
||||
|
||||
Die Liste der ueberwachten Critical-Container steht in
|
||||
`services/posture-check/export-prometheus-textfile.sh` (`CRITICAL_CONTAINERS`).
|
||||
`services/posture-check/export-prometheus-textfile.sh`.
|
||||
|
||||
### Gruppe `homelab-meta`
|
||||
## Bekannte Luecken
|
||||
|
||||
| Alarm | Trigger (PromQL, gekuerzt) | Schwelle / `for` | Severity | Was tun |
|
||||
|---|---|---|---|---|
|
||||
| `HomelabPrometheusTargetDown` | `up == 0` | =0 / 5m | critical | Scrape-Ziel (node-exporter/cadvisor/blackbox/traefik) pruefen — Metriken sind sonst still |
|
||||
|
||||
## Bewertung: Sind die Alarme sinnvoll?
|
||||
|
||||
Insgesamt solide. Die Erreichbarkeits-Gruppe ist gut entworfen — der
|
||||
Sammelausfall-Trick (`>=5` Endpunkte als ein Warning, Einzelausfall als
|
||||
Critical) verhindert eine ntfy-Flut bei kurzen DSL-Reconnects. Borg ist mit vier
|
||||
Regeln (fehlende Metrik, veraltet, fehlgeschlagen, mit Warnungen) gut
|
||||
abgedeckt.
|
||||
|
||||
Anmerkungen / Feinschliff (kein Handlungsdruck):
|
||||
|
||||
- **`HomelabDiskAlmostFull` ohne Array-Filter.** Der `fstype!~"tmpfs|overlay"`-
|
||||
Filter schliesst keine bewusst vollen Unraid-Array-Disks aus. Eine
|
||||
Datengrab-Disk, die dauerhaft bei 90 % liegt, erzeugt einen Dauer-Warning.
|
||||
Bei Bedarf per `mountpoint`-Filter auf die wirklich kritischen Pfade
|
||||
(`/`, appdata-/services-Cache) eingrenzen.
|
||||
- **`HomelabEndpointSlow` >5s** ist grosszuegig und damit eher ruhig — okay als
|
||||
bewusste Wahl, faengt aber keine schleichende 3–4s-Degradierung.
|
||||
- **`HomelabHighMemoryUsage` 90 %** ist auf einem Host mit ZFS/Unraid-Cache
|
||||
schnell erreicht (Cache zaehlt nicht als „available" je nach Messung); die
|
||||
Verwendung von `MemAvailable` ist hier korrekt und mildert das.
|
||||
|
||||
## Bewertung: Fehlt etwas? (Luecken, priorisiert)
|
||||
|
||||
### Hoch — erledigt 2026-05-30
|
||||
|
||||
1. ~~Kein `up == 0` auf Scrape-Targets~~ → **`HomelabPrometheusTargetDown`**
|
||||
umgesetzt (Gruppe `homelab-meta`). Faellt node-exporter/cadvisor/blackbox/
|
||||
traefik aus, feuert jetzt nach 5 Minuten ein Critical.
|
||||
2. ~~Kein Disk-Critical-Tier~~ → **`HomelabDiskCritical`** bei >95 % umgesetzt
|
||||
(Gruppe `homelab-host`), zusaetzlich zum bestehenden Warning bei >85 %.
|
||||
|
||||
### Mittel — sinnvoll, aber kein Notstand
|
||||
|
||||
3. **Dead-Man's-Switch.** Faellt Prometheus oder die ntfy-Bridge selbst aus,
|
||||
feuert gar kein Alarm — strukturell blind. Eine immer feuernde
|
||||
Watchdog-Regel plus externer „Heartbeat fehlt"-Waechter (z. B. Uptime-Kuma
|
||||
Push-Monitor oder Healthchecks.io) schliesst die Luecke. Bewusst leichtes
|
||||
Gewicht, weil Posture-Check/Borg-Pre-Hook teilweise unabhaengig laufen.
|
||||
4. **Inode-Erschoepfung.** Paperless/Immich erzeugen viele kleine Dateien;
|
||||
`node_filesystem_files_free` kann vor dem Byte-Limit knapp werden. Niedrige
|
||||
Wahrscheinlichkeit, billiger Alarm.
|
||||
|
||||
### Bewusst nicht in Prometheus (anderer Pfad deckt ab)
|
||||
|
||||
- **NVMe-SMART-Verschleiss** → `check_nvme_smart` im Posture-Check (ntfy direkt).
|
||||
- **Compose-Runtime-Drift / Authelia-Drift** → Posture-Check (ntfy direkt).
|
||||
- **Docker `oom`/`die`/`kill`** → `docker-critical-events.sh` (ntfy direkt) —
|
||||
dies ist auch der Detektionspfad fuer den ersten echten OOM-Vorfall, der F-19
|
||||
(Container-Memory-Limits) ausloesen wuerde.
|
||||
- **Cert/Token-Health jenseits TLS-Ablauf** → `cert-token-check.sh`.
|
||||
|
||||
## Stand
|
||||
|
||||
Die zwei Hoch-Luecken sind seit 2026-05-30 in `alerts.yml` umgesetzt. Naechster
|
||||
optionaler Schritt waere der Dead-Man's-Switch ueber einen externen Heartbeat-
|
||||
Waechter; ohne familienkritischen Anlass aber nicht eilig.
|
||||
- Kein externer Dead-Man's-Switch fuer Prometheus/ntfy-Bridge. Optional spaeter
|
||||
ueber Uptime-Kuma Push-Monitor oder Healthchecks.io.
|
||||
- Kein Inode-Alarm. Bei Paperless/Immich spaeter sinnvoll, aber aktuell kein
|
||||
dokumentierter Vorfall.
|
||||
- Container-Memory-Limits werden erst nach realen Peak-Daten gesetzt; OOM/kill
|
||||
wird bereits ueber `docker-critical-events.sh` gemeldet.
|
||||
|
||||
Reference in New Issue
Block a user