Monitoring & Observability

Přehled o stavu infrastruktury. Rozlišujeme: Dashboard (rychlý pohled), Uptime Kuma (dostupnost), Loki (logy), InfluxDB (metriky).

1. Dashboard (Homepage) 🖥️

"Funguje to teď?"

Slouží pro rychlou kontrolu stavu domácnosti. Běží na https://home.marada.name.

Slouží jako centrální rozcestník na všechna známá zařízení a služby v Homelabu, která mají vlastní webové UI.

Zdroj pravdy pro zařazení položek je docs/infrastruktura/sit/inventory.md.

Typicky obsahuje odkazy na:

Síť: pfSense, switche, UniFi OS Server.
Platformu: Proxmox, PBS, TrueNAS, Home Assistant.
Aplikace: Uptime Kuma, Grafana, Loki, n8n, Scrypted, Immich.
IoT a technologie domu: Zigbee koordinátor, Atrea, EcoGeo.

Při přidání nové služby s UI je potřeba současně aktualizovat i docs/files/docker/debian-services/homepage/services.yaml.

Standardní webová UI na portech 80/443 mohou vést přímo na zařízení přes pfSense DNS override. UI na nestandardních portech mají preferovat *.marada.name přes Nginx na debian-services, aby Homepage neukazovala porty.

2. Uptime Kuma 🚨

"Hrozí problém?"

Monitoring dostupnosti služeb a zařízení. Běží jako HA addon na http://192.168.20.7:3001.

Nahrazuje dřívější CheckMK. Jednodušší, lehčí, pokrývá hlavní potřebu: "běží to?"

Typické monitory:

Zařízení / Služba	Metoda	Co sledujeme
Síťová infrastruktura	Ping / HTTP	pfSense, switche, UniFi APs, UniFi OS Server
Servery	Ping / HTTP	Proxmox nodes, TrueNAS, PBS, debian-services
Aplikace	HTTP(S)	Grafana, Loki, n8n, Scrypted, Immich, HA
IoT zařízení	Ping / HTTP	Zigbee koordinátor, kamery, tiskárna

3. Centrální Logování (Loki) 📜

"Co se stalo a proč?"

[!CAUTION] Pravidlo pro AI Agenty (Troubleshooting): Při jakémkoliv debugování, potížích se sítí, disky nebo službami, je ZCELA NEZBYTNÉ POUŽÍT LOKI LOGY JAKO PRVNÍ KROK. - Dokud nezkontroluješ logy přes Alloy/Loki zdroj (nebo přes AI Log Monitor JSON), nesmíš se připojovat po SSH ani spouštět ping / obskurní skripty. - Logy obsahují 99% odpovědí. Používej Grafana Explore (LogQL) a vždy hledej kontext.

Architektura

Dva datové toky do Loki, každý přes svůj Alloy collector (od 2026-06-15, logging review ⑧ — syslog ingest přesunut z HA na debian-services, viz decision_log.md):

Journal pipeline (job=journal): HA Core, addony, docker kontejnery na HA → HA Alloy addon (jen journal) → Loki. Journal se čte lokálně na HA, nelze ho sbírat vzdáleně.
Syslog pipeline (job=syslog): všechna síťová/infra zařízení → standalone Alloy (docker) na debian-services, co-located s Loki → Loki. pmx/PBS posílají přímo (RFC5424 + [hostname] template); zbytek (RFC3164 zařízení + pfSense) přes rsyslog relay na debian-services (:514), který přidá [hostname] a přepošle na lokální Alloy (127.0.0.1:5514).

[!NOTE] Proč dva collectory: syslog ingest sedí u Loki (debian-services) → výpadek/restart HA neshodí logování zbytku domu, žádný debian→HA→debian round-trip. Journal musí zůstat na HA (lokální systemd journal). To je záměr, ne duplikace.

