Como configurar Prometheus Alertmanager para enviar alertas ao Telegram e Slack com Docker Compose passo a passo — guia prático

Deploy & DevOps · Por Kevin Marcondes · Publicado em 20/10/2026 · 9 min de leitura

Como configurar Prometheus Alertmanager com Docker Compose para enviar alertas ao Telegram e Slack — Foto: Egor Komarov / Pexels

Neste tutorial, você vai ver como configurar Prometheus Alertmanager para enviar alertas ao Telegram e Slack com Docker Compose passo a passo. Você criará o bot do Telegram, o webhook do Slack, escreverá os arquivos de configuração, subirá o stack com Docker Compose e validará todo o fluxo com alertas de teste de forma segura em laboratório.

Pré‑requisitos e arquitetura do fluxo

Você terá um stack mínimo: Prometheus, Alertmanager e destinos de notificação Telegram e Slack. O Prometheus avalia regras e envia eventos ao Alertmanager, que agrupa e roteia por severidade.

Se você ainda não tem Prometheus e Grafana, veja o guia para subir o stack básico: Guia prático: configurar Prometheus e Grafana com Docker Compose em VPS.

Docker e Docker Compose instalados. Você precisa de permissão para usar Docker.
Bot do Telegram com token e o chat_id do canal/grupo ou conversa direta.
Webhook do Slack (ou app/bot com permissões para postar em um canal).
Editor de texto e portas locais livres 9090 (Prometheus) e 9093 (Alertmanager).

Criar o bot no Telegram e obter o chat_id

Crie um bot conversando com @BotFather e anote o token. Adicione o bot ao grupo/canal e envie uma mensagem qualquer para iniciar a conversa. Em seguida, use a API para descobrir o chat_id e testar o envio.

Nunca compartilhe seu token. Guarde fora do repositório Git.

# 1) Verifique o bot
curl -s "https://api.telegram.org/bot<TELEGRAM_BOT_TOKEN>/getMe" | jq .

# 2) Descubra o chat_id: envie uma mensagem ao bot e depois rode
curl -s "https://api.telegram.org/bot<TELEGRAM_BOT_TOKEN>/getUpdates" | jq .
# Procure por result[].message.chat.id

# 3) Teste o envio manual
curl -s -X POST \
  "https://api.telegram.org/bot<TELEGRAM_BOT_TOKEN>/sendMessage" \
  -d chat_id=<CHAT_ID> \
  -d text="Teste de alerta via Telegram"

Criar o webhook/app no Slack e testar envio

No Slack, crie um Incoming Webhook (ou um app com permissões chat:write) e copie a URL do webhook. Defina o canal que receberá os alertas.

Valide a entrega com um POST simples. Não exponha a URL do webhook publicamente.

# Substitua pela sua URL de webhook
SLACK_WEBHOOK="https://hooks.slack.com/services/XXX/YYY/ZZZ"

# Teste básico de mensagem
curl -X POST -H 'Content-type: application/json' \
  --data '{"text":"Teste de alerta via Slack (webhook)"}' \
  "$SLACK_WEBHOOK"

Escrever o docker-compose do stack de monitoramento

Crie um diretório de projeto contendo pastas prometheus/ e alertmanager/. Vamos mapear os arquivos de configuração via volumes. Em laboratório, as portas 9090 e 9093 ficam expostas localmente.

Em produção, restrinja o acesso com firewall e autenticação em um proxy reverso. Consulte também o Checklist de segurança para VPS Linux.

Serviço	Porta interna	Porta externa	Função
prometheus	9090	9090	Scrape de métricas e avaliação de regras
alertmanager	9093	9093	Roteamento e entrega de notificações

version: "3.8"
services:
  prometheus:
    image: prom/prometheus:v2.52.0
    command:
      - --config.file=/etc/prometheus/prometheus.yml
      - --web.enable-lifecycle
    volumes:
      - ./prometheus/prometheus.yml:/etc/prometheus/prometheus.yml:ro
      - ./prometheus/alerts.yml:/etc/prometheus/alerts.yml:ro
    ports:
      - "9090:9090"
    networks: [monitoring]

  alertmanager:
    image: prom/alertmanager:v0.27.0
    command:
      - --config.file=/etc/alertmanager/alertmanager.yml
      - --web.route-prefix=/
      - --web.listen-address=:9093
    volumes:
      - ./alertmanager/alertmanager.yml:/etc/alertmanager/alertmanager.yml:ro
      - alertmanager-data:/alertmanager
    ports:
      - "9093:9093"
    networks: [monitoring]

