Volver al blog

Alertas de Prometheus Alertmanager en tu teléfono: enrutamiento por severidad, agrupación y resoluciones silenciosas

Alertas de Prometheus Alertmanager en tu teléfono: enrutamiento por severidad, agrupación y resoluciones silenciosas

Prometheus es bueno detectando que algo va mal. Hacer llegar esa noticia a una persona es trabajo de Alertmanager, y en muchas configuraciones la noticia acaba en una carpeta de correo o en un canal de Slack que nadie lee a las 3 de la mañana.

Alertmanager no tiene una aplicación push propia, pero sí tiene un receptor de webhook genérico, y eso es todo lo que necesitas para recibir alertas en el teléfono. Esta guía lo configura con enrutamiento por severidad: las alertas critical llegan con sonido, las advertencias llegan como notificaciones normales y los avisos de "resolved" llegan en silencio. Todo lo que aparece aquí se probó con Alertmanager 0.34.2 y Prometheus 3.15.1 en Docker. Los payloads se capturaron y se procesaron con el código de plantillas de Pocket Alert.

Qué necesitas

  • Alertmanager 0.31 o posterior para la configuración completa. Las versiones anteriores se explican más abajo.
  • La aplicación de Pocket Alert en tu iPhone o Android y una clave de API de Claves de API.
  • Un plan de pago para la configuración con tres webhooks, porque el plan gratuito incluye un webhook. Hay una versión con un solo webhook cerca del final.

Qué envía Alertmanager

Alertmanager no envía una petición por cada alerta. Reúne las alertas en grupos según las etiquetas de group_by y envía una notificación por grupo: un POST con un cuerpo JSON fijo, "version": "4". Cuando caen dos hosts con group_by: ['alertname'], sale una sola petición. Aquí tienes un ejemplo, un poco recortado:

{
  "receiver": "pocketalert-critical",
  "status": "firing",
  "alerts": [
    {
      "status": "firing",
      "labels": {"alertname": "InstanceDown", "instance": "web-1:9100", "job": "node", "severity": "critical"},
      "annotations": {"summary": "web-1:9100 is down"},
      "startsAt": "2026-10-31T16:17:04.374Z",
      "generatorURL": "http://prometheus.example.com:9090/graph?g0.expr=up%7Bjob%3D%22node%22%7D+%3D%3D+0&g0.tab=1"
    },
    {
      "status": "firing",
      "labels": {"alertname": "InstanceDown", "instance": "web-2:9100", "job": "node", "severity": "critical"},
      "annotations": {"summary": "web-2:9100 is down"}
    }
  ],
  "notification_reason": "first notification",
  "groupLabels": {"alertname": "InstanceDown"},
  "commonLabels": {"alertname": "InstanceDown", "job": "node", "severity": "critical"},
  "commonAnnotations": {},
  "routeLabels": {},
  "externalURL": "http://alertmanager.example.com:9093",
  "version": "4",
  "groupKey": "{}/{severity=\"critical\"}:{alertname=\"InstanceDown\"}",
  "truncatedAlerts": 0
}

Hay cuatro cosas en esta estructura que determinan la configuración:

  • Una notificación push por grupo. Las alertas individuales están en el array alerts, así que la plantilla del mensaje tiene que trabajar con un array.
  • commonAnnotations suele estar vacío. Solo contiene anotaciones idénticas en todas las alertas del grupo. Un resumen que menciona la instancia es distinto en cada alerta, así que nunca aparece ahí.
  • status pertenece al grupo. Es resolved solo cuando todas las alertas del grupo están resueltas. Cuando un host se recupera y otro sigue caído, el estado sigue siendo firing y la alerta recuperada aparece dentro con su propio "status": "resolved".
  • No hay un campo level de nivel superior, que es donde un webhook de Pocket Alert busca la prioridad. Por eso la prioridad viene del nivel por defecto del webhook, y esta guía usa un webhook por cada nivel de sonido.

