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. commonAnnotationssuele 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í.statuspertenece al grupo. Esresolvedsolo cuando todas las alertas del grupo están resueltas. Cuando un host se recupera y otro sigue caído, el estado sigue siendofiringy la alerta recuperada aparece dentro con su propio"status": "resolved".- No hay un campo
levelde 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
| Webhook | default_level | Recibe |
|---|---|---|
| Prometheus critical | 2 (critical) | Grupos en firing con severity="critical" |
| Prometheus warning | 0 (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.summaryes el resumen de la primera alerta en firing.alerts.#(status=="firing")#.labels.instancelista 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,infose descarta y todo lo demás, incluidas las alertas sin una etiquetaseverity, cae en el receptor de advertencias. - La URL elige el webhook. Desde la 0.31.0, la
urldel webhook es una plantilla. Un grupo cuyo estado esresolvedva al webhook silencioso, y todo lo demás va al webhook propio del receptor.send_resolvedya estruepor defecto en los webhooks; se escribe explícitamente para que nadie lo desactive sin darse cuenta. max_alerts: 20limita 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", ytruncatedAlerts: 5en el payload.- Inhibición. Cuando la alerta crítica
DiskSpaceLowse activa para un sistema de archivos, se silencia la advertencia con el mismoalertname,instanceymountpoint.amtool alert query --inhibitedla muestra comosuppressed.
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
| Ajuste | Qué hace | Aquí |
|---|---|---|
group_wait | Cuánto espera un grupo nuevo a más alertas antes de la primera notificación push | 30s, 10s para critical |
group_interval | Intervalo mínimo entre notificaciones push para un grupo cuyas alertas han cambiado | 5m |
repeat_interval | Recordatorio para un grupo que sigue en firing y sin cambios | 4h, 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 failedcon el código de estado. Un404indica 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í queCPU 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.