networks:
  monitoring: {}

volumes:
  alertmanager-data: {}

Prometheus: scrape e regras de alerta (alerts.yml)

O Prometheus precisa conhecer o Alertmanager e carregar um arquivo de regras. A regra InstanceDown detecta alvos inativos. A Watchdog sempre dispara e serve para validar o pipeline de notificação.

Deixe a Watchdog apenas durante os testes, para não gerar ruído constante.

# arquivo: prometheus/prometheus.yml
global:
  scrape_interval: 15s
  evaluation_interval: 15s

alerting:
  alertmanagers:
    - static_configs:
        - targets: ["alertmanager:9093"]

rule_files:
  - /etc/prometheus/alerts.yml

scrape_configs:
  - job_name: prometheus
    static_configs:
      - targets: ["prometheus:9090"]

---
# arquivo: prometheus/alerts.yml
groups:
  - name: basic
    rules:
      - alert: InstanceDown
        expr: up == 0
        for: 1m
        labels:
          severity: critical
        annotations:
          summary: "Alvo indisponível"
          description: "O alvo {{ $labels.instance }} está inativo por mais de 1 minuto."

      - alert: Watchdog
        expr: vector(1)
        labels:
          severity: warning
        annotations:
          summary: "Watchdog: canal de alertas ativo"
          description: "Alerta contínuo para verificar o pipeline. Desabilite em produção."

Alertmanager: roteamento e mensagens para Telegram e Slack

Defina o roteamento por severidade: warnings vão ao Telegram; críticos, ao Slack. Ajuste conforme sua realidade (times, horários, escalas).

Os tokens e webhooks estão no arquivo. Não faça commit desse arquivo no Git. Guarde em cofre de secrets ou fora do repositório.

# arquivo: alertmanager/alertmanager.yml
global: {}

route:
  receiver: default
  group_by: ["alertname", "severity"]
  group_wait: 10s
  group_interval: 2m
  repeat_interval: 4h
  routes:
    - matchers:
        - severity = "critical"
      receiver: slack
    - matchers:
        - severity = "warning"
      receiver: telegram

receivers:
  - name: default
    slack_configs:
      - api_url: "https://hooks.slack.com/services/REPLACE_WITH_YOUR_WEBHOOK"
        channel: "#alerts"
        send_resolved: true
        title: "[{{ .Status | toUpper }}] {{ .CommonLabels.alertname }}"
        text: >-
          {{ range .Alerts -}}
          • {{ .Annotations.summary }} ({{ .Labels.instance }})
          {{ end }}

  - name: telegram
    telegram_configs:
      - bot_token: "REPLACE_WITH_YOUR_TELEGRAM_BOT_TOKEN"
        chat_id: REPLACE_WITH_YOUR_CHAT_ID
        parse_mode: "Markdown"
        disable_web_page_preview: true
        send_resolved: true
        message: >-
          [{{ .Status | toUpper }}] {{ .CommonLabels.alertname }}\n
          {{ range .Alerts -}}
          • {{ .Annotations.summary }} ({{ .Labels.instance }})
          {{ end }}

  - name: slack
    slack_configs:
      - api_url: "https://hooks.slack.com/services/REPLACE_WITH_YOUR_WEBHOOK"
        channel: "#alerts"
        send_resolved: true
        title: "[{{ .Status | toUpper }}] {{ .CommonLabels.alertname }}"
        text: >-
          {{ range .Alerts -}}
          • {{ .Annotations.summary }} ({{ .Labels.instance }})
          {{ end }}

Validar sintaxe com promtool e amtool antes do reload

Valide arquivos para evitar erros de recarga. Use promtool para as regras do Prometheus e amtool para a configuração do Alertmanager.

Execute a partir da raiz do projeto, onde estão as pastas prometheus/ e alertmanager/.

# Checar regras do Prometheus
docker run --rm -v "$PWD/prometheus":/etc/prometheus \
  prom/prometheus:v2.52.0 promtool check rules /etc/prometheus/alerts.yml