Paso 1: Crea los webhooks de Pocket Alert

Webhookdefault_levelRecibe
Prometheus critical2 (critical)Grupos en firing con severity="critical"
Prometheus warning0 (default)Todos los demás grupos en firing
Prometheus resolved-1 (low)Grupos en los que todas las alertas se han resuelto

Los botones solo se pueden configurar mediante la API, así que crea los tres con un único script:

PA_KEY='your-api-key'

FIRING='%groupLabels.alertname%: %alerts.#(status=="firing")#|#% firing
%alerts.#(status=="firing").annotations.summary%
Firing: %alerts.#(status=="firing")#.labels.instance%'

RESOLVED='Resolved: %groupLabels.alertname% (%commonLabels.severity%)
%alerts.#.labels.instance%'

BUTTONS='[{"type":"view","label":"Alertmanager","value":"%externalURL%"}]'

create_webhook() {
  jq -n --arg name "$1" --argjson level "$2" --arg message "$3" --arg actions "$4" \
    '{name: $name, default_level: $level, message: $message, actions: $actions}' |
  curl -sS https://api.pocketalert.app/v1/webhooks \
    -H "Token: $PA_KEY" \
    -H 'Content-Type: application/json' \
    --data-binary @- |
  jq -r '"\(.name): https://p4a.me/wh/\(.url)"'
}

create_webhook 'Prometheus critical' 2 "$FIRING" "$BUTTONS"
create_webhook 'Prometheus warning' 0 "$FIRING" "$BUTTONS"
create_webhook 'Prometheus resolved' -1 "$RESOLVED" ''

Imprime tres URL de recepción. Guarda el slug del final de cada una; pegarás los slugs en alertmanager.yml.

Los marcadores %...% son rutas GJSON, y GJSON puede consultar arrays:

  • alerts.#(status=="firing")#|# cuenta las alertas del grupo que siguen en firing.
  • alerts.#(status=="firing").annotations.summary es el resumen de la primera alerta en firing.
  • alerts.#(status=="firing")#.labels.instance lista las instancias de todas las alertas en firing. Se muestra como un array JSON, como ["web-1:9100","web-2:9100"], porque no existe una función para unir cadenas.

Una ruta que no existe se muestra como una cadena vacía, así que una ruta incorrecta da una línea en blanco, no una alerta perdida. Pocket Alert pone a cada notificación de webhook el título Webhook <name>, así que el título dice "Webhook Prometheus critical" y el nombre de la alerta va en la primera línea del mensaje. critical necesita un plan de pago, que esta configuración requiere de todas formas para los tres webhooks. Suena aunque el iPhone esté en silencio o en No molestar, y ocupa la pantalla en Android. Usa 1 (high) si no quieres que las alertas anulen No molestar.

Paso 2: alertmanager.yml

Sustituye los tres marcadores *_SLUG por tus slugs:

route:
  receiver: pocketalert-warning
  group_by: ['alertname']
  group_wait: 30s
  group_interval: 5m
  repeat_interval: 4h
  routes:
    - matchers: ['severity="critical"']
      receiver: pocketalert-critical
      group_wait: 10s
      repeat_interval: 1h
    - matchers: ['severity="info"']
      receiver: blackhole

receivers:
  - name: pocketalert-critical
    webhook_configs:
      - url: 'https://p4a.me/wh/{{ if eq .Status "resolved" }}RESOLVED_SLUG{{ else }}CRITICAL_SLUG{{ end }}'
        send_resolved: true
        max_alerts: 20
  - name: pocketalert-warning
    webhook_configs:
      - url: 'https://p4a.me/wh/{{ if eq .Status "resolved" }}RESOLVED_SLUG{{ else }}WARNING_SLUG{{ end }}'
        send_resolved: true
        max_alerts: 20
  - name: blackhole

inhibit_rules:
  - source_matchers: ['severity="critical"']
    target_matchers: ['severity="warning"']
    equal: ['alertname', 'instance', 'mountpoint']

