homelab-infra/docs/ALERT_RULES.md

# Alert Rules

Stand: 2026-06-23

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/`.

## Alarmwege

| Weg | Quelle | Ziel |
|---|---|---|
| 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` |

## End-to-End-Drills

Stand 2026-06-23 sind die produktionsnahen Alarmwege bis zum Handy des
Operators synthetisch belegt:

| Pfad | Test | Ergebnis |
|---|---|---|
| Direkter ntfy-Kanal | `ops/restore-tests/send-ntfy.sh homelab-alerts ...` | Handy-Empfang bestaetigt |
| Restore-Wrapper Fehler | `run-restore-job-with-ntfy.sh codex-negative-alert-test homelab-info` | `Restore job failed: codex-negative-alert-test` am Handy bestaetigt |
| Restore-Freshness Negativtest | `run-restore-checks.sh freshness-negative` | `TEST: Restore freshness alert path ok` am Handy bestaetigt; produktive Dumps nicht veraendert |
| Alertmanager -> Bridge -> ntfy | `amtool alert add HomelabAlertChainTest ...` im `monitoring-alertmanager`-Container | `FIRING` und `RESOLVED` am Handy bestaetigt; Bridge loggte `sent 1 ntfy notifications` |
| Docker Critical Events | `test-docker-critical-events.sh` + `docker-critical-events-supervisor.sh smoke` | Filtertest gruen; `Docker critical watcher smoke` am Handy bestaetigt |
| Borg Pre-Hook Fehler | `PRE_BACKUP_DUMPS=/bin/false POSTURE_CHECK=/bin/true FRESHNESS_CHECK=/bin/true pre-borg.sh` | `Borg pre-hook failed: pre-backup-dumps` am Handy bestaetigt; keine echten Backups/Dumps angefasst |

Nicht separat belegt wurde eine temporaere Prometheus-Testregel bis
Alertmanager. Der kritischere Pfad Alertmanager -> Bridge -> ntfy -> Handy ist
bewiesen; Prometheus-Regelladung wird im Monitoring-Reload-/Alert-Smoke des
Monitoring-Hardening-Punkts mitgeprueft.

## Prometheus-Regeln

| 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 |
| `HomelabBorgDumpMissing` | erwartetes Dump-Artefakt fehlt im aktuellen Dump-Set | critical | `pre-backup-dumps.sh`/User-Script pruefen |
| `HomelabBorgDumpStale` | Dump-Artefakt >30h alt (Borg laeuft, Dumps eingefroren) | critical | `pre-backup-dumps.sh`/User-Script pruefen, nicht nur den Borg-Job |
| `HomelabBorgScopeSourceListMissing` | Repo-Quellliste fuer Borg-Drift-Check fehlt | critical | Borg-UI-Mount `/local/services/homelab-infra` und Repo-Pfad pruefen |
| `HomelabBorgScopeMissingSources` | Borg UI enthaelt nicht alle Pfade aus `ops/borg-ui/all-important-sources.txt` | critical | Live-Borg-Scope an Repo-Quelle angleichen |
| `HomelabBorgScopeExtraSources` | Borg UI enthaelt Pfade ausserhalb der Repo-Quellliste | warning | Doku oder Live-Scope bereinigen |
| `HomelabBorgRepositoryCheckStale` | letzter Borg-Check >14 Tage alt | warning | Borg-Repository-Check ausfuehren oder Scheduler pruefen |
| `HomelabBorgRetentionDisabled` | Scheduled Job fuehrt kein Prune aus | warning | Retention-Einstellung in Borg UI pruefen |
| `HomelabBorgCompactDisabled` | Scheduled Job fuehrt kein Compact aus | warning | Compact-Einstellung in Borg UI pruefen |
| `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`.

## Bekannte Luecken

- 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 ueber `docker-critical-events.sh` gemeldet, sobald der Host-Watcher per
  Unraid User Script aktiviert ist. Start/Stop/Status/Smoke laufen ueber
  `services/posture-check/docker-critical-events-supervisor.sh`.