Torna al blog

Alertmanager di Prometheus sul telefono: routing per severità, raggruppamento e risoluzioni silenziose

Alertmanager di Prometheus sul telefono: routing per severità, raggruppamento e risoluzioni silenziose

Prometheus è bravo a capire che qualcosa non va. Far arrivare la notizia a una persona è il compito di Alertmanager, e in molte configurazioni la notizia finisce in una cartella email o in un canale Slack che nessuno legge alle 3 di notte.

Alertmanager non ha un'app push sua, ma ha un receiver webhook generico, ed è tutto ciò che serve per ricevere gli alert sul telefono. Questa guida lo configura con routing per severità: gli alert critical arrivano ad alto volume, i warning come notifiche normali e le "risoluzioni" in modo silenzioso. Tutto qui è stato testato con Alertmanager 0.34.2 e Prometheus 3.15.1 in Docker. I payload sono stati catturati e fatti passare nel codice dei template di Pocket Alert.

Cosa ti serve

  • Alertmanager 0.31 o successivo per la configurazione completa. Le versioni precedenti sono trattate più avanti.
  • L'app Pocket Alert sul tuo iPhone o Android e una chiave API da Chiavi API.
  • Un piano a pagamento per la configurazione con tre webhook, perché il piano gratuito include un solo webhook. Una versione con un solo webhook è verso la fine.

Cosa invia Alertmanager

Alertmanager non invia una richiesta per ogni alert. Raccoglie gli alert in gruppi in base alle label indicate in group_by e invia una notifica per gruppo: una POST con un corpo JSON fisso, "version": "4". Quando due host vanno giù con group_by: ['alertname'], parte una sola richiesta. Eccola, leggermente accorciata:

{
  "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
}

Quattro cose di questo payload determinano la configurazione:

  • Una notifica push per gruppo. I singoli alert sono nell'array alerts, quindi il template del messaggio deve funzionare con un array.
  • commonAnnotations è spesso vuoto. Contiene solo le annotazioni identiche in tutti gli alert del gruppo. Un riepilogo che cita l'istanza è diverso per ogni alert, quindi non compare mai lì.
  • status appartiene al gruppo. È resolved solo quando tutti gli alert del gruppo sono risolti. Quando un host si riprende e un altro è ancora giù, lo stato resta firing e l'alert risolto compare al suo interno con il proprio "status": "resolved".
  • Non esiste un campo level al primo livello, ed è lì che un webhook di Pocket Alert cerca la priorità. Quindi la priorità arriva dal livello predefinito del webhook, ed è il motivo per cui questa guida usa un webhook per ogni livello di volume.

Passo 1: crea i webhook di Pocket Alert

Webhookdefault_levelRiceve
Prometheus critical2 (critical)Gruppi firing con severity="critical"
Prometheus warning0 (default)Tutti gli altri gruppi firing
Prometheus resolved-1 (low)Gruppi in cui ogni alert è risolto

I pulsanti si possono impostare solo tramite API, quindi crea tutti e tre con uno 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" ''

Stampa tre URL di ricezione. Conserva lo slug alla fine di ciascuno: incollerai gli slug in alertmanager.yml.

I segnaposto %...% sono percorsi GJSON, e GJSON sa interrogare gli array:

  • alerts.#(status=="firing")#|# conta gli alert del gruppo che sono ancora firing.
  • alerts.#(status=="firing").annotations.summary è il riepilogo del primo alert firing.
  • alerts.#(status=="firing")#.labels.instance elenca le istanze di tutti gli alert firing. Viene mostrato come array JSON, per esempio ["web-1:9100","web-2:9100"], perché non esiste una funzione di unione di stringhe.

Un percorso che non esiste viene mostrato come stringa vuota, quindi un percorso sbagliato produce una riga vuota, non un alert perso. Pocket Alert intitola ogni push di webhook Webhook <name>, quindi il titolo riporta "Webhook Prometheus critical" e il nome dell'alert va sulla prima riga del messaggio. critical richiede un piano a pagamento, che questa configurazione richiede comunque per i tre webhook. Su iPhone suona anche con l'interruttore silenzioso e con Non disturbare, e su Android occupa lo schermo. Usa 1 (high) se non vuoi che gli alert scavalchino Non disturbare.

Passo 2: alertmanager.yml

Sostituisci i tre segnaposto *_SLUG con i tuoi slug:

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']

Come funzionano le parti:

  • Routing per severità. severity="critical" va al receiver ad alto volume, info viene scartato, e tutto il resto, compresi gli alert senza label severity, ricade nel receiver dei warning.
  • L'URL sceglie il webhook. Dalla 0.31.0 l'url del webhook è un template. Un gruppo il cui stato è resolved va al webhook silenzioso, tutto il resto va al webhook del receiver. send_resolved è già true per impostazione predefinita nei webhook; è scritto esplicitamente perché nessuno lo disattivi senza accorgersene.
  • max_alerts: 20 limita quanti alert finiscono in una singola richiesta. Nel test sono andati giù 25 host contemporaneamente. Ne è risultata una sola push con scritto "20 firing", e truncatedAlerts: 5 nel payload.
  • Inibizione. Quando scatta il critical DiskSpaceLow per un filesystem, il warning con lo stesso alertname, instance e mountpoint viene silenziato. amtool alert query --inhibited lo mostra come suppressed.

Verifica configurazione e routing prima di ricaricare:

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

Il secondo comando stampa pocketalert-critical.

Avvia Alertmanager con --web.external-url impostato sull'indirizzo che puoi aprire dal telefono. Senza, externalURL è il solo hostname. In Docker era http://de48ea5ffc29:9093, che rende inutile il pulsante.

Controlla prima la versione

alertmanager --version deve indicare 0.31 o successiva per l'URL templato. La versione 0.30.1 accetta questa configurazione identica e amtool check-config segnala SUCCESS, ma non esegue il rendering del template. Inviava la richiesta a /wh/%7B%7B%20if%20eq%20.Status..., che non corrisponde ad alcun webhook. Sulle versioni precedenti, assegna a ogni receiver l'URL semplice del proprio webhook. Le notifiche di risoluzione arrivano allora al livello di quel webhook.

Passo 3: regole con un'etichetta di severità

Il routing qui sopra funziona solo se le tue regole impostano severity. Ecco due esempi (altre idee su cosa monitorare sono nella pagina monitoraggio dei server), con DiskSpaceLow su due soglie in modo che la regola di inibizione abbia qualcosa da fare:

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 il file. Indica a Prometheus il file e Alertmanager in prometheus.yml:

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

Provalo con amtool

Genera un alert di prova, attendi group_wait (10 secondi sul percorso critical) e risolvilo:

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)"

Mantieni le doppie virgolette interne nell'annotazione, altrimenti amtool avvisa che è passato al vecchio parser. La push di risoluzione arriva al successivo intervallo group_interval, che con questa configurazione può richiedere fino a 5 minuti.

Cosa arriva sul telefono

Questi sono i messaggi che Pocket Alert genera dai payload reali del test, in cui Prometheus ha visto web-1 e web-2 andare giù e tornare su:

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

Quando web-1 torna su, Alertmanager invia un aggiornamento al successivo group_interval. Il gruppo è ancora firing, quindi va al webhook critical:

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

Quando entrambi sono tornati, arriva una push a bassa priorità:

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

Timer: evitare tempeste di push

ImpostazioneCosa faQui
group_waitQuanto attende un nuovo gruppo prima di altri alert e della prima push30s, 10s per critical
group_intervalIntervallo minimo tra le push per un gruppo i cui alert sono cambiati5m
repeat_intervalPromemoria per un gruppo ancora firing e invariato4h, 1h per critical

Un gruppo può inviare al massimo una push per group_interval, quindi un alert intermittente costa fino a 12 push all'ora con 5m. Un'interruzione che dura un giorno costa 24 promemoria con un repeat_interval di 1h. Il raggruppamento fa gran parte del lavoro: un guasto a uno switch che fa cadere 40 host è una push, non 40. Non usare group_by: ['...'], che raggruppa per ogni label e riporta a una push per alert. I piani hanno limiti giornalieri di messaggi (Starter è 1.000 al giorno), e ogni richiesta a un webhook che genera un messaggio viene conteggiata.

Pulsanti: Alertmanager e Grafana

Il template BUTTONS qui sopra aggiunge un pulsante "Alertmanager". Puoi aggiungere fino a tre pulsanti di azione. Questo apre una dashboard Grafana per la prima istanza in 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%"}]'

Le virgolette non escapate dentro il segnaposto sembrano sbagliate, ma funzionano: Pocket Alert sostituisce prima i segnaposto e fa il parsing del JSON dopo.

Attenzione ai valori vuoti. Un pulsante il cui value risulta vuoto viene eliminato da quella push; gli altri pulsanti e il messaggio arrivano comunque. %alerts.0.generatorURL% (il link al grafico di Prometheus) è un buon bersaglio per gli alert di Prometheus, ma gli alert inviati con amtool non hanno un generator URL, quindi arrivano senza quel pulsante. I pulsanti di azione sono una funzione a pagamento.

Alertmanager 0.32+: chiamare direttamente l'API

Le guide più datate dicono che Alertmanager non può modificare il corpo del webhook. Questo è cambiato con la 0.32.0, che ha aggiunto l'opzione payload a webhook_configs. Insieme a http_config.http_headers, che può inviare un header Token, Alertmanager può fare POST direttamente su https://api.pocketalert.app/v1/messages con titolo e livello propri.

C'è una trappola. Alertmanager interpreta ogni valore renderizzato come YAML. Nel test, un payload campo per campo con message: '{{ range .Alerts }}{{ .Annotations.summary }}...' ha trasformato il riepilogo web-1:9100: / has 12% free nell'oggetto {"web-1:9100": "/ has 12% free"}. L'API lo rifiuta con 400. Alertmanager non riprova immediatamente un 4xx; invia di nuovo lo stesso corpo sbagliato a ogni group_interval, quindi l'alert non arriva mai.

Costruire l'intero corpo con dict e toJson evita il problema:

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 riepilogo che contiene due punti e virgolette, ha inviato:

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

La versione di risoluzione è arrivata con "level":"low".

Quale usare, quindi? L'API diretta ti dà un titolo reale e un livello per ogni notifica, il tutto da un unico receiver e senza webhook. Il webhook non richiede alcuna chiave API in Alertmanager e funziona su qualsiasi versione (la variante con URL semplice). Un percorso sbagliato viene mostrato come riga vuota invece di una richiesta rifiutata, e ogni richiesta compare nella cronologia dei webhook. La documentazione di Alertmanager definisce payload "da usare a proprio rischio", quindi testalo con amtool prima di affidartici.

Sul piano gratuito

Il piano gratuito ha un solo webhook, 50 messaggi al giorno, nessun pulsante, e critical viene consegnato come high. Crea un webhook con default_level: 1, metti il suo URL semplice in un unico receiver ed elimina le route per severità. Anche le notifiche di risoluzione arrivano allora come high, a meno che tu non imposti send_resolved: false. Su Alertmanager 0.32+, la configurazione API diretta qui sopra è più adatta al piano gratuito, perché non richiede webhook e imposta il livello per ogni notifica.

Se non arriva nulla

  • Leggi il log di Alertmanager. Una consegna fallita registra Notify for alerts failed con il codice di stato. Un 404 indica uno slug sbagliato, oppure un URL templato su una versione precedente alla 0.31.
  • Apri la cronologia del webhook in Pocket Alert. Se la richiesta c'è, il problema è nel template. Se non c'è, Alertmanager non l'ha mai inviata.
  • Le righe vuote significano che un percorso non corrisponde al payload. I nomi dei campi sono sensibili alle maiuscole.
  • Un % subito prima di un segnaposto va raddoppiato. Un % seguito da uno spazio è testo normale, quindi CPU over 90% on %groupLabels.alertname% funziona. Scrivi %% quando il % tocca altro testo, come in %commonLabels.usage%%%.
  • Usa il tester dei webhook per catturare cosa invia davvero il tuo Alertmanager prima di scrivere i template.

FAQ

Funziona con kube-prometheus-stack?

Sì. Il receiver è una normale configurazione di Alertmanager, quindi va inserito nella configurazione di Alertmanager del chart come qualsiasi altro receiver. Controlla quale versione di Alertmanager distribuisce il chart prima di usare l'URL templato o payload. Per la parte del cluster vedi alert Kubernetes.

Uso Grafana alerting, non Alertmanager. Cosa cambia?

Grafana invia un proprio formato di webhook. Vedi la guida su Grafana.

Crea un account gratuito, esegui lo script, incolla i tre slug in alertmanager.yml e il prossimo InstanceDown arriverà sul tuo telefono.

Condividi questo articolo