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

> Invia gli alert di Prometheus Alertmanager su iPhone e Android come notifiche push. Una notifica push per gruppo di alert, alert critici ad alto volume, warning normali, notifiche di risoluzione silenziose. Un alertmanager.yml testato, regole di esempio e quando conviene l'opzione payload di Alertmanager 0.32.

*29.10.2026*

<!-- source: https://pocketalert.app/it/blog/prometheus-alertmanager-notifications -->

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](/get-app) e una chiave API da [Chiavi API](/account/apikeys).
- 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:

```json
{
  "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

<div class="cmp-table-wrap">
<table class="cmp-table">
<thead><tr><th>Webhook</th><th><code>default_level</code></th><th>Riceve</th></tr></thead>
<tbody>
<tr><th>Prometheus critical</th><td><code>2</code> (critical)</td><td>Gruppi firing con <code>severity="critical"</code></td></tr>
<tr><th>Prometheus warning</th><td><code>0</code> (default)</td><td>Tutti gli altri gruppi firing</td></tr>
<tr><th>Prometheus resolved</th><td><code>-1</code> (low)</td><td>Gruppi in cui ogni alert è risolto</td></tr>
</tbody>
</table>
</div>

I pulsanti si possono impostare solo tramite API, quindi crea tutti e tre con uno script:

```bash
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](https://info.pocketalert.app/api/webhooks/settings), 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:

```yaml
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:

```bash
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](/use-cases/server-monitoring)), con `DiskSpaceLow` su due soglie in modo che la regola di inibizione abbia qualcosa da fare:

```yaml
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`:

```yaml
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:

```bash
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:

```text
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:

```text
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à:

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

## Timer: evitare tempeste di push

<div class="cmp-table-wrap">
<table class="cmp-table">
<thead><tr><th>Impostazione</th><th>Cosa fa</th><th>Qui</th></tr></thead>
<tbody>
<tr><th><code>group_wait</code></th><td>Quanto attende un nuovo gruppo prima di altri alert e della prima push</td><td>30s, 10s per critical</td></tr>
<tr><th><code>group_interval</code></th><td>Intervallo minimo tra le push per un gruppo i cui alert sono cambiati</td><td>5m</td></tr>
<tr><th><code>repeat_interval</code></th><td>Promemoria per un gruppo ancora firing e invariato</td><td>4h, 1h per critical</td></tr>
</tbody>
</table>
</div>

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](https://info.pocketalert.app/features/daily-limits) (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](/features/action-buttons). Questo apre una dashboard Grafana per la prima istanza in firing:

```bash
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:

```yaml
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:

```json
{"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](/features/webhook-history). 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](/tools/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](/use-cases/kubernetes-alerts).

### Uso Grafana alerting, non Alertmanager. Cosa cambia?

Grafana invia un proprio formato di webhook. Vedi [la guida su Grafana](/blog/how-to-integrate-grafana-into-pocketalert).

[Crea un account gratuito](/signup), esegui lo script, incolla i tre slug in `alertmanager.yml` e il prossimo `InstanceDown` arriverà sul tuo telefono.