Cómo funcionan las piezas:

  • Enrutamiento por severidad. severity="critical" va al receptor con sonido, info se descarta y todo lo demás, incluidas las alertas sin una etiqueta severity, cae en el receptor de advertencias.
  • La URL elige el webhook. Desde la 0.31.0, la url del webhook es una plantilla. Un grupo cuyo estado es resolved va al webhook silencioso, y todo lo demás va al webhook propio del receptor. send_resolved ya es true por defecto en los webhooks; se escribe explícitamente para que nadie lo desactive sin darse cuenta.
  • max_alerts: 20 limita cuántas alertas entran en una misma petición. En la prueba, 25 hosts cayeron a la vez. Eso produjo una notificación push que decía "20 firing", y truncatedAlerts: 5 en el payload.
  • Inhibición. Cuando la alerta crítica DiskSpaceLow se activa para un sistema de archivos, se silencia la advertencia con el mismo alertname, instance y mountpoint. amtool alert query --inhibited la muestra como suppressed.

Comprueba la configuración y el enrutamiento antes de recargar:

amtool check-config alertmanager.yml
amtool config routes test --config.file=alertmanager.yml severity=critical alertname=Test

El segundo comando imprime pocketalert-critical.

Inicia Alertmanager con --web.external-url apuntando a la dirección que puedas abrir desde tu teléfono. Sin esta opción, externalURL es solo el nombre de host. En Docker, eso fue http://de48ea5ffc29:9093, lo que hace que el botón no sirva para nada.

Comprueba antes tu versión

alertmanager --version tiene que indicar 0.31 o posterior para que funcione la URL con plantilla. La versión 0.30.1 acepta esta configuración exacta y amtool check-config informa de SUCCESS, pero no procesa la plantilla. Envió la petición a /wh/%7B%7B%20if%20eq%20.Status..., que no coincide con ningún webhook. En versiones anteriores, asigna a cada receptor la URL simple de su propio webhook. Las notificaciones de resolución llegarán entonces con el nivel de ese webhook.

Paso 3: Reglas con una etiqueta de severidad

El enrutamiento anterior solo funciona si tus reglas definen severity. Aquí tienes dos ejemplos (más ideas sobre qué vigilar están en la página de monitorización de servidores), con DiskSpaceLow en dos umbrales para que la regla de inhibición tenga algo que hacer:

groups:
  - name: node
    rules:
      - alert: InstanceDown
        expr: up{job="node"} == 0
        for: 2m
        labels:
          severity: critical
        annotations:
          summary: '{{ $labels.instance }} is down'

      - alert: DiskSpaceLow
        expr: node_filesystem_avail_bytes{fstype!~"tmpfs|overlay"} / node_filesystem_size_bytes * 100 < 15
        for: 10m
        labels:
          severity: warning
        annotations:
          summary: '{{ $labels.instance }} {{ $labels.mountpoint }} has {{ printf "%.0f" $value }}% free'

      - alert: DiskSpaceLow
        expr: node_filesystem_avail_bytes{fstype!~"tmpfs|overlay"} / node_filesystem_size_bytes * 100 < 5
        for: 5m
        labels:
          severity: critical
        annotations:
          summary: '{{ $labels.instance }} {{ $labels.mountpoint }} has {{ printf "%.0f" $value }}% free'

promtool check rules rules.yml valida el archivo. Indica a Prometheus el archivo y Alertmanager en prometheus.yml:

rule_files: [rules.yml]
alerting:
  alertmanagers:
    - static_configs:
        - targets: ['alertmanager:9093']

Pruébalo con amtool

Dispara una alerta de prueba, espera el group_wait (10 segundos en la ruta crítica) y resuélvela:

amtool --alertmanager.url=http://localhost:9093 alert add alertname=PocketAlertTest severity=critical instance=test:9100 \
  --annotation='summary="Test alert from amtool"'

