Grafana observability
Estas son las prácticas de un stack auto-alojado de nivel productivo: alrededor de 60 dashboards, más de 400 reglas de alerta, 50 trabajos de scraping, logs y trazas, todo gestionado como código. Cada regla que aparece a continuación existe porque incumplirla causó un incidente real. Se incluye el por qué para que puedas juzgar los casos límite.
Primero, elige el modo
- Aprendizaje ("enséñame", "explica", "qué es", "examíname"): sigue references/learning-path.md. Enseña una etapa a la vez y ejecuta el laboratorio en assets/lab/. Verifica la comprensión antes de continuar. No vuelques todas las etapas de una vez.
- Construcción (un dashboard, alerta, pipeline, Terraform o despliegue): sigue el flujo de trabajo a continuación y abre solo el archivo de referencia que la tarea necesite.
- Planificar un despliegue en una organización: references/implementation-plan.md.
El stack en una imagen
apps / hosts / network kit / cloud APIs
│ métricas (exporters, /metrics) │ logs (archivos, docker, syslog) │ trazas (OTLP)
▼ ▼ ▼
Prometheus ◄── scrape ── Grafana Alloy (colector: descubre, reetiqueta, redacta, envía)
│ │ │
│ Loki Tempo
└──────────────┬────────────────────┴────────────────────────────────┘
▼
Grafana ── dashboards, Explore, alerting ──► puntos de contacto (chat, email, guardia)
▲
Terraform (carpetas, fuentes de datos, reglas, enrutamiento) + scripts (dashboards) + git
Detalles: references/architecture.md.
Las reglas estrictas
- El código es la fuente de verdad. Cambia las alertas a través de Terraform y crea los dashboards con un script generador o un JSON que viva en git. Un clic en la interfaz se pierde en el próximo apply, o peor aún, el próximo apply lo revierte silenciosamente.
- Antes de cualquier apply, verifica ambos tipos de desviación. (a) Reglas que existen en vivo pero no en código: un apply sin destino específico las elimina. (b) Reglas que están en código pero fueron cambiadas en vivo: un apply las revierte. Un plan "Sin cambios" no prueba nada sobre reglas que Terraform nunca ha visto. Consulta references/as-code.md.
- Protege el plan guardado. Ejecuta
terraform plan -out, luego rechaza cualquierdelete/replaceque no hayas planeado, en cualquier recurso. Ponprevent_destroyen las carpetas. Eliminar una carpeta de Grafana elimina todos los dashboards y reglas que contiene. - Usa un token de cuenta de servicio, nunca
admin:password. Si el estado se creó con autenticación por token, un apply con autenticación básica planifica la eliminación y recreación de carpetas, puntos de contacto y el árbol de políticas. Esto borró una vez 59 dashboards y todo el árbol de enrutamiento en un solo apply. - Nunca pongas
notification_settings(un punto de contacto) en una regla. Una regla que lo tenga se salta completamente el árbol de políticas. Escapa del enrutamiento por severidad, intervalos de repetición y silencios por horario. En un entorno, 196 de 217 reglas hacían esto y nadie lo notó. - Pon el umbral en la etapa de umbral de Grafana, no dentro del PromQL. Con
expr > 90, un host sano no devuelve series, lo que Grafana interpreta como NoData, no como OK. Consulta el valor bruto; compáralo en la etapa C. - Enruta por capacidad de acción y trata los intervalos de repetición como la verdadera palanca. Usa
severity(critical/warning/info) másurgency=backlogpara problemas crónicos conocidos. La mayor parte del ruido de las alertas es re-notificación de algo ya conocido. Repite las alertas críticas a diario y las warnings semanalmente, no cada hora. - La escalada debe ser una demora, y un silencio es el acuse de recibo. La ruta de paginación usa
group_waitde unos 15 minutos, por lo que pagina solo si la alerta sigue disparada y sin silenciar. Las reglas de tipo evento necesitankeep_firing_for≥ el tiempo de espera, o se resuelven antes de escalar. - Monitorea el monitoreo. Vigila los fallos de evaluación, los fallos de entrega de notificaciones, las alertas suprimidas (silenciadas), los exporters obsoletos y las copias de seguridad que se detuvieron. Un sistema de alertas silencioso se ve exactamente igual que uno saludable. Consulta references/meta-monitoring.md.
- Verifica, no confíes. Ejecuta cada consulta de panel o alerta contra la fuente de datos antes de escribirla. Después de cualquier escritura por API, lee el objeto de vuelta y afirma que tu cambio está en él: la respuesta POST no te dice qué contenido se subió. El acuerdo entre dos personas o dos sesiones no es verificación; un comando sí lo es.
Flujo de trabajo para cualquier cambio
- Formula la pregunta que el panel o la alerta responde, y quién actúa sobre ella. Si nadie actuara ante una alerta, es un panel de dashboard, no una alerta.
- Prueba la consulta en Explore o a través de la API proxy de la fuente de datos. Verifica que devuelve datos, que las etiquetas son aquellas por las que agruparás o enrutarás, y cómo se comporta en estado saludable (¿vacío? ¿cero?).
- Escríbela en código: un grupo de reglas de Terraform, un generador de dashboards o una configuración de Alloy. Sigue references/alerting.md o references/dashboards.md.
- Verifica la desviación, luego
terraform plan -out=tfplan. Lee cada bloque colapsado~, especialmente engrafana_notification_policy, porque decide hacia dónde va cada alerta. - Aplica el plan guardado con un token de cuenta de servicio. Usa
-targetcuando no estés seguro. - Léelo de vuelta desde la API, confirma que la regla evalúa (el estado no es Error/NoData) y, para las alertas, dispara una prueba de extremo a extremo hasta el punto de contacto real.
- Haz commit con el por qué. Deja un comentario en el código donde una decisión parezca incorrecta pero sea deliberada.
Definición de completado
Regla de alerta: en Terraform; etiqueta severity establecida; las plantillas de resumen y descripción incluyen el host o servicio afectado y el valor actual; no_data_state elegido deliberadamente; for suficientemente largo para no oscilar; enrutada por el árbol (sin punto de contacto por regla); un enlace a un runbook o un primer paso en la descripción; probada de extremo a extremo; no duplica la paginación con una regla existente.
Dashboard: en git (generado, o exportado con id/version eliminados); en la carpeta correcta; enlazado desde el hub de visión general y de vuelta; variables para entorno/host; cada panel tiene un título que pregunta o responde a una pregunta; unidades y umbrales establecidos; keepTime en los enlaces.
Nuevo exporter o fuente de datos: scrapeado con etiquetas estables (env, team, service, role); cubierto por la regla general up == 0 (no agregues una separada); si tiene una métrica de última ejecución o frescura, una regla de caducidad; añadido a la auditoría de meta-monitoreo; la fuente de datos tiene un uid fijo.
Índice de referencias
| Archivo | Ábrelo cuando |
|---|---|
| learning-path.md | enseñar o aprender, etapa por etapa con laboratorios |
| architecture.md | elegir componentes, etiquetas, retención, autenticación, alta disponibilidad |
| queries.md | escribir PromQL o LogQL, o una consulta parece incorrecta |
| dashboards.md | construir o revisar un dashboard |
| alerting.md | reglas, enrutamiento, puntos de contacto, silencios, fatiga |
| as-code.md | Terraform, API, copias de seguridad, desviación, restauraciones |
| meta-monitoring.md | probar que el monitoreo en sí funciona |
| implementation-plan.md | introducir Grafana a un equipo o empresa |
Activos: assets/lab/ es un laboratorio local con Docker Compose. assets/terraform-starter/ es un stack inicial de Terraform con los valores predeterminados seguros ya conectados.