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

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