Configure Alerting Rules

Configurar Reglas de Alerta

Configura reglas de alerta de Prometheus y Alertmanager para notificaciones de incidentes confiables y accionables.

Consulta Ejemplos Extendidos para archivos de configuración completos y plantillas.

Cuándo Usar

• Implementar monitoreo proactivo con detección automatizada de incidentes
• Enrutar alertas a los equipos apropiados según la gravedad y la propiedad del servicio
• Reducir la fatiga de alertas mediante agrupación y deduplicación inteligentes
• Integrar el monitoreo con sistemas de guardia (PagerDuty, Opsgenie)
• Establecer políticas de escalada para problemas críticos de producción
• Migrar desde sistemas de monitoreo heredados a alertas basadas en Prometheus
• Crear alertas accionables que guíen a los equipos de respuesta hacia la resolución

Entradas

• Requerido: Métricas de Prometheus para alertar (tasas de error, latencia, saturación)
• Requerido: Rotación de guardia y políticas de escalada
• Opcional: Definiciones de alertas existentes para migrar
• Opcional: Canales de notificación (Slack, correo electrónico, PagerDuty)
• Opcional: Documentación de manual de procedimientos para alertas comunes

Procedimiento

Paso 1: Desplegar Alertmanager

Instala y configura Alertmanager para recibir alertas de Prometheus.

Despliegue con Docker Compose (estructura básica):

version: '3.8'
services:
  alertmanager:
    image: prom/alertmanager:v0.26.0
    ports:
      - "9093:9093"
    volumes:
      - ./alertmanager.yml:/etc/alertmanager/alertmanager.yml
    # ... (see EXAMPLES.md for complete configuration)

Configuración básica de Alertmanager (extracto de alertmanager.yml):

global:
  resolve_timeout: 5m
  slack_api_url: 'https://hooks.slack.com/services/YOUR/SLACK/WEBHOOK'

route:
  receiver: 'default-receiver'
  group_by: ['alertname', 'cluster', 'service']
  group_wait: 30s
  group_interval: 5m
  repeat_interval: 4h

  routes:
    - match:
        severity: critical
      receiver: pagerduty-critical

# ... (see EXAMPLES.md for complete routing, inhibition rules, and receivers)

Configurar Prometheus para usar Alertmanager (prometheus.yml):

alerting:
  alertmanagers:
    - static_configs:
        - targets:
            - alertmanager:9093
      timeout: 10s
      api_version: v2

Esperado: Interfaz de Alertmanager accesible en http://localhost:9093, "Status > Alertmanagers" de Prometheus muestra estado UP.

En caso de fallo:

• Verificar los logs de Alertmanager: docker logs alertmanager
• Verificar que Prometheus pueda alcanzar Alertmanager: curl http://alertmanager:9093/api/v2/status
• Probar las URL de webhook: curl -X POST <SLACK_WEBHOOK_URL> -d '{"text":"test"}'
• Validar la sintaxis YAML: amtool check-config alertmanager.yml

Paso 2: Definir Reglas de Alerta en Prometheus

Crea reglas de alerta que se activen cuando se cumplan las condiciones.

Crear el archivo de reglas de alerta (extracto de /etc/prometheus/rules/alerts.yml):

groups:
  - name: instance_alerts
    interval: 30s
    rules:
      - alert: InstanceDown
        expr: up == 0
        for: 5m
        labels:
          severity: critical
          team: infrastructure
        annotations:
          summary: "Instance {{ $labels.instance }} is down"
          description: "{{ $labels.instance }} has been down for >5min."
          runbook_url: "https://wiki.example.com/runbooks/instance-down"

      - alert: HighCPUUsage
        expr: 100 - (avg by(instance) (rate(node_cpu_seconds_total{mode="idle"}[5m])) * 100) > 80
        for: 10m
        labels:
          severity: warning
        annotations:
          summary: "High CPU usage on {{ $labels.instance }}"
          # ... (see EXAMPLES.md for complete alerts)

Buenas prácticas de diseño de alertas:

• Duración for: Previene alertas intermitentes. Usar 5-10 minutos para la mayoría de las alertas.
• Anotaciones descriptivas: Incluir valor actual, recurso afectado y vínculo al manual.
• Niveles de gravedad: critical (llama al equipo de guardia), warning (investigar), info (para tu información)
• Etiquetas de equipo: Habilitar el enrutamiento al equipo/canal correcto
• Vínculos a manuales: Cada alerta debe tener una URL de manual