graph LR
    subgraph "Home Assistant (192.168.20.7)"
        JOURNAL["systemd Journal<br/>(HA Core + Addons)"]
        HA_ALLOY["Alloy addon<br/>JEN journal<br/>/config/alloy/config.alloy"]
    end

    subgraph "debian-services (192.168.20.20 / .40.20)"
        RSYSLOG["rsyslog relay<br/>514/udp, přidá [hostname]"]
        DS_ALLOY["Alloy (docker)<br/>SYSLOG<br/>UDP 5514 / TCP 5601"]
        LOKI["Loki 3.7<br/>(Docker, 3100)"]
        GRAFANA["Grafana<br/>(data.marada.name)"]
    end

    subgraph "Přímo → debian Alloy (RFC5424 + [hostname])"
        PMX1["Proxmox pmx1"]
        PMX2["Proxmox pmx2"]
        PBS["PBS"]
    end

    subgraph "Přes relay (debian-services :514)"
        PFSENSE["pfSense"]
        UNIFI["UniFi APs"]
        SLZB["SLZB-MR3"]
        TRUENAS["TrueNAS"]
        SW1["Switch Rack 1"]
        SW2["Switch Rack 2"]
    end

    JOURNAL --> HA_ALLOY
    HA_ALLOY -->|"HTTP POST :3100"| LOKI

    PMX1 -->|"UDP 5514<br/>RFC5424"| DS_ALLOY
    PMX2 -->|"UDP 5514<br/>RFC5424"| DS_ALLOY
    PBS -->|"UDP 5514<br/>RFC5424"| DS_ALLOY

    PFSENSE -->|"UDP 514"| RSYSLOG
    UNIFI -->|"UDP 514<br/>RFC3164"| RSYSLOG
    SLZB -->|"UDP 514<br/>(IoT .40.20)"| RSYSLOG
    TRUENAS -->|"UDP 514"| RSYSLOG
    SW1 -->|"UDP 514"| RSYSLOG
    SW2 -->|"UDP 514"| RSYSLOG
    RSYSLOG -->|"127.0.0.1:5514"| DS_ALLOY

    DS_ALLOY -->|"HTTP POST :3100"| LOKI
    GRAFANA -->|"LogQL"| LOKI

Komponenty

Komponenta	Kde běží	Funkce
Alloy — journal	HA Addon (`wymangr/hassos-addons` v0.0.8, Alloy v1.12.2)	Jen HA journal pipeline → Loki. Config v repu: `alloy/config.alloy`.
Alloy — syslog	docker na debian-services (`grafana/alloy:v1.16.3`)	Přijímá veškerý syslog (UDP 5514 / TCP 5601) → relabel/process ([hostname] bracket) → Loki. Config: `docs/files/docker/debian-services/alloy/config.alloy`.
rsyslog relay	debian-services (nativní, 514/udp)	RFC3164 zdroje + pfSense → přidá `[hostname]` → lokální Alloy `127.0.0.1:5514`. Config: `docs/files/config_backups/debian-services-relay/`.
Loki	Docker na Debianu (port 3100)	Databáze logů (indexuje labely, ne text)
Grafana	Docker na Debianu (`data.marada.name`)	Vizualizace, dashboardy (auto-provisioning z repa). Setup data sources viz Grafana — první kroky.

Alloy Custom Config

Alloy běží s custom konfigurací v /config/alloy/config.alloy (addon option override_config: true). Zdrojový soubor je v repu: alloy/config.alloy.

Label schema (po správném nasazení):

Label	Journal	Syslog	Popis
`job`	`journal`	`syslog`	Typ pipeline
`component`	`loki.source.journal`	`loki.source.syslog`	Alloy komponenta
`hostname`	HA hostname	Zdrojový server	Odkud log pochází
`app`	syslog_identifier	RFC5424 APP-NAME	Aplikace/služba
`level`	—	RFC5424 severity	Závažnost (info, warning, error...)
`unit`	systemd unit	—	Systemd služba (jen journal)
`protocol`	—	`udp` / `tcp`	Transportní protokol (jen syslog)

Co se loguje

