homelab-infra/monitoring/README.md

Monitoring Stack

Zielzustand: ein zentraler Observability-Stack fuer KalliLab CORE.

Enthaltene Dienste

• monitoring-grafana: zentrale UI unter https://monitoring.kaleschke.info
• monitoring-prometheus: Metriken mit 30 Tagen Retention
• monitoring-alertmanager: Alert-Routing fuer Prometheus-Regeln
• monitoring-alertmanager-ntfy-bridge: uebersetzt Alertmanager-Webhooks zu ntfy-Pushes
• monitoring-loki: Container-Logs mit 30 Tagen Retention
• monitoring-promtail: Docker-Log-Discovery ueber read-only Docker-Socket
• monitoring-node-exporter: Host-Metriken
• monitoring-cadvisor: Container-Metriken
• monitoring-blackbox-exporter: externe HTTP-Erreichbarkeit als Uptime-Kuma-Ersatz
• monitoring-influxdb3-core: InfluxDB 3 Core fuer Home-Assistant-/Ecowitt-Langzeitdaten

Die alten Pfade ops/loki und ops/grafana-influxdb wurden am 2026-05-26 aus dem aktiven Repo entfernt. Rollback erfolgt bei Bedarf ueber Git-Historie, nicht ueber parallel gepflegte Compose-Verzeichnisse.

Live-Stand 2026-06-01: die zehn monitoring-* Container laufen produktiv, die alten Container grafana, influxdb3-core, loki und alloy sind in Docker nicht mehr vorhanden. Uptime Kuma ist durch Blackbox Exporter, Prometheus-Alerts und das Dashboard Homelab / Availability abgeloest.

Secrets

Vor dem Deploy muessen diese Host-Dateien existieren:

/mnt/user/appdata/secrets/monitoring_grafana_admin_password.txt
/mnt/user/appdata/secrets/monitoring_grafana_influxdb_token.txt
/mnt/user/appdata/secrets/influxdb3_admin_token.json

Alle Dateien mit Rechten 600 anlegen. Werte niemals ins Git schreiben.

monitoring-influxdb3-core uebernimmt bewusst /mnt/user/appdata/influxdb3/data und /mnt/user/appdata/influxdb3/plugins vom bisherigen Grafana/Influx-Stack, damit Home-Assistant-/Ecowitt-Historie und Token-Katalog erhalten bleiben.

Stack Environment

Default ist sicher lokal:

INFLUXDB_BIND_IP=127.0.0.1

Wenn Home Assistant aus der VM schreiben soll, in Komodo fuer den monitoring-Stack setzen:

INFLUXDB_BIND_IP=192.168.178.58

Migration

1. Secrets anlegen. Erledigt.
2. Alten ops/loki-Stack stoppen, wenn monitoring-loki und monitoring-promtail live gehen. Erledigt.
3. Alten ops/grafana-influxdb-Stack stoppen, bevor monitoring-influxdb3-core den LAN-Port 192.168.178.58:8181 uebernimmt. Erledigt.
4. monitoring via Komodo deployen und INFLUXDB_BIND_IP=192.168.178.58 erst setzen, wenn der Altcontainer den Port freigegeben hat. Erledigt.
5. Alte Repo-Verzeichnisse ops/loki und ops/grafana-influxdb entfernen. Erledigt.
6. Optionales Dashboard-Bootstrap-Profil einmalig ausfuehren.
7. Home Assistant Writer gegen http://192.168.178.58:8181/ pruefen; 401 Unauthorized ohne Token ist erwartbar.

Smoke-Tests

• https://monitoring.kaleschke.info leitet zu Authelia.
• Grafana-Datasources Prometheus, Loki und InfluxDB 3 Core testen erfolgreich.
• Prometheus Targets: prometheus, node-exporter, cadvisor, traefik, blackbox-http.
• Node Exporter Textfile Collector: /mnt/user/services/posture-check/textfile/homelab.prom wird vom Host-Skript services/posture-check/export-prometheus-textfile.sh befuellt.
• Alertmanager ist erreichbar und sendet ueber monitoring-alertmanager-ntfy-bridge nach https://ntfy.kaleschke.info/homelab-alerts.
• Loki zeigt Container-Logs mit Labels container, compose_project, compose_service.
• InfluxDB 3 Core enthaelt die Datenbank homelab.

Abloesestand

• Dozzle bleibt abgeloest: Homelab / Containers + Logs ersetzt Live-Logs und Error-Rate.
• Glances erst stoppen, wenn Homelab / Host Overview und Homelab / Containers + Logs fuer CPU, RAM, Disk, Network, Container-CPU und Container-RAM passen.
• Uptime Kuma ist entfernt; Homelab / Availability, Blackbox Exporter und Prometheus-Alerts sind der Zielzustand fuer HTTP-Verfuegbarkeit.
• Dashboard-Zielbestand: Homelab / Availability, Homelab / Containers + Logs, Homelab / Host Overview, Homelab / Family Status, Traefik Official Standalone Dashboard.

Wetter-Tagesberichte

Die Ecowitt-/HA-Wetterdaten (DB homeassistant, Datasource ha-weather-influx) werden in drei Grafana-Dashboards sichtbar (Ordner Homelab, Tag weather):

