grafana-observability

Aprende, diseña, construye y opera un stack de observabilidad con Grafana (métricas con Prometheus, logs con Loki, trazas con Tempo, recolección con Alloy, dashboards y alertas) gestionado como código con Terraform. Úsalo para aprender o enseñar Grafana, PromQL o LogQL; para configurar monitoreo; para escribir o revisar un dashboard, una regla de alerta, una política de notificación, un punto de contacto, un pipeline de Alloy o Terraform para Grafana; o para depurar alertas ruidosas, silenciosas, atascadas en NoData o que no llegan a nadie.

¿Qué es grafana-observability?

Esta skill proporciona un conjunto completo de prácticas y referencias para construir y operar un stack de observabilidad de Grafana de nivel productivo, gestionado completamente como código. Está diseñada para tres modos de uso: aprendizaje (con una ruta de aprendizaje y un laboratorio Docker Compose local), construcción (dashboards, alertas, pipelines, Terraform) y planificación de despliegue en una organización. La skill se basa en más de 60 dashboards, 400+ reglas de alerta, 50 trabajos de scraping, logs y trazas, todo gestionado con Terraform. Cada regla documentada existe porque su incumplimiento causó un incidente real. Funciona en plataformas como Claude Code, Cursor y Codex, y su estructura modular permite al usuario abrir solo el archivo de referencia que necesita para la tarea actual. Entre sus principios clave destacan: el código es la fuente de verdad, verificar la desviación antes de cada `apply`, proteger el plan guardado contra eliminaciones no intencionadas, no usar `admin:password`, no poner `notification_settings` en las reglas, poner el umbral en la etapa de Grafana y no dentro de PromQL, enrutar por capacidad de acción, usar silencios como acuse de recibo, monitorizar el monitoreo mismo y verificar cada cambio leyendo el objeto de vuelta desde la API.

Compatible con~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/louij2/grafana-observability-skill/tree/HEAD/.github/skills/grafana-observability

Installed? Explore more Productividad y colaboración skills: steipete/gemini, steipete/gh-issues, steipete/skill-creator · View all 6 →

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

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

  1. 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.
  2. 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.
  3. Protege el plan guardado. Ejecuta terraform plan -out, luego rechaza cualquier delete/replace que no hayas planeado, en cualquier recurso. Pon prevent_destroy en las carpetas. Eliminar una carpeta de Grafana elimina todos los dashboards y reglas que contiene.
  4. 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.
  5. 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ó.
  6. 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.
  7. Enruta por capacidad de acción y trata los intervalos de repetición como la verdadera palanca. Usa severity (critical/warning/info) más urgency=backlog para 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.
  8. La escalada debe ser una demora, y un silencio es el acuse de recibo. La ruta de paginación usa group_wait de unos 15 minutos, por lo que pagina solo si la alerta sigue disparada y sin silenciar. Las reglas de tipo evento necesitan keep_firing_for ≥ el tiempo de espera, o se resuelven antes de escalar.
  9. 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.
  10. 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

  1. 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.
  2. 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?).
  3. 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.
  4. Verifica la desviación, luego terraform plan -out=tfplan. Lee cada bloque colapsado ~, especialmente en grafana_notification_policy, porque decide hacia dónde va cada alerta.
  5. Aplica el plan guardado con un token de cuenta de servicio. Usa -target cuando no estés seguro.
  6. 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.
  7. 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.mdenseñar o aprender, etapa por etapa con laboratorios
architecture.mdelegir componentes, etiquetas, retención, autenticación, alta disponibilidad
queries.mdescribir PromQL o LogQL, o una consulta parece incorrecta
dashboards.mdconstruir o revisar un dashboard
alerting.mdreglas, enrutamiento, puntos de contacto, silencios, fatiga
as-code.mdTerraform, API, copias de seguridad, desviación, restauraciones
meta-monitoring.mdprobar que el monitoreo en sí funciona
implementation-plan.mdintroducir 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.

Skills relacionados