amtool --alertmanager.url=http://localhost:9093 alert add alertname=PocketAlertTest severity=critical instance=test:9100 \
  --annotation='summary="Test alert from amtool"' --end="$(date -u +%Y-%m-%dT%H:%M:%SZ)"

Mantén las comillas dobles internas en la anotación, o amtool avisará de que ha recurrido a su analizador antiguo. La notificación de resolución llega en el siguiente ciclo de group_interval, que con esta configuración puede tardar hasta 5 minutos.

Lo que llega a tu teléfono

Estos son los mensajes que Pocket Alert genera a partir de los payloads reales de la prueba, en la que Prometheus vio caer y volver web-1 y web-2:

Webhook Prometheus critical
InstanceDown: 2 firing
web-1:9100 is down
Firing: ["web-1:9100","web-2:9100"]

Cuando web-1 se recupera, Alertmanager envía una actualización en el siguiente group_interval. El grupo sigue en firing, así que va al webhook crítico:

Webhook Prometheus critical
InstanceDown: 1 firing
web-2:9100 is down
Firing: ["web-2:9100"]

Cuando los dos están de vuelta, llega una notificación push de prioridad baja:

Webhook Prometheus resolved
Resolved: InstanceDown (critical)
["web-1:9100","web-2:9100"]

Temporizadores: evitar tormentas de notificaciones

AjusteQué haceAquí
group_waitCuánto espera un grupo nuevo a más alertas antes de la primera notificación push30s, 10s para critical
group_intervalIntervalo mínimo entre notificaciones push para un grupo cuyas alertas han cambiado5m
repeat_intervalRecordatorio para un grupo que sigue en firing y sin cambios4h, 1h para critical

Un grupo puede enviar como máximo una notificación push por cada group_interval, así que una alerta intermitente cuesta hasta 12 notificaciones por hora con 5m. Una caída que dura un día cuesta 24 recordatorios con un repeat_interval de 1h. La agrupación hace la mayor parte del trabajo: un fallo de conmutador que tumba 40 hosts son una notificación push, no 40. No uses group_by: ['...'], que agrupa por todas las etiquetas y vuelve a convertirlo en una notificación push por alerta. Los planes tienen límites diarios de mensajes (Starter permite 1.000 al día), y cada petición a un webhook que genera un mensaje cuenta contra ese límite.

Botones: Alertmanager y Grafana

La plantilla BUTTONS de arriba añade un botón "Alertmanager". Puedes añadir hasta tres botones de acción. Este abre un panel de Grafana para la primera instancia en firing:

BUTTONS='[{"type":"view","label":"Alertmanager","value":"%externalURL%"},{"type":"view","label":"Grafana","value":"https://grafana.example.com/d/YOUR_DASHBOARD?var-instance=%alerts.#(status=="firing").labels.instance%"}]'

Las comillas sin escapar dentro del marcador parecen incorrectas, pero funcionan: Pocket Alert sustituye primero los marcadores y analiza el JSON después.

Ojo con los valores vacíos. Un botón cuyo value queda vacío se elimina de esa notificación push; los demás botones y el mensaje sí llegan. %alerts.0.generatorURL% (el enlace al gráfico de Prometheus) es un buen destino para las alertas de Prometheus, pero las alertas enviadas con amtool no tienen URL generadora, así que llegan sin ese botón. Los botones de acción son una función de pago.

Alertmanager 0.32+: llamar a la API directamente

Las guías antiguas dicen que Alertmanager no puede cambiar el cuerpo del webhook. Eso cambió en la 0.32.0, que añadió una opción payload a webhook_configs. Junto con http_config.http_headers, que puede enviar una cabecera Token, Alertmanager puede hacer POST directamente a https://api.pocketalert.app/v1/messages con su propio título y nivel.

