Přeskočit obsah

AI Log Monitor

Tento dokument popisuje funkčnost, nasazení a zdrojový kód skriptu log_monitor.py, který sbírá logy z databáze Loki, nechává je analyzovat umělou inteligencí (Google Gemini Flash) a v případě nalezení kritických chyb zakládá GitHub Issues a odesílá report na Telegram.

[!NOTE] Dříve existovaly také skripty loki_search.py (CLI vyhledávání) a check_homelab.py (korelace issues s logy). Oba byly smazány — jejich funkcionalitu plně nahrazují Grafana MCP tools (query_loki_logs, query_loki_stats, query_loki_patterns) dostupné přímo v AI agentu.

Architektura

  • Kde to běží: LXC kontejner debian-services (192.168.20.20), složka /opt/scripts/.
  • Spouštění: Nativní systemd timer (spouští se automaticky ve 08:00 a 20:00).
  • Vstupy:
    • Dotaz do API služby Loki (http://localhost:3100/loki/api/v1/query_range), která beží na stejném serveru v Dockeru.
    • Konfigurační soubor /opt/scripts/log_monitor.env (obsahuje API klíče).
  • Výstupy:
    • Telegram Bot API (zpráva odeslána definovanému uživateli) + GitHub Issues.
    • Vlastní strukturované logy (modul logging): INFO → stdout, WARNING/ERROR → stderr. Pod systemd jde obojí do journald, takže chyby samotného monitoru (selhání Loki, Gemini, GitHubu, Telegramu, nevalidní JSON z Gemini) jsou dohledatelné v journalu (a odtud v Loki) — journalctl -u log-monitor.service, ne jen v Telegramu.

1. Zdrojový kód

Skript žije v repu — jediný zdroj pravdy: scripts/log_monitor.py (čistý Python, jen urllib/json, bez venv). Needituj kopii v dokumentaci — tahle stránka popisuje jen architekturu, nasazení a provoz.

Co dělá: dotáhne logy z Loki za posledních N hodin → odfiltruje šum a dedupuje → pošle do Gemini k triáži → výsledek jde na Telegram a zakládá GitHub Issues (s denním limitem). Při selhání všech Loki dotazů pošle varování, ne falešné „čisto".

Triáž a re-surface (proč seznam issues neroste donekonečna)

  • Nové issue se založí jen pro reálný problém, ne pro šum. Přechodné jednorázovky (např. Tailscale „context canceled"), boot-only selhání na hostu s dlouhým uptime (např. systemd-networkd-wait-online) a známý benigní log šum (např. UniFi wevent Resource busy) Gemini klasifikuje jako P2 — a P2 issue nezakládá.
  • Už otevřené issue se při dalším 12h běhu znovu nekomentuje. Re-surface (komentář
  • Telegram) nastane jen při seriózním opakování: priorita P0 vždy, P1 až když počet výskytů v okně překročí SERIOUS_RECURRENCE_THRESHOLD (default 50). Tím se totéž neomílá každých 12 h.
  • Zavírání issues je ruční — monitor je sám nezavírá.

2. Plánování pomocí Systemd

Aby skript běžel asynchronně na pozadí, nevyužívá se klasický cron, ale systemd timers, což zabezpečuje lepší sběr logů a kontrolu timeoutů.

/etc/systemd/system/log-monitor.service

Tento soubor definuje, jak se má skript spustit. Důležité je specifikovat EnvironmentFile, odkud skript čerpá API klíče. Argument --hours 12 určuje ohlédnutí o 12 hodin dozadu.

[Unit]
Description=AI Log Monitor - Analyzes Loki logs with Gemini Flash
After=network-online.target

[Service]
Type=oneshot
EnvironmentFile=/opt/scripts/log_monitor.env
ExecStart=/usr/bin/python3 /opt/scripts/log_monitor.py --hours 12
TimeoutSec=120

[Install]
WantedBy=multi-user.target

/etc/systemd/system/log-monitor.timer

Timer určuje kadenci spouštění (08:00 ráno a 20:00 večer).

[Unit]
Description=Run AI Log Monitor every 12 hours

[Timer]
OnCalendar=*-*-* 08,20:00:00
Persistent=true
RandomizedDelaySec=300

[Install]
WantedBy=timers.target

3. Nasazení a Údržba (Deployment)

Jelikož se skript nespouští z gitu, ale z izolované složky na serveru, je nutné po každé úpravě lokálního souboru scripts/log_monitor.py vynutit jeho přenos na Debian server:

# Z PC (ha-config repozitáře)
scp scripts/log_monitor.py root@192.168.20.20:/opt/scripts/log_monitor.py

Při změně parametrů timeru nebo služby je nutné na serveru provést daemon-reload: 

# Na serveru
systemctl daemon-reload

4. Prvotní instalace

  1. Vytvoření prostředí na serveru: 
    mkdir -p /opt/scripts/
# Vytvořit .env soubor (musí obsahovat citlivé tokeny)
cat <<EOF > /opt/scripts/log_monitor.env
GEMINI_API_KEY="AIza...<doplň-svůj-klíč>"
TELEGRAM_BOT_TOKEN="<bot-token>"
TELEGRAM_CHAT_ID="<chat-id>"
GITHUB_TOKEN="ghp_<doplň-svůj-token>"
GITHUB_REPO="docek/ha-config"
EOF
chmod 600 /opt/scripts/log_monitor.env
  2. Kopírování souborů: Přenos scriptu, timeru a service souborů na jejich místa.
  3. Povolení a start: 
    systemctl daemon-reload
systemctl enable log-monitor.timer
systemctl start log-monitor.timer
  4. Ad-hoc spuštění: 
    systemctl start log-monitor.service
# Sledování průběhu:
journalctl -u log-monitor.service -f