# Checar config do Alertmanager
docker run --rm -v "$PWD/alertmanager":/etc/alertmanager \
  prom/alertmanager:v0.27.0 amtool check-config /etc/alertmanager/alertmanager.yml

Subir os containers e validar o pipeline de alertas

Agora inicialize o stack, recarregue o Prometheus e o Alertmanager e gere um alerta de teste. A Watchdog deve aparecer no Alertmanager e chegar ao Telegram em poucos segundos.

Para exercitar o Slack, troque temporariamente a severidade da Watchdog para critical e recarregue as configs.

# Subir o stack
docker compose up -d

# Verifique os serviços
docker compose ps

# Recarregar Prometheus (habilitado por --web.enable-lifecycle)
curl -X POST http://localhost:9090/-/reload

# Recarregar Alertmanager via SIGHUP
docker compose kill -s HUP alertmanager

# Acesse as UIs:
# Prometheus:   http://localhost:9090
# Alertmanager: http://localhost:9093

Verificação, ajustes finos e solução de problemas

Confirme no Alertmanager se a Watchdog está ativa e roteada. Veja o histórico de entregas no Telegram e Slack. Remova ou silencie a Watchdog após o teste.

Problemas comuns e correções rápidas:

- Telegram sem mensagens: inicie conversa com o bot ou use chat_id do grupo correto.

- Slack sem entregas: webhook inválido, app sem permissão ou canal privado.

- Reload sem efeito: erro de sintaxe nos YAML. Cheque logs e valide a indentação.

- Portas ocupadas: ajuste mapeamentos 9090/9093 no compose.

- Tokens expostos: mova configs sensíveis para arquivos fora do Git e restrinja permissões do diretório.

Para coletar métricas da sua aplicação PHP, integre um exporter específico: Tutorial: expor métricas PHP‑FPM para Prometheus. Para segurança geral do host, consulte o Checklist de segurança para VPS Linux. Quer comparar abordagens de observabilidade? Veja o Comparativo: Prometheus+Grafana vs Loki+Tempo. E, se quiser notificar incidentes de segurança no Telegram, veja o tutorial do fail2ban com webhooks.

Use “silences” no Alertmanager para janelas de manutenção.
Ajuste group_wait e group_interval para reduzir ruído.
Padronize labels severity, service e environment nas suas regras.
Separe canais por equipe (ex.: on-call no Slack; NOC no Telegram).

Perguntas frequentes

Posso usar apenas Telegram ou apenas Slack?

Sim. Basta manter um receiver e remover o outro do alertmanager.yml. No route, direcione todas as severidades para o receiver escolhido. O Prometheus não muda: ele só envia eventos ao Alertmanager, que faz o roteamento.

Como proteger tokens e webhooks do Git?

Guarde alertmanager.yml fora do repositório ou use um repositório privado. Restrinja permissões do diretório (chmod 600). Em ambientes maiores, armazene segredos em cofres dedicados e gere o arquivo de configuração no deploy.

Por que a regra InstanceDown não dispara no exemplo?

Porque o único alvo é o próprio Prometheus, que está saudável. Para testar falhas reais, adicione targets inexistentes ou desligue temporariamente um serviço monitorado. Use a Watchdog apenas para validar o caminho de entrega.

Como alterar o formato das mensagens?

Ajuste os campos message (Telegram) e title/text (Slack) no alertmanager.yml. Você pode incluir labels e annotations das Alerts. Mantenha mensagens curtas e com contexto: severidade, nome do alerta, instância e um resumo objetivo.

Dá para silenciar alertas por horário ou ambiente?

Você pode usar matchers com labels como environment e service no route do Alertmanager. Para janelas por horário, crie silences programados via UI ou automação. Em pipelines, aplique labels por ambiente nas regras para separar DEV, STG e PROD.

Como integrar serviços além de Telegram e Slack?

O Alertmanager suporta diversos destinos (e‑mail, webhooks, PagerDuty, entre outros). Adicione novos receivers no alertmanager.yml e crie rotas específicas por severidade, serviço ou equipe. Teste cada integração isoladamente antes de ativar em produção.

Pronto para levar seus alertas a sério?

Use este template como base, padronize labels e rotas, e integre seus serviços. Precisa adaptar para produção com alta disponibilidade e menos ruído? Vamos conversar.

Falar sobre observabilidade