• Wetterarchiv KalliHome (ha-weather-archive): Verlaeufe und Gauges ueber einen Zeitbereich.
• Wetterbericht KalliHome (ha-weather-day-report): visueller Tagesbericht fuer einen Tag (Bewertungs-Banner, Kennzahl-Karten mit Sparkline, Tagescharts Temperatur und Solar/UV).
• Wetter-Tagesberichte KalliHome (ha-weather-report-history): Index/Finder, eine Zeile pro Tag mit Kurzbewertung, T min/max/Mittel, Regen, UV und Boee.

Alte Tagesberichte finden und ein Datum waehlen

1. Dashboard Wetter-Tagesberichte oeffnen (Standard: letzte 30 Tage, Europe/Berlin). In der Tabelle auf das Datum klicken -> der ausfuehrliche Tagesbericht oeffnet sich fuer genau diesen Tag. Weiter zurueck: Zeitbereich oben rechts vergroessern.
2. Alternativ im Dashboard Wetterbericht KalliHome direkt einen Tag waehlen: Zeitbereich oben rechts -> Absolute time range -> z. B. From 2026-06-15 00:00:00, To 2026-06-16 00:00:00 -> Apply. Beide Dashboards haben Zeitzone Europe/Berlin, die Eingaben gelten also in Berliner Lokalzeit; Standard ist gestern (now-1d/d bis now/d).

Grafana hat keine echte Datepicker-Variable: eine Textbox-Variable kann den Zeitbereich nicht setzen, und ein report_date-Ansatz braeuchte zeitzonen-genaues Tages-Bounding in InfluxDB-3-SQL. Deshalb ist der Timepicker bei Dashboard-Zeitzone Europe/Berlin der exakte Weg fuer einen vollstaendigen Lokaltag, und die Index-Tabelle der bequeme Klick-Selektor fuer alte Tage. Die Tabellen-Buckets liegen auf UTC-Mitternacht (~01:00/02:00 Berlin); der verlinkte Tagesbericht zeigt das gewaehlte Fenster vollstaendig.

Quelle: InfluxDB statt Markdown-Index

Die Dashboards rendern direkt per SQL aus InfluxDB 3 Core - gleiche Quelle wie der Markdown-Generator services/posture-check/weather-day-report.py. Damit ist jeder zurueckliegende Tag reproduzierbar, solange die Rohdaten vorgehalten werden; ein separater Markdown-Index ist bewusst nicht noetig. Die erzeugten Tagesberichte als Datei (E-Mail/Offline-Archiv) liegen weiterhin unter /mnt/user/services/posture-check/daily-reports/homelab-day-YYYY-MM-DD.md.

Deploy und Test

Dashboards werden aus monitoring/grafana/dashboards/ provisioniert (Verzeichnis- Mount, Reload alle 5 Minuten, Ordner Homelab). Nach Push nach Gitea deployt Komodo den monitoring-Stack; Grafana laedt die JSON-Dateien automatisch nach. Kein Bootstrap-Importer noetig (der gilt nur fuer grafana.com-Dashboard-ID 17346).

SQL der Index-Tabelle vor dem Verlassen einmal pruefen: Grafana -> Explore -> Datasource ha-weather-influx -> die rawSql aus weather-report-history.json einfuegen und einen Zeitbereich (z. B. letzte 7 Tage) waehlen. Erwartet: eine Zeile pro Tag mit gefuellten Spalten. Falls extract(epoch FROM ...) auf dem InfluxDB-3- Build nicht unterstuetzt wird, stattdessen to_unixtime(...) verwenden.

Alerting

Prometheus wertet monitoring/prometheus/alerts.yml aus und sendet an monitoring-alertmanager. Alertmanager routet alle Alerts an den ntfy-Bridge-Container. Der Bridge-Container postet nach https://ntfy.kaleschke.info/homelab-alerts.

Blackbox-HTTP-Alerts unterscheiden zwischen einem einzelnen kaputten Endpoint und einem externen Connectivity-Problem:

• HomelabExternalConnectivityDown feuert, wenn mindestens 5 Public-Endpoints gleichzeitig fuer 8 Minuten nicht erreichbar sind. Das deckt WAN-, DNS- oder Provider-Ausfaelle ab, inklusive laengerer DSL-Reconnects.
• HomelabEndpointDown feuert fuer einzelne Endpoints erst nach 8 Minuten und wird unterdrueckt, solange der Sammelalert aktiv ist. Dadurch erzeugt ein Telekom-24h-Reconnect keine ntfy-Flut pro Domain.
• HomelabCertificateExpiresSoon und HomelabCertificateExpiresCritical nutzen Blackbox TLS-Metriken fuer 21-/7-Tage-Warnungen.
• HomelabBorgBackupStale, HomelabBorgLastJobFailed, HomelabBorgLastJobCompletedWithWarnings und HomelabCriticalContainerDown nutzen Host-Textfile-Metriken. Voraussetzung: services/posture-check/export-prometheus-textfile.sh laeuft regelmaessig auf dem Host, empfohlen alle 15 Minuten.

Test:

curl -fsS http://alertmanager-ntfy-bridge:8080/healthz

Textfile-Metriken manuell aktualisieren:

bash /mnt/user/services/homelab-infra/services/posture-check/export-prometheus-textfile.sh