Zdroj	Cesta	Stav	Jak nakonfigurovat
HA Core + Addons	Alloy journal	✅	Automaticky (systemd journal)
pfSense	→ debian:514 (relay) → Alloy	✅	Status → System Logs → Settings → Remote: `192.168.20.20:514` (relay přidá `[hostname]`; GUI neumí vlastní template)
Proxmox (pmx1)	Přímo → debian Alloy:5514 (RFC5424)	✅	Nasadit `/etc/rsyslog.d/99-loki.conf` (viz repo `docs/files/config_backups/`) — template prependuje `[%HOSTNAME%]`
Proxmox (pmx2)	Přímo → debian Alloy:5514 (RFC5424)	✅	Nasadit `/etc/rsyslog.d/99-loki.conf`
PBS	Přímo → debian Alloy:5514 (RFC5424)	✅	Nasadit `/etc/rsyslog.d/99-loki.conf`
Debian Services	Přímo → debian Alloy:5514 (RFC5424)	✅	Nasadit `/etc/rsyslog.d/99-loki.conf`
Scrypted	Přímo → debian Alloy:5514 (RFC5424)	⏳	Nasadit `/etc/rsyslog.d/99-loki.conf`
UniFi APs	→ debian:514 (relay) → Alloy	✅	UniFi OS Server → Settings → System → Remote Logging → `192.168.20.20:514`
SLZB-MR3	→ debian:514 (relay, IoT) → HA:5514	✅	SLZB Web UI → Log and debug → Syslog → `192.168.40.20:514` (BSD/RFC3164/UDP)
TrueNAS	→ debian:514 (relay) → Alloy	✅	System → Advanced → Syslog → Remote: `192.168.20.20:514`
Switch Rack 1 (USW-48-PoE)	→ debian:514 (relay) → Alloy	✅	Web UI → Diagnostics → Remote Log → `192.168.20.20:514`
Switch Rack 2 (USW-Lite-8-PoE)	→ debian:514 (relay) → Alloy	✅	Web UI → Diagnostics → Remote Log → `192.168.20.20:514`

[!NOTE] Stav k 2026-06-15: Veškerý syslog sbírá standalone Alloy (docker) na debian-services (:5514), co-located s Loki — HA addon dělá jen journal (logging review ⑧). Všechny zdroje tečou s hostname labelem (servername=debian-services pro syslog, HomeAssistant pro journal). pmx1/pmx2/PBS posílají přímo na debian Alloy s [%HOSTNAME%] template; RFC3164 zařízení + pfSense přes rsyslog relay (:514), který prefix přidá → mj. hostname=pfSense.marada.lan. pfSense filterlog byl 2026-06-12 vyřazen z remote loggingu (~97 % objemu; drop eventy lokálně přes clog). Loki retence 90 dní (compactor). HA journal byl 17. 3.–12. 6. nefunkční, opraveno (decision_log.md 2026-06-12).

Postup nasazení rsyslog na nový server

# Z lokálního PC (ha-config repo)
scp docs/files/config_backups/99-loki.conf root@<host>:/etc/rsyslog.d/99-loki.conf
ssh root@<host> systemctl restart rsyslog

rsyslog relay na debian-services

Relay je nativní rsyslog (ne Docker). Konfigurace:

/etc/rsyslog.d/10-udp-receiver.conf — příjem RFC3164 na UDP 514
/etc/rsyslog.d/99-loki.conf — forward na lokální Alloy (127.0.0.1:5514) + přidá [hostname] (config verzován v docs/files/config_backups/debian-services-relay/)

debian-services má dvě síťovky: LAN (192.168.20.20) a IoT (192.168.40.20). Zařízení na IoT VLANu (SLZB-MR3) posílají syslog na IoT adresu.

Jak hledat v logách

Grafana → Explore → Loki datasource → LogQL:

# Všechny logy z HA Core
{job="journal", unit="homeassistant.service"}

# Errory z jakéhokoliv addonu
{job="journal"} |= "error"

# Všechny syslog logy
{job="syslog"}

# Syslog z konkrétního hostu (po nasazení RFC5424)
{job="syslog", hostname="pmx1"} |= "error"

# WiFi eventy z UniFi AP
{job="syslog"} |= "stahtd"

# DNS timeouty
{job="syslog"} |= "dns timeout"

[!TIP] Zjištění dostupných labelů:
curl -s http://192.168.20.20:3100/loki/api/v1/labels
curl -s http://192.168.20.20:3100/loki/api/v1/label/job/values
curl -s http://192.168.20.20:3100/loki/api/v1/label/hostname/values
Hlavní labely: job (journal/syslog), hostname, app, level, unit (jen journal). Label host neexistuje — nepoužívat.

4. Metriky (InfluxDB 2.x) 📊

"Jak se dům chová v čase?"

[!NOTE] Stav: ✅ Funkční. HA posílá stavy senzorů do InfluxDB 2.x v reálném čase.

