Saltar a contenido

Stack de logging centralizado (Loki + Promtail + Grafana)

Patrón estándar para agregar logs de múltiples servicios, queryarlos con LogQL y alertar proactivamente. Sin esto, "no tinkering" es ilusorio porque el usuario tendría que abrir HA UI y scrollear logs cada vez que sospecha que algo no anda. El agente AI tampoco puede diagnosticar sin un endpoint queryable.

Contexto

Es la capa 4 del self-healing stack. Habilita el resto: sin logs centralizados, no hay detection proactiva, no hay diagnosis automatizada, no hay aprendizaje del agente sobre qué se rompe.

Contenido

Componentes

  1. Promtail (agente): scrapes log files locales, los streams a Loki. Configurable con pipeline_stages para parsear/labelear/dropear logs en source.
  2. Loki (storage + query engine): time-series store optimizado para logs. Habla LogQL (sintaxis Prometheus-like).
  3. Grafana (UI + alerting): visualización de queries Loki, dashboards, alertas a múltiples canales (Telegram, email, webhook).

Flujo

HA / Z2M / ESPHome / mini-PC services
        │
        ▼ (file logs)
   Promtail (scrape + filter)
        │
        ▼ (HTTP push)
       Loki (store + index)
        │
        ▼ (LogQL queries)
     Grafana (dashboards + alerts)
        │
        ▼ (webhook)
   Agente AI / Telegram / email

Aplicado al setup del usuario

Source de logs Cómo se ingiere
HA Core (/var/log/home-assistant.log o equivalente HAOS) Promtail con regex pipeline para parsear level/component
Z2M Promtail con job aparte; Z2M loguea en formato distinto
ESPHome devices Cada device emite logs via syslog o MQTT; necesita Promtail con syslog o pipeline custom MQTT→Loki
Mosquitto Standard mosquitto log file → Promtail
Docker container logs Promtail con docker_sd_configs
Gatus health check failures Webhook directo a Grafana, o emit a Loki via custom integration

Patrón "alerta proactiva" (LogQL templates)

# Alerta si HA loguea cualquier ERROR
count_over_time({job="homeassistant", level="ERROR"}[5m]) > 0

# Alerta si Zigbee tiene >2 connection failures en 15 min (catch intermittent glitches)
count_over_time(
  {job="homeassistant", component=~".*zigbee.*", level="ERROR"} |= "failed to connect"
[15m]) > 2

# Alerta si Z2M está down (no logs recibidos en 5 min)
absent_over_time({job="zigbee2mqtt"}[5m])

# Alerta si ESPHome device específico no reporta
absent_over_time({job="esphome", device="sensor_cocina"}[10m])

Patrón "agente AI usa Loki como input"

El agente del Q10 strategy llama Loki HTTP API directo:

curl -G -s "http://loki:3100/loki/api/v1/query_range" \
  --data-urlencode "query={job=\"homeassistant\", level=\"ERROR\"}" \
  --data-urlencode "start=$(date -u -d '15 min ago' +%s)000000000" \
  --data-urlencode "end=$(date -u +%s)000000000"

Output JSON → el agente parsea y razona. Patrón estándar para Q10.

Tuning

  • Retention: 30 días default es razonable para smart home. Si hay constraint de disco, bajar a 14.
  • Drop noise en Promtail: ESPHome puede ser muy verbose en DEBUG; drop reglas evitan llenar Loki.
  • HA logger config: control granular antes de que el log salga de HA. logger: default: warning, logs: homeassistant.components.zha: info.

Failure modes del stack mismo (meta)

  • Loki down: alertas dejan de funcionar. Critical: monitorear Loki con Gatus o Prometheus self-check.
  • Disk lleno (logs acumulados): retention falla. Monitorear df del directorio de Loki.
  • Promtail desconectado: los logs siguen en disco pero no llegan a Loki. Pipeline silencioso fallido.

Aplicación al "invisible smart home"

El usuario no debería tener que mirar ni los logs ni el Grafana. Los alerts deben ser únicos y accionables, no inundación de notifications. Heurística:

Severity Notification
Critical (essentials down) Telegram immediate + email
Warning (experimental misbehaving, intermitencia) Telegram batched (1x/hour)
Info (cambios del agente) Daily digest
Debug No notification — sólo en Grafana para investigación

Relaciones

Citas / evidencia

Abierto / gaps

  • Pipeline concreta para ESPHome logs vía MQTT (gap específico — el patrón general no aplica directo porque ESPHome no escribe a un file central por default).
  • Cómo integrar Prometheus metrics además de logs (mismo Grafana puede leer ambos).
  • Templates Grafana dashboards específicos para smart home (gap: encontrar / armar JSON exportables).