Grafana: alertas complejas con variables y GitOps
La evolución de las alertas: de simples umbrales a lógica compleja
En la administración de sistemas moderna, el monitoreo ya no se trata solo de levantar dashboards bonitos. La verdadera madurez operativa se mide en la capacidad de detectar anomalías antes de que impacten al usuario final. Grafana, en su versión 9 y superiores, ha unificado su motor de alertas (unified alerting) para permitir evaluaciones de series temporales con lógica avanzada, pero muchos equipos siguen configurando alertas manualmente, una a una, generando un infierno de mantenimiento. Este artículo explora dos estrategias que, combinadas, llevan tu monitoreo al siguiente nivel: el uso de variables de plantilla dentro de reglas de alerta y la implementación de provisioning GitOps para gestionar todo como código.
El poder oculto de las variables en alertas
Cuando pensamos en variables de plantilla en Grafana, lo primero que viene a la mente son los dashboards interactivos. Sin embargo, el sistema de alertas unificado permite usar estas mismas variables dentro de las consultas que definen una condición. La clave está en que una regla de alerta no es estática: puede referenciar etiquetas (labels) de las series, usar expresiones matemáticas y, crucialmente, disparar una alerta por cada combinación de labels sin necesidad de crear reglas duplicadas.
Imagina que tienes 50 servidores web. En lugar de crear 50 alertas de CPU, creas una sola regla que evalúa la métrica cpu_usage agrupada por instancia. Grafana generará una instancia de alerta separada para cada servidor. Esto es posible gracias al modelo de datos de Prometheus o la consulta SQL que devuelva múltiples series.
Ejemplo práctico: alerta por instancia con umbral dinámico
Supongamos que usamos Prometheus como fuente de datos. La siguiente consulta calcula el uso de CPU por instancia y lo compara contra un umbral que varía según el entorno:
100 - (avg(rate(node_cpu_seconds_total{mode="idle"}[5m])) by (instance) * 100) > {{ $labels.env == "prod" ? 80 : 60 }}
Este ejemplo es ilustrativo, pero la sintaxis exacta no permite operadores ternarios. En Grafana, la gracia viene al usar variables de plantilla definidas a nivel de la regla, no de la consulta. Puedes definir una variable $umbral en la regla, y luego usar ${umbral} dentro de la expresión. Sin embargo, el verdadero poder aparece con las alertas multi-dimensionales: si tu consulta devuelve series con labels env="prod" y env="dev", puedes usar la función label_values() en la definición de la variable para extraer esos valores y luego crear condiciones condicionales.
Alertas complejas con reducción y expresiones
El engine de alertas usa un pipeline de consultas y expresiones. Para lógica compleja, concatenamos operaciones:
- Consulta A:
rate(http_requests_total[5m])porpathymethod. - Expresión B (Math):
$A * 0.95para aplicar un factor de corrección. - Expresión C (Reduce):
max()para agrupar la serie en un solo valor por label. - Expresión D (Threshold):
IS ABOVE 100.
Esta cadena permite alertar solo cuando el pico máximo supera el umbral, ignorando valles. Para alertar cuando el promedio excede cierto valor durante 10 minutos, usarías avg() en la reducción. Combinar reduce y math abre un abanico enorme: puedes calcular la diferencia entre dos métricas, aplicar logaritmos, o comparar la tasa actual contra un promedio móvil de la semana pasada usando consultas de rango completo.
Provisioning GitOps: alertas como código
La configuración manual de alertas es frágil y no auditable. El provisioning de Grafana permite definir fuentes de datos, dashboards y, desde la versión 9.4, también alert rules y contact points mediante archivos YAML. Esto nos permite aplicar los principios de GitOps: el repositorio Git es la única fuente de verdad, los cambios pasan por pull requests y CI/CD, y la configuración se aplica automáticamente.
Estructura de archivos para provisioning
Se define en la configuración principal de Grafana (generalmente /etc/grafana/grafana.ini o variables de entorno). Un setup típico:
[provisioning]
alerting = /etc/grafana/provisioning/alerting/
Dentro de este directorio, creamos dos archivos:
alerting.ymlpara cargar policy y contact points.rules.ymlpara las reglas de alerta.
Ejemplo de alerting.yml:
apiVersion: 1
contactPoints:
- orgId: 1
name: 'Slack SRE'
receivers:
- uid: 'slack-sre'
type: slack
settings:
address: 'https://hooks.slack.com/services/T000000/B000000/XXXX'
disableResolveMessage: false
policies:
- orgId: 1
receiver: 'Slack SRE'
group_by: ['alertname', 'instance']
group_wait: 30s
group_interval: 5m
repeat_interval: 4h
La clave aquí es group_by: al agrupar por instance, una tormenta de alertas se convierte en una sola notificación con múltiples etiquetas, reduciendo el ruido.
Definiendo reglas complejas en YAML
Ahora el archivo rules.yml, donde residen las alertas complejas. Aquí podemos usar plantillas Go para generar consultas dinámicas. Un ejemplo con variable de plantilla aplicada a una regla:
apiVersion: 1
groups:
- orgId: 1
name: 'Alta latencia por endpoint'
folder: 'Producción'
interval: 1m
rules:
- uid: 'latency-p95'
title: 'P95 latencia alta en {{ $labels.job }}'
condition: 'C'
data:
- refId: 'A'
datasourceUid: 'prometheus'
queryType: 'range'
model:
expr: 'histogram_quantile(0.95, sum(rate(http_request_duration_seconds_bucket[5m])) by (le, job))'
instant: false
relativeTimeRange:
from: 300
to: 0
- refId: 'B'
datasourceUid: '__expr__'
type: 'reduce'
expression: 'A'
reducer: 'last'
- refId: 'C'
datasourceUid: '__expr__'
type: 'threshold'
expression: 'B'
conditions:
- evaluator:
type: 'gt'
params: [500]
operator:
type: 'and'
noDataState: 'NoData'
execErrState: 'Error'
for: '5m'
labels:
severity: 'critical'
team: 'backend'
annotations:
summary: 'Latencia P95 supera 500ms en job {{ $labels.job }}'
Observa que en el campo title y annotations usamos {{ $labels.job }}. En el provisionamiento, Grafana no reemplaza estas plantillas hasta el momento de la evaluación, lo que permite alertas personalizadas por serie. Además, la subconsulta histogram_quantile es una operación compleja que sería tediosa de replicar en 20 reglas manuales.
Flujo de trabajo GitOps con CI/CD
El ciclo de vida ideal es:
- El ingeniero modifica
rules.ymlen una rama. - Abre un Pull Request. El pipeline de CI valida la sintaxis YAML con
yaml-linty opcionalmente con el API de Grafana (curl -X POST http://grafana:3000/api/v1/provisioning/alert-rulespara simular). - El merge a main dispara un job que copia los archivos al volumen del contenedor de Grafana.
- Grafana detecta cambios en los archivos y los recarga automáticamente (si el
provisioningestá en modowatch).
Para forzar la recarga manualmente sin esperar el watcher, podemos usar el endpoint interno:
curl -X POST http://localhost:3000/api/admin/provisioning/alerting/reload -H "Authorization: Bearer $GRAFANA_API_TOKEN"
Este comando es útil en entornos con alta seguridad donde el watcher está