Voltar para o blog

Alertas do Prometheus Alertmanager no celular: roteamento por severidade, agrupamento e resoluções silenciosas

Alertas do Prometheus Alertmanager no celular: roteamento por severidade, agrupamento e resoluções silenciosas

O Prometheus é bom em perceber que algo está errado. Levar essa informação até uma pessoa é trabalho do Alertmanager, e em muitas configurações o aviso acaba numa pasta de e-mail ou num canal do Slack que ninguém lê às 3 da manhã.

O Alertmanager não tem um aplicativo push próprio, mas tem um receptor de webhook genérico, e isso é tudo o que você precisa para receber alertas no celular. Este guia configura o roteamento por severidade: alertas critical chegam em alto volume, avisos chegam como notificações normais, e "resolvido" chega em silêncio. Tudo aqui foi testado com Alertmanager 0.34.2 e Prometheus 3.15.1 no Docker. Os payloads foram capturados e processados pelo próprio código de templates do Pocket Alert.

O que você precisa

  • Alertmanager 0.31 ou mais recente para a configuração completa. Versões anteriores estão cobertas mais abaixo.
  • O aplicativo Pocket Alert no seu iPhone ou Android e uma chave de API em Chaves de API.
  • Um plano pago para a configuração com três webhooks, já que o plano gratuito inclui um webhook. Uma versão com um único webhook aparece perto do final.

O que o Alertmanager envia

O Alertmanager não envia uma requisição por alerta. Ele reúne os alertas em grupos pelos rótulos definidos em group_by e envia uma notificação por grupo: um POST com um corpo JSON fixo, "version": "4". Quando dois hosts caem com group_by: ['alertname'], sai uma única requisição. Veja, um pouco resumida:

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

Quatro pontos desse formato de payload moldam a configuração:

  • Uma notificação push por grupo. Os alertas individuais estão no array alerts, então o template da mensagem precisa funcionar com um array.
  • commonAnnotations costuma estar vazio. Ele guarda apenas as anotações idênticas em todos os alertas do grupo. Um resumo que menciona a instância é diferente em cada alerta, então nunca aparece ali.
  • status pertence ao grupo. Ele só é resolved quando todos os alertas do grupo estão resolvidos. Quando um host se recupera e outro continua caído, o status continua firing e o alerta recuperado aparece dentro da lista com seu próprio "status": "resolved".
  • Não existe um campo level no nível superior, e é nele que um webhook do Pocket Alert procura a prioridade. Por isso a prioridade vem do nível padrão do webhook, e este guia usa um webhook por volume.

Passo 1: Crie os webhooks do Pocket Alert

Webhookdefault_levelRecebe
Prometheus critical2 (critical)Grupos disparando com severity="critical"
Prometheus warning0 (default)Todos os outros grupos disparando
Prometheus resolved-1 (low)Grupos em que todos os alertas foram resolvidos

Os botões só podem ser definidos pela API, então crie os três com um ú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" ''

Ele imprime três URLs de recebimento. Guarde o slug no fim de cada uma; você vai colar os slugs no alertmanager.yml.

Os placeholders %...% são caminhos GJSON, e o GJSON consegue consultar arrays:

  • alerts.#(status=="firing")#|# conta os alertas do grupo que ainda estão disparando.
  • alerts.#(status=="firing").annotations.summary é o resumo do primeiro alerta disparando.
  • alerts.#(status=="firing")#.labels.instance lista as instâncias de todos os alertas disparando. Ele aparece como um array JSON, como ["web-1:9100","web-2:9100"], porque não existe uma função de junção de strings.

Um caminho que não existe aparece como string vazia, então um caminho errado gera uma linha em branco, não um alerta perdido. O Pocket Alert dá a todo push de webhook o título Webhook <name>, então o título fica "Webhook Prometheus critical" e o nome do alerta vai na primeira linha da mensagem. critical exige um plano pago, que esta configuração já exige para os três webhooks. Ele toca mesmo com a chave de silencioso e com o Não perturbe no iPhone, e toma a tela no Android. Use 1 (high) se não quiser que os alertas passem por cima do Não perturbe.

Passo 2: alertmanager.yml