Cargar reglas en Prometheus:

# prometheus.yml
rule_files:
  - "rules/*.yml"

Validar y recargar:

promtool check rules /etc/prometheus/rules/alerts.yml
curl -X POST http://localhost:9090/-/reload

Esperado: Las alertas son visibles en la página "Alerts" de Prometheus, las alertas se activan cuando se superan los umbrales, Alertmanager recibe las alertas activadas.

En caso de fallo:

• Verificar los logs de Prometheus para errores de evaluación de reglas
• Verificar la sintaxis de reglas con promtool check rules
• Probar las consultas de alerta independientemente en la interfaz de Prometheus
• Inspeccionar las transiciones de estado de alerta: Inactive → Pending → Firing

Paso 3: Crear Plantillas de Notificación

Diseña mensajes de notificación legibles y accionables.

Crear el archivo de plantilla (extracto de /etc/alertmanager/templates/default.tmpl):

{{ define "slack.default.title" }}
[{{ .Status | toUpper }}] {{ .GroupLabels.alertname }}
{{ end }}

{{ define "slack.default.text" }}
{{ range .Alerts }}
*Alert:* {{ .Labels.alertname }}
*Severity:* {{ .Labels.severity }}
*Summary:* {{ .Annotations.summary }}
{{ if .Annotations.runbook_url }}*Runbook:* {{ .Annotations.runbook_url }}{{ end }}
{{ end }}
{{ end }}

# ... (see EXAMPLES.md for complete email and PagerDuty templates)

Usar plantillas en receptores:

receivers:
  - name: 'slack-custom'
    slack_configs:
      - channel: '#alerts'
        title: '{{ template "slack.default.title" . }}'
        text: '{{ template "slack.default.text" . }}'

Esperado: Las notificaciones tienen formato consistente, incluyen todo el contexto relevante, son accionables con vínculos a manuales.

En caso de fallo:

• Probar el renderizado de plantillas: amtool template test --config.file=alertmanager.yml
• Verificar errores de sintaxis de plantillas en los logs de Alertmanager
• Usar {{ . | json }} para depurar la estructura de datos de la plantilla

Paso 4: Configurar Enrutamiento y Agrupación

Optimiza la entrega de alertas con reglas de enrutamiento inteligentes.

Configuración de enrutamiento avanzada (extracto):

route:
  receiver: 'default-receiver'
  group_by: ['alertname', 'cluster', 'service']
  group_wait: 30s

  routes:
    - match:
        team: platform
      receiver: 'team-platform'
      routes:
        - match:
            severity: critical
          receiver: 'pagerduty-platform'
          group_wait: 10s
          repeat_interval: 15m
          continue: true   # Also send to Slack

# ... (see EXAMPLES.md for complete routing with time intervals)

Estrategias de agrupación:

# Group by alertname: All HighCPU alerts bundled together
group_by: ['alertname']

# Group by alertname AND cluster: Separate notifications per cluster
group_by: ['alertname', 'cluster']

Esperado: Las alertas se enrutan a los equipos correctos, agrupadas lógicamente, con timing apropiado para la gravedad.

En caso de fallo:

• Probar el enrutamiento: amtool config routes test --config.file=alertmanager.yml --alertname=HighCPU --label=severity=critical
• Verificar el árbol de enrutamiento: amtool config routes show --config.file=alertmanager.yml
• Verificar continue: true si la alerta debe coincidir con múltiples rutas

Paso 5: Implementar Inhibición y Silenciado

Reduce el ruido de alertas con reglas de inhibición y silencios temporales.

Reglas de inhibición (suprimir alertas dependientes):

inhibit_rules:
  # Cluster down suppresses all node alerts in that cluster
  - source_match:
      alertname: 'ClusterDown'
      severity: 'critical'
    target_match_re:
      alertname: '(InstanceDown|HighCPU|HighMemory)'
    equal: ['cluster']

  # Service down suppresses latency and error alerts
  - source_match:
      alertname: 'ServiceDown'
    target_match_re:
      alertname: '(HighLatency|HighErrorRate)'
    equal: ['service', 'namespace']

# ... (see EXAMPLES.md for more inhibition patterns)

Crear silencios de forma programática:

# Silence during maintenance
amtool silence add \
  instance=app-server-1 \
  --author="ops-team" \
  --comment="Scheduled maintenance" \
  --duration=2h

# List and manage silences
amtool silence query
amtool silence expire <SILENCE_ID>

Esperado: La inhibición reduce las alertas en cascada automáticamente, los silencios previenen notificaciones durante el mantenimiento planificado.

En caso de fallo:

• Probar la lógica de inhibición con alertas en vivo
• Verificar la pestaña "Silences" en la interfaz de Alertmanager
• Verificar que los matchers del silencio sean exactos (las etiquetas deben coincidir perfectamente)

Paso 6: Integrar con Sistemas Externos

Conecta Alertmanager con PagerDuty, Opsgenie, Jira, etc.

Integración con PagerDuty (extracto):

receivers:
  - name: 'pagerduty'
    pagerduty_configs:
      - routing_key: 'YOUR_INTEGRATION_KEY'
        severity: '{{ .CommonLabels.severity }}'
        description: '{{ range .Alerts.Firing }}{{ .Annotations.summary }}{{ end }}'
        details:
          firing: '{{ .Alerts.Firing | len }}'
          alertname: '{{ .GroupLabels.alertname }}'
        # ... (see EXAMPLES.md for complete integration examples)

Webhook para integraciones personalizadas:

receivers:
  - name: 'webhook-custom'
    webhook_configs:
      - url: 'https://your-webhook-endpoint.com/alerts'
        send_resolved: true

Esperado: Las alertas crean incidentes en PagerDuty, aparecen en los canales de comunicación del equipo, activan las escaladas de guardia.

En caso de fallo:

• Verificar que las claves/tokens de API sean válidos
• Verificar la conectividad de red a los servicios externos
• Probar los endpoints de webhook independientemente con curl
• Habilitar el modo de depuración: --log.level=debug

Validación

• Alertmanager recibe alertas de Prometheus correctamente
• Las alertas se enrutan a los equipos correctos según etiquetas y gravedad
• Las notificaciones se entregan a Slack, correo electrónico o PagerDuty
• La agrupación de alertas reduce el volumen de notificaciones apropiadamente
• Las reglas de inhibición suprimen las alertas dependientes correctamente
• Los silencios previenen notificaciones durante las ventanas de mantenimiento
• Las plantillas de notificación incluyen vínculos a manuales y contexto
• El intervalo de repetición previene la fatiga de alertas para problemas de larga duración
• Las notificaciones de resolución se envían cuando las alertas se eliminan
• Las integraciones externas (PagerDuty, Opsgenie) crean incidentes

Errores Comunes

• Fatiga de alertas: Demasiadas alertas de baja prioridad hacen que los equipos ignoren las críticas. Establecer umbrales estrictos, usar inhibición.
• Falta de duración for: Las alertas sin for se activan en picos transitorios. Siempre usar ventanas de 5-10 minutos.
• Agrupación demasiado amplia: Agrupar por ['...'] envía notificaciones individuales. Usar agrupación de etiquetas específica.
• Sin vínculos a manuales: Las alertas sin manuales dejan a los equipos adivinando. Cada alerta necesita una URL de manual.
• Gravedad incorrecta: Etiquetar advertencias como críticas desensibiliza al equipo. Reservar crítico para emergencias.
• Silencios olvidados: Los silencios sin expiración pueden ocultar problemas reales. Siempre establecer tiempos de fin.
• Ruta única: Todas las alertas a un canal pierde contexto. Usar enrutamiento específico por equipo.
• Sin inhibición: Las alertas en cascada durante interrupciones crean ruido. Implementar reglas de inhibición.

Habilidades Relacionadas

• setup-prometheus-monitoring - Definir métricas y reglas de grabación que alimentan las reglas de alerta
• define-slo-sli-sla - Generar alertas de tasa de quema de SLO para la gestión del presupuesto de error
• write-incident-runbook - Crear manuales vinculados desde las anotaciones de alerta
• build-grafana-dashboards - Visualizar el historial de activación de alertas y patrones de silencio