Ruta guiada: Entender observabilidad¶
Guía paso a paso para comprender y desplegar el pipeline completo de observabilidad de 
SmallCountry: métricas, logs, trazas, dashboards y alertas que te dicen qué pasa en cada rincón del ecosistema.
¿Para quién es esta ruta?¶
Para quien quiera entender cómo SmallCountry vigila su propia salud. No necesitas ser administrador de sistemas —esta ruta empieza por los porqués antes de llegar a los cómos—, pero ayuda tener acceso a Grafana para explorar los dashboards mientras lees. Si ya tienes la infraestructura base funcionando, el despliegue del stack de observabilidad será directo.
1. Filosofía de observabilidad¶
Antes de instalar nada, entiende por qué observabilidad no es solo monitorización. Es la capacidad de hacer preguntas nuevas al sistema y obtener respuestas sin tener que desplegar código nuevo.
Principio 8 — Observabilidad integral — Todo lo que corre emite métricas, todo lo que emite métricas tiene un dashboard, y todo dashboard dispara alertas cuando algo se sale de lo normal.
También relevante: Mecanismo 7 — Presupuesto de Observabilidad, que define cuánta observabilidad es suficiente sin que el coste de vigilar supere el coste de lo vigilado.
2. Arquitectura del pipeline¶
Visualiza el camino completo que recorren los datos: desde que un sensor emite una métrica hasta que ves la gráfica en Grafana.
Sistema de Observabilidad — Visión global con el diagrama Mermaid del pipeline: emisores → recolección → almacenamiento → visualización.
Fíjate en la tabla de cobertura por servicio. No todos los servicios necesitan trazas distribuidas; un sensor de temperatura no gana nada con trazabilidad. La observabilidad es proporcional a la criticidad.
3. Métricas con Prometheus + VictoriaMetrics¶
Prometheus recolecta métricas por sondeo de todos los servicios. VictoriaMetrics las almacena de forma eficiente y compatible con PromQL.
Prometheus Stack — Ficha con reglas de scrape, Alertmanager y configuración de targets.
VictoriaMetrics — TSDB ligera con retención configurable y compatibilidad total con PromQL.
La decisión de usar VictoriaMetrics en lugar de Prometheus para almacenamiento a largo plazo está documentada en el ADR-011.
4. Logs con VictoriaLogs¶
Los logs de todos los servicios se centralizan en VictoriaLogs. En lugar de hacer SSH a cada LXC para leer logs, consultas todo desde un solo punto con LogQL.
VictoriaLogs — Ficha con ingesta de logs, consultas y retención.
Verifica que los logs de los servicios Tier S y A están llegando. Un servicio sin logs es un punto ciego.
5. Trazas con Tempo¶
Las trazas distribuidas te permiten seguir una petición a través de múltiples servicios. Si una consulta de IA tarda mucho, ¿es culpa de Ollama, de Qdrant o de la red?
Tempo — Backend de trazas compatibles con OpenTelemetry.
No todos los servicios emiten trazas. Consulta la tabla de cobertura en el Sistema de Observabilidad para saber cuáles sí.
6. Dashboards con Grafana¶
Grafana unifica todas las fuentes de datos en dashboards visuales. Cada dashboard está versionado en Forgejo como código JSON.
Grafana — Ficha con fuentes de datos, dashboards principales y exportación.
Explora los dashboards que ya existen: Infraestructura General, Modo Isla, Finca, Backups, IA Local, Energía. Cada uno cuenta una historia distinta sobre la salud del sistema.
7. Agentes con Grafana Alloy¶
Grafana Alloy es el agente que recolecta métricas, logs y trazas de cada nodo y los envía al backend correspondiente. Sustituye al antiguo Grafana Agent.
Grafana Alloy — Ficha con configuración de pipelines OpenTelemetry.
Cada nodo físico (Ra, Horus, Geb, Thoth) debe tener Alloy corriendo. Es el primer eslabón de la cadena de observabilidad: si Alloy no funciona en un nodo, ese nodo es invisible.
8. Alerting y Uptime Kuma¶
Tener dashboards bonitos no sirve de nada si nadie mira cuando algo falla. Las alertas cierran el ciclo.
Uptime Kuma — Monitor de disponibilidad que hace ping a cada servicio y avisa si no responde.
Prometheus Stack — Alertmanager dispara notificaciones cuando las métricas superan umbrales.
Configura al menos: alertas de disco lleno (>80%), RAM saturada (>90%), servicio caído (healthcheck fallido 3 veces seguidas) y backup fallido. Las notificaciones llegan por ntfy y Matrix.
¿Ya terminaste? Ver también¶
- Runbooks de emergencia — Con la observabilidad funcionando, necesitas saber qué hacer cuando salta una alerta.
- Estado Global — Dashboard de alto nivel que resume la salud de todo el ecosistema.
- Diccionario de alertas — Catálogo de todas las alertas configuradas, su significado y la acción recomendada.