Substitua os três placeholders *_SLUG pelos seus 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']

Como as peças funcionam:

  • Roteamento por severidade. severity="critical" vai para o receptor de alto volume, info é descartado, e todo o resto, incluindo alertas sem rótulo severity, cai no receptor de aviso.
  • A URL escolhe o webhook. Desde a 0.31.0, a url do webhook é um template. Um grupo cujo status é resolved vai para o webhook silencioso, e todo o resto vai para o próprio webhook do receptor. send_resolved já é true por padrão em webhooks; ele aparece escrito para que ninguém o desligue sem perceber.
  • max_alerts: 20 limita quantos alertas entram em uma requisição. No teste, 25 hosts caíram ao mesmo tempo. Isso gerou uma notificação push com "20 firing", e truncatedAlerts: 5 no payload.
  • Inibição. Quando o alerta crítico DiskSpaceLow dispara para um sistema de arquivos, o aviso do mesmo alertname, instance e mountpoint é silenciado. amtool alert query --inhibited o mostra como suppressed.

Verifique a configuração e o roteamento antes de recarregar:

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

O segundo comando imprime pocketalert-critical.

Inicie o Alertmanager com --web.external-url definido com o endereço que você consegue abrir pelo celular. Sem isso, externalURL fica só com o hostname. No Docker, isso resultou em http://de48ea5ffc29:9093, o que gera um botão inútil.

Verifique a versão primeiro

alertmanager --version precisa indicar 0.31 ou mais recente para a URL com template. A versão 0.30.1 aceita exatamente esta configuração, e o amtool check-config informa SUCCESS, mas não renderiza o template. Ela enviou a requisição para /wh/%7B%7B%20if%20eq%20.Status..., que não corresponde a nenhum webhook. Em versões antigas, dê a cada receptor a URL simples do próprio webhook. As notificações de resolvido então chegam com o nível daquele webhook.

Passo 3: Regras com um rótulo de severidade

O roteamento acima só funciona se suas regras definirem severity. Aqui estão dois exemplos (mais ideias do que monitorar estão na página de monitoramento de servidores), com DiskSpaceLow em dois limites para que a regra de inibição tenha o que fazer:

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 o arquivo. Aponte o Prometheus para o arquivo e para o Alertmanager no prometheus.yml:

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

Teste com o amtool

Dispare um alerta de teste, espere o group_wait (10 segundos na rota crítica) e resolva-o:

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

Mantenha as aspas duplas internas na anotação, ou o amtool avisa que voltou ao analisador antigo. A notificação push de resolvido chega no próximo ciclo de group_interval, que pode levar até 5 minutos com esta configuração.

O que chega no seu celular

Estas são as mensagens que o Pocket Alert renderiza a partir dos payloads reais do teste, em que o Prometheus viu web-1 e web-2 caírem e voltarem:

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

Quando web-1 se recupera, o Alertmanager envia uma atualização no próximo group_interval. O grupo ainda está disparando, então vai para o webhook crítico:

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

Quando os dois voltam, chega uma notificação push de baixa prioridade:

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

Temporizadores: evitando rajadas de notificações

ConfiguraçãoO que fazAqui
group_waitQuanto tempo um grupo novo espera por mais alertas antes da primeira notificação30s, 10s para critical
group_intervalIntervalo mínimo entre notificações de um grupo cujos alertas mudaram5m
repeat_intervalLembrete para um grupo que continua disparando sem mudanças4h, 1h para critical

Um grupo pode enviar no máximo uma notificação por group_interval, então um alerta que oscila custa até 12 notificações por hora com 5m. Uma queda que dura um dia gera 24 lembretes com repeat_interval de 1h. O agrupamento faz a maior parte do trabalho: uma falha de switch que derruba 40 hosts gera uma notificação, não 40. Não use group_by: ['...'], que agrupa por todos os rótulos e transforma tudo de volta em uma notificação por alerta. Os planos têm limites diários de mensagens (o Starter é de 1.000 por dia), e cada requisição para um webhook que gera uma mensagem conta contra esse limite.

Botões: Alertmanager e Grafana

O template BUTTONS acima adiciona um botão "Alertmanager". Você pode adicionar até três botões de ação. Este abre um painel do Grafana para a primeira instância disparando:

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%"}]'