Hay una trampa. Alertmanager interpreta cada valor renderizado como YAML. En la prueba, un payload campo por campo con message: '{{ range .Alerts }}{{ .Annotations.summary }}...' convirtió el resumen web-1:9100: / has 12% free en el objeto {"web-1:9100": "/ has 12% free"}. La API lo rechaza con 400. Alertmanager no reintenta un 4xx de inmediato; vuelve a enviar el mismo cuerpo roto en cada group_interval, así que la alerta nunca llega.

Construir todo el cuerpo con dict y toJson lo evita:

receivers:
  - name: pocketalert-api
    webhook_configs:
      - url: https://api.pocketalert.app/v1/messages
        http_config:
          http_headers:
            Token:
              files: [/etc/alertmanager/pocketalert.key]
        payload: >-
          {{ $msg := "" }}{{ range .Alerts }}{{ $msg = printf "%s%s: %s\n" $msg .Status .Annotations.summary }}{{ end }}
          {{ $level := "default" }}{{ if eq .Status "resolved" }}{{ $level = "low" }}{{ else if eq .CommonLabels.severity "critical" }}{{ $level = "critical" }}{{ end }}
          {{ dict "title" (printf "[%s] %s" (toUpper .Status) .GroupLabels.alertname) "message" $msg "level" $level | toJson }}

Con un resumen que contenía dos puntos y comillas, envió:

{"level":"critical","message":"firing: web-1:9100: / has 4% free, \"quoted\"\nfiring: web-2:9100 / has 3% free\n","title":"[FIRING] DiskSpaceLow"}

La versión de resolución llegó con "level":"low".

Entonces, ¿cuál usar? La API directa te da un título real y un nivel para cada notificación, todo desde un solo receptor y sin webhooks. El webhook no necesita ninguna clave de API en Alertmanager y funciona en cualquier versión (la variante con URL simple). Una ruta incorrecta se muestra como una línea en blanco en lugar de una petición rechazada, y cada petición aparece en el historial de webhooks. La documentación de Alertmanager califica payload como "úsalo bajo tu propia responsabilidad", así que pruébalo con amtool antes de depender de él.

En el plan gratuito

El plan gratuito tiene un webhook, 50 mensajes al día, sin botones, y critical se entrega como high. Crea un webhook con default_level: 1, pon su URL simple en un único receptor y elimina las rutas por severidad. Las notificaciones de resolución también llegarán como high, a menos que configures send_resolved: false. En Alertmanager 0.32+, la configuración de API directa de arriba encaja mejor con el plan gratuito, porque no necesita webhook y define el nivel de cada notificación.

Si no llega nada

  • Lee el log de Alertmanager. Una entrega fallida registra Notify for alerts failed con el código de estado. Un 404 indica un slug incorrecto o una URL con plantilla en una versión anterior a la 0.31.
  • Abre el historial de webhooks en Pocket Alert. Si la petición está ahí, el problema está en la plantilla. Si no está, Alertmanager nunca la envió.
  • Las líneas en blanco significan que una ruta no coincide con el payload. Los nombres de campo distinguen mayúsculas y minúsculas.
  • Un % justo antes de un marcador necesita duplicarse. Un % seguido de un espacio es texto normal, así que CPU over 90% on %groupLabels.alertname% funciona. Escribe %% cuando el % toca otro texto, como en %commonLabels.usage%%%.
  • Usa el probador de webhooks para capturar lo que Alertmanager envía realmente antes de escribir las plantillas.

Preguntas frecuentes

¿Funciona con kube-prometheus-stack?

Sí. El receptor es una configuración normal de Alertmanager, así que se añade a la configuración de Alertmanager del chart como cualquier otro receptor. Comprueba qué versión de Alertmanager despliega el chart antes de usar la URL con plantilla o payload. Para la parte del clúster, consulta alertas de Kubernetes.

Uso alertas de Grafana, no Alertmanager. ¿Qué cambia?

Grafana envía su propio formato de webhook. Consulta la guía de Grafana.

Crea una cuenta gratuita, ejecuta el script, pega los tres slugs en alertmanager.yml y el próximo InstanceDown llegará a tu teléfono.

Comparte este artículo