Cómo configurar Prometheus Alertmanager para enviar alertas a Telegram y Slack con Docker Compose — guía práctica

Deploy & DevOps · Por · Publicado el · 9 min de lectura

Cómo configurar Prometheus Alertmanager con Docker Compose para enviar alertas a Telegram y Slack
Foto: Egor Komarov / Pexels

En este tutorial verás cómo configurar Prometheus Alertmanager para enviar alertas a Telegram y Slack usando Docker Compose paso a paso. Crearás el bot de Telegram, el webhook de Slack, escribirás los archivos de configuración, levantarás el stack con Docker Compose y validarás todo el flujo con alertas de prueba en un laboratorio seguro.

Requisitos previos y arquitectura del flujo

Tendrás un stack mínimo: Prometheus, Alertmanager y destinos de notificación Telegram y Slack. Prometheus evalúa reglas y envía eventos a Alertmanager, que agrupa y enruta según la severidad.

Si aún no tienes Prometheus y Grafana, consulta la guía para levantar el stack básico: Guía práctica: configurar Prometheus y Grafana con Docker Compose en VPS.

  • Docker y Docker Compose instalados. Necesitas permisos para usar Docker.
  • Bot de Telegram con token y el chat_id del canal/grupo o conversación directa.
  • Webhook de Slack (o app/bot con permisos para publicar en un canal).
  • Editor de texto y puertos locales libres 9090 (Prometheus) y 9093 (Alertmanager).

Crear el bot en Telegram y obtener el chat_id

Crea un bot conversando con @BotFather y anota el token. Añade el bot al grupo/canal y envía un mensaje cualquiera para iniciar la conversación. Luego usa la API para descubrir el chat_id y probar el envío.

Nunca compartas tu token. Guárdalo fuera del repositorio 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"

Crear el webhook/app en Slack y probar el envío

En Slack, crea un Incoming Webhook (o una app con permisos chat:write) y copia la URL del webhook. Define el canal que recibirá las alertas.

Valida la entrega con un POST simple. No expongas la URL del webhook públicamente.

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

Escribir el docker-compose del stack de monitorización

Crea un directorio de proyecto que contenga carpetas prometheus/ y alertmanager/. Vamos a mapear los archivos de configuración mediante volúmenes. En laboratorio, los puertos 9090 y 9093 quedan expuestos localmente.

En producción, restringe el acceso con firewall y autenticación en un proxy inverso. Consulta también el Checklist de seguridad para VPS Linux.

Servicio Puerto interno Puerto externo Función
prometheus 9090 9090 Scrape de métricas y evaluación de reglas
alertmanager 9093 9093 Enrutamiento y entrega de notificaciones 
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 y reglas de alerta (alerts.yml)

Prometheus necesita conocer al Alertmanager y cargar un archivo de reglas. La regla InstanceDown detecta objetivos inactivos. El Watchdog siempre dispara y sirve para validar el pipeline de notificaciones.

Mantén el Watchdog solo durante las pruebas, para no generar ruido 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: enrutamiento y mensajes para Telegram y Slack

Define el enrutamiento por severidad: warnings van al Telegram; críticos, al Slack. Ajusta según tu realidad (equipos, horarios, escalas).

Los tokens y webhooks están en el archivo. No hagas commit de este archivo en Git. Guárdalos en un vault de secrets o fuera del repositorio.

# 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 sintaxis con promtool y amtool antes del reload

Valida los archivos para evitar errores en la recarga. Usa promtool para las reglas de Prometheus y amtool para la configuración de Alertmanager.

Ejecuta desde la raíz del proyecto, donde están las carpetas prometheus/ y 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

Levantar los contenedores y validar el pipeline de alertas

Ahora inicia el stack, recarga Prometheus y Alertmanager y genera una alerta de prueba. El Watchdog debería aparecer en Alertmanager y llegar a Telegram en pocos segundos.

Para ejercitar Slack, cambia temporalmente la severidad del Watchdog a critical y recarga las configuraciones.

# 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

Verificación, ajustes finos y solución de problemas

Confirma en Alertmanager si el Watchdog está activo y enrutado. Revisa el historial de entregas en Telegram y Slack. Elimina o silencia el Watchdog después de la prueba.

Problemas comunes y correcciones rápidas:

  • Telegram sin mensajes: inicia conversación con el bot o usa el chat_id correcto del grupo.
  • Slack sin entregas: webhook inválido, app sin permisos o canal privado.
  • Reload sin efecto: error de sintaxis en los YAML. Revisa logs y valida la indentación.
  • Puertos ocupados: ajusta los mapeos 9090/9093 en el compose.
  • Tokens expuestos: mueve configuraciones sensibles a archivos fuera del Git y restringe permisos del directorio.

Enlaces útiles y siguientes pasos

Para recopilar métricas de tu aplicación PHP, integra un exporter específico: Tutorial: exponer métricas PHP‑FPM para Prometheus. Para seguridad general del host, consulta el Checklist de seguridad para VPS Linux. ¿Quieres comparar enfoques de observabilidad? Revisa el Comparativo: Prometheus+Grafana vs Loki+Tempo. Y si deseas notificar incidentes de seguridad en Telegram, mira el tutorial de fail2ban con webhooks y alertas en Telegram.

  • Usa “silences” en Alertmanager para ventanas de mantenimiento.
  • Ajusta group_wait y group_interval para reducir ruido.
  • Estandariza labels severity, service y environment en tus reglas.
  • Separa canales por equipo (ej.: on-call en Slack; NOC en Telegram).

Preguntas frecuentes

¿Puedo usar solo Telegram o solo Slack?

Sí. Mantén un único receiver y elimina el otro del alertmanager.yml. En la ruta, dirige todas las severidades al receiver elegido. Prometheus no cambia: simplemente envia eventos a Alertmanager, que hace el enrutamiento.

¿Cómo proteger tokens y webhooks del Git?

Guarda alertmanager.yml fuera del repositorio o usa un repositorio privado. Restringe permisos del directorio (chmod 600). En entornos más grandes, almacena secretos en cofres dedicados y genera el archivo de configuración en el deploy.

¿Por qué la regla InstanceDown no dispara en el ejemplo?

Porque el único target es el propio Prometheus, que está saludable. Para probar fallos reales, añade targets inexistentes o apaga temporalmente un servicio monitorizado. Usa el Watchdog solo para validar la ruta de entrega.

¿Cómo cambiar el formato de los mensajes?

Ajusta los campos message (Telegram) y title/text (Slack) en alertmanager.yml. Puedes incluir labels y annotations de las Alerts. Mantén mensajes cortos y con contexto: severidad, nombre del alerta, instancia y un resumen objetivo.

¿Se pueden silenciar alertas por horario o entorno?

Puedes usar matchers con labels como environment y service en las rutas de Alertmanager. Para ventanas por horario, crea silences programados vía UI o automatización. En pipelines, aplica labels por entorno en las reglas para separar DEV, STG y PROD.

¿Cómo integrar servicios además de Telegram y Slack?

Alertmanager soporta múltiples destinos (email, webhooks, PagerDuty, entre otros). Añade nuevos receivers en alertmanager.yml y crea rutas específicas por severidad, servicio o equipo. Prueba cada integración de forma aislada antes de activarla en producción.

¿Listo para tomar en serio tus alertas?

Usa esta plantilla como base, estandariza labels y rutas, e integra tus servicios. ¿Necesitas adaptar esto para producción con alta disponibilidad y menos ruido? Hablemos.

Hablar sobre observabilidad

Ver también