InfluxDB 2.7: Časové řady (teploty, vlhkost, spotřeba). Běží v Dockeru na Debianu.
Grafana: Vizualizace a dashboardy (data.marada.name). Datasource provisionovaný automaticky.
HA Integrace: Nativní influxdb: v configuration.yaml (api_version: 2, token auth).
Org/Bucket: homelab / homeassistant.
Retention: Bez limitu (infinite). Data se uchovávají neomezeně pro dlouhodobé analýzy.
Query jazyk: Flux (v Grafaně), InfluxQL kompatibilní endpoint dostupný na /query.
Token: V secrets.yaml na HA, v .env na debian-services.

5. Strategie Alertingu

Kritické: (Výpadek internetu, Disky, Teplota, FTV Napájení) -> Push Notifikace (Telegram/Mobil).
Info: (Aktualizace, krátký výpadek) -> Dashboard nebo Email report.
Tok dat: Uptime Kuma (Alert) -> Webhook -> Home Assistant -> Mobilní Aplikace (Critical Notification).

Grafana Alerting (logy/metriky → Telegram)

Od 2026-06-14 běží nativní Grafana alerting, provisionovaný z repa (grafana/provisioning/alerting/):

Contact point telegram — bot token z env (TELEGRAM_BOT_TOKEN, předáno přes compose z .env), chat id literál v contactpoints.yaml.
Notification policy — root route posílá vše defaultně na Telegram (sólo provoz).
Log-freshness pravidla (rules.yaml, folder Alerts): „Log source silent: journal" a „…: syslog" — pokud daný job za 10 min nepošle žádný řádek (nebo úplně zmizí → noDataState: Alerting), po 10 min vystřelí alert. Tohle je pojistka proti tichému výpadku log pipeline, který 3 měsíce nikdo neviděl (viz decision_log.md 2026-06-12).
Pozor: alerting je provisionovaný = v UI read-only. Změny dělej v repu a nasaď (scp + docker compose up -d grafana).

6. Standardy Monitoringu

Pro každou službu v Homelabu platí:

Healthcheck: HTTP služba musí mít endpoint /health nebo vracet 200 OK. Uptime Kuma toto kontroluje.
Logování: Služba musí psát logy do stdout/stderr (Docker) nebo do /var/log. Alloy je sbírá → Loki.
Zálohování: PBS ověřuje stáří posledního backupu.

7. AI Integrace

AI Log Monitor

/opt/scripts/log_monitor.py na Debianu, systemd timer 2× denně, Loki → Gemini Flash → GitHub Issues → Telegram.

Grafana MCP (ad-hoc diagnostika)

Pro ad-hoc dotazy na logy a diagnostiku používáme Grafana MCP tools přímo v Claude agentu:

query_loki_logs — LogQL dotazy
list_loki_label_names / list_loki_label_values — discovery labelů
query_loki_stats — statistiky streamů
query_loki_patterns — detekce log patternů

Nahrazuje dřívější skripty loki_search.py a check_homelab.py.

8. Implementační Roadmap

Fáze 1: Stack ✅ — Docker Compose (Loki, Grafana, Nginx, InfluxDB), Alloy Addon s custom configem.
Fáze 2a: Journal ✅ — HA Core + Addony přes Alloy journal pipeline.
Fáze 2b: Syslog ⏳ — Nasadit 99-loki.conf na servery, spustit syslog-ng relay, ověřit labely.
Fáze 3: Notifikace ⏳ — Uptime Kuma → Webhook → HA → Push notifikace.

[!TIP] Při přidávání nové VM/LXC: 1) Přidat monitor do Uptime Kuma, 2) Nasadit 99-loki.conf (repo: docs/files/config_backups/) → restart rsyslog.

9. Grafana Dashboardy

Dashboardy jsou verzovány v docs/files/docker/debian-services/grafana/dashboards/ a automaticky se načítají do Grafany přes file-based provisioning.

Dashboard	Soubor	Popis
Log Pipeline Health	`log-pipeline-health.json`	„Tečou logy?" — aktivní zdroje, journal/syslog objem, tabulka kdo posílá za 15 min. Párový k freshness alertům.
Syslog Overview	`syslog-overview.json`	Log volume, error rate, top errors, live stream — agregace per `hostname`
Home Assistant Logs	`homeassistant-logs.json`	HA Core errors, integration errors, addon logs
Infrastructure Health	`infrastructure-health.json`	Network, storage, auth failures, backup events

Export existujících dashboardů

uv run scripts/export_grafana_dashboards.py
uv run scripts/export_grafana_dashboards.py --folder Homelab  # jen z konkrétní složky