Saltar a contenido

Stack de observabilidad para el setup del usuario (v1)

Primera síntesis de Q5: qué corre dónde, qué se observa, qué dispara alerta. Aplicado al setup HA Yellow (essentials) + mini-PC (experimental + observability + agente). Stack: Prometheus + Loki + Grafana + Gatus, en containers sobre el mini-PC. Sin dependencias del Yellow para que un fallo del essentials no derribe el observatorio.

Contexto

Esta página cierra la primera versión operativa de Q5. Coexiste con ha upgrade reliability strategy (Q2) y self healing adapted to user setup (Q1 + Q10). El stack de observability es la base de "no tinkering": sin él, el usuario no sabe si las cosas funcionan, y el agente no puede diagnosticar.

Contenido

Donde corre todo

HA Yellow (essentials)              Mini-PC (todo lo demás)
─────────────────────────           ────────────────────────────────
- HA Core                           - Prometheus (scrape metrics)
- Z2M add-on                        - Loki (logs)
- Mosquitto                         - Grafana (UI + alerts)
- Backup automation                 - Gatus (health checks → alertas)
                                    - Promtail (ships logs Yellow → Loki)
                                    - Node exporter (host metrics)
                                    - HA Container (twin)
                                    - Agente AI (consume Loki/Grafana API)

Principio clave: el observatorio no vive en el Yellow. Si el Yellow se cae, las alertas siguen funcionando — disparan EL FALLO del Yellow.

Qué se observa (4 dimensiones)

Dimensión Tool Ejemplos concretos
Health binario gatus HA UI responde? Z2M devuelve "Bridge online"? mini-PC ping responde? router responde?
Métricas continuas Prometheus + HA Prometheus exporter CPU/RAM del Yellow, uptime de HA core, # devices Zigbee online, latencia de últimos events, uptime de cada container del mini-PC
Logs Loki + Promtail HA Core errors, Z2M errors, Mosquitto errors, ESPHome device logs (vía MQTT bridge), Docker container logs en mini-PC
Resultados de actions del agente Loki (formato JSONL custom) "Agente reinició Z2M a las 02:14 — closed alert ZHA-failed-connect"

Pipeline crítica: HA Yellow → mini-PC

El Yellow corre HAOS; no es trivial instalarle Promtail. Tres opciones:

  1. HA → MQTT logs: HA puede publicar logs via MQTT (con el logger integration + un custom config). El mini-PC subscribe ese topic con un Promtail MQTT pipeline → Loki. Recomendado.
  2. HA syslog forward: HA tiene la opción de forwardear logs via syslog. Configurar syslog server en mini-PC.
  3. HA REST API polling: el agente hace polling del /api/error/all endpoint y traga. Menos elegante pero funciona sin tocar el Yellow.

Alerts priorizadas (de menos a más urgente)

Alerta Severity Notification Acción del agente
HA UI no responde (Gatus check) Critical Telegram + email immediate Restart HA Container (si es el twin) / escalar humano (si es Yellow)
Z2M reporta >2 device disconnect en 15 min Warning Telegram batched Investigate logs, propose restart en PR
HA Yellow CPU > 80% sostenido 10 min Warning Telegram batched Investigate; restart no autorizado en essentials
ESPHome device no reporta en 10 min Warning Telegram batched Investigate (Wi-Fi? OTA pendiente? off?)
Loki retention < 7 días de disk left Warning Daily digest Limpiar logs viejos / aumentar disk
Agente AI completó X fixes hoy Info Daily digest — (sólo reporting)

LogQL queries que el agente ejecuta de rutina

(Catálogo a expandir con cada incidente diagnosticado.)

# Errores HA en últimos 15 min
{job="homeassistant", level="ERROR"} | json | line_format "{{.message}}"

# Z2M connection issues
{job="zigbee2mqtt"} |= "failed to connect" | line_format "{{.timestamp}} {{.device}}"

# ESPHome device específico
{job="esphome", device="$device"} | line_format "{{.message}}"

# Agente actions del día
{job="agent"} | json | line_format "[{{.action}}] {{.target}} → {{.result}}"

Métricas Prometheus prioritarias

HA expone via el integration prometheus. Métricas clave para el smart home:

  • homeassistant_entity_available (sí/no por entity)
  • homeassistant_battery_level_percent (catch baterías bajas antes que mueran)
  • homeassistant_temperature_c, homeassistant_humidity_percent
  • homeassistant_last_updated_time_seconds (catch entities stuck)
  • homeassistant_automation_triggered_count (debug del agente)

Grafana dashboards mínimos

3 dashboards a armar (gaps, no hay JSON ready-to-import todavía):

  1. Smart Home Health Overview — status binario de essentials (luces críticas, cerraduras, calefacción, sensores).
  2. Zigbee Network Health — # devices online, LQI per device, errors por hora.
  3. Agent Activity — fixes aplicados, escalations, perímetro autónomo growth a lo largo del tiempo.

Adopción incremental (alineado con self healing adapted to user setup)

Esto está en el paso 3 del setup propuesto. Resumen del orden:

  1. Loki + Promtail + Grafana en mini-PC (1-2 días).
  2. Configurar HA → MQTT logs pipeline.
  3. Gatus con 3-5 essentials checks.
  4. Prometheus + HA Prometheus integration.
  5. Grafana data sources (Loki + Prometheus).
  6. Primer dashboard (health overview).
  7. Primeras 3-5 alerts críticas (HA down, Z2M down, mini-PC down).

Tras esto, el agente AI ya tiene fuente queryable y el usuario tiene visibilidad sin abrir HA UI.

Relaciones

Citas / evidencia

  • "Transform from a reactive debugging process into a proactive, insightful monitoring strategy." — newerest ha loki grafana.

Abierto / gaps

  • HA → MQTT logs pipeline concreta: el patrón está identificado pero falta el code real. Próxima iteración debería buscar o derivar.
  • Grafana dashboards JSON exportables para smart home — buscar o armar.
  • Prometheus exporter scrape config específico para HA — debería estar en ha prometheus integration cuando se ingiera.
  • ESPHome → Loki pipeline: device logs van vía MQTT al broker; Promtail MQTT plugin existe pero requiere config.
  • Self-monitoring del observatorio: ¿qué pasa si Loki se cae? Gatus debe monitorear Loki también.