As aspas sem escape dentro do placeholder parecem erradas, mas funcionam: o Pocket Alert substitui os placeholders primeiro e interpreta o JSON depois.

Cuidado com valores vazios. Um botão cujo value sai vazio é removido daquela notificação; os outros botões e a mensagem continuam chegando. %alerts.0.generatorURL% (o link do gráfico do Prometheus) é um bom destino para alertas do Prometheus, mas alertas enviados com o amtool não têm generator URL, então chegam sem esse botão. Botões de ação são um recurso pago.

Alertmanager 0.32+: chamando a API diretamente

Guias antigos dizem que o Alertmanager não consegue alterar o corpo do webhook. Isso mudou na 0.32.0, que adicionou a opção payload em webhook_configs. Junto com http_config.http_headers, que pode enviar um cabeçalho Token, o Alertmanager consegue fazer POST diretamente em https://api.pocketalert.app/v1/messages com o próprio título e nível.

Há uma armadilha. O Alertmanager interpreta cada valor renderizado como YAML. No teste, um payload campo a campo com message: '{{ range .Alerts }}{{ .Annotations.summary }}...' transformou o resumo web-1:9100: / has 12% free no objeto {"web-1:9100": "/ has 12% free"}. A API rejeita isso com 400. O Alertmanager não tenta novamente imediatamente uma resposta 4xx; ele reenvia o mesmo corpo quebrado a cada group_interval, então o alerta nunca chega.

Montar o corpo inteiro com dict e toJson evita o 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 }}

Com um resumo contendo dois-pontos e aspas, ele enviou:

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

A versão de resolvido chegou com "level":"low".

Então, qual usar? A API direta oferece um título real e um nível para cada notificação, tudo a partir de um só receptor e sem webhooks. O webhook não exige chave de API no Alertmanager e funciona em qualquer versão (a variante com URL simples). Um caminho errado gera uma linha em branco em vez de uma requisição rejeitada, e toda requisição aparece no histórico de webhooks. A própria documentação do Alertmanager classifica payload como "use por sua conta e risco", então teste com o amtool antes de depender dele.

No plano gratuito

O plano gratuito tem um webhook, 50 mensagens por dia, sem botões, e critical é entregue como high. Crie um webhook com default_level: 1, coloque a URL simples dele em um único receptor e remova as rotas de severidade. As notificações de resolvido também chegam como high, a menos que você defina send_resolved: false. No Alertmanager 0.32+, a configuração da API direta acima se encaixa melhor no plano gratuito, porque não precisa de webhook e define o nível de cada notificação.

Se nada chegar

  • Leia o log do Alertmanager. Uma entrega com falha registra Notify for alerts failed com o código de status. Um 404 significa slug errado ou uma URL com template em uma versão anterior à 0.31.
  • Abra o histórico de webhooks no Pocket Alert. Se a requisição estiver lá, o problema está no template. Se não estiver, o Alertmanager nunca a enviou.
  • Linhas em branco significam que um caminho não corresponde ao payload. Os nomes dos campos diferenciam maiúsculas de minúsculas.
  • Um % logo antes de um placeholder precisa ser duplicado. Um % seguido de espaço é texto comum, então CPU over 90% on %groupLabels.alertname% funciona. Escreva %% quando o % encostar em outro texto, como em %commonLabels.usage%%%.
  • Use o testador de webhook para capturar o que o seu Alertmanager realmente envia antes de escrever os templates.

FAQ

Isso funciona com o kube-prometheus-stack?

Sim. O receptor é uma configuração comum do Alertmanager, então ela entra na configuração do Alertmanager do chart como qualquer outro receptor. Verifique qual versão do Alertmanager o chart implanta antes de usar a URL com template ou payload. Veja alertas do Kubernetes para o lado do cluster.

Eu uso alertas do Grafana, não do Alertmanager. O que muda?

O Grafana envia o próprio formato de webhook. Veja o guia do Grafana.

Crie uma conta gratuita, execute o script, cole três slugs no alertmanager.yml, e o próximo InstanceDown vai chegar ao seu celular.

Compartilhe este artigo