Volver a la wiki

Entidad: Alertmanager — enrutador y notificador de alertas por email

Resumen

Alertmanager es el componente que recibe alertas de vmalert, las agrupa (para evitar spam), aplica delays anti-falso-positivo, y envía notificaciones al equipo infra vía email (Resend SMTP).

El destinatario es logcrearack@esfericlabs.com (buzón canónico para alertas de runtime SaaS) y el remitente es CreaRack Pro <noreply@crearack.com> (dominio verificado en Resend). Desde el 28-07-2026 el asunto etiqueta el entorno de origen ([CreaRack PROD] / [CreaRack STAGE] / [CreaRack LOCAL]) — antes iba hardcodeado a PROD.

Despliegue

Imagen

prom/alertmanager:v0.27.0

Configuración en compose

Local (compose.observability.yml)

alertmanager:
  image: prom/alertmanager:v0.27.0
  container_name: crearack_alertmanager
  volumes:
    - ./observability/alertmanager/alertmanager.yml:/etc/alertmanager/alertmanager.yml:ro
    - ./observability/alertmanager/smtp_password:/etc/alertmanager/smtp_password:ro
    - alertmanager_data:/alertmanager
  command:
    - "--config.file=/etc/alertmanager/alertmanager.yml"
    - "--storage.path=/alertmanager"
  ports:
    - "9093:9093"
  restart: unless-stopped
  networks:
    - crearack_internal

PROD/STAGE (compose.prod.yml — ambos Dokploy usan este archivo)

alertmanager:
  image: prom/alertmanager:v0.27.0
  restart: unless-stopped
  volumes:
    - ./observability/alertmanager/alertmanager.yml:/etc/alertmanager/alertmanager.yml:ro
    - ../files/smtp_password:/etc/alertmanager/smtp_password:ro
    - alertmanager_data_prod:/alertmanager
  command:
    - "--config.file=/etc/alertmanager/alertmanager.yml"
    - "--storage.path=/alertmanager"
    - "--web.external-url=${ALERTMANAGER_EXTERNAL_URL:-http://crearack-prod.netbird.cloud:9093}"
  networks:
    - crearack_internal

Nota importante: En PROD, la ruta de smtp_password es ../files/ (sibling del repo clonado en code/), no en el repo mismo. Esto es porque Dokploy no clona archivos gitignored — el secret se proporciona separadamente en cada Dokploy (STAGE y PROD).

Rutas y volúmenes

Configuración

alertmanager.yml

Archivo en observability/alertmanager/alertmanager.yml. Estructura:

global:
  resolve_timeout: 5m
  smtp_smarthost: "smtp.resend.com:587"
  smtp_from: "CreaRack Pro <noreply@crearack.com>"
  smtp_hello: "crearack.com"
  smtp_auth_username: "resend"
  smtp_auth_password_file: "/etc/alertmanager/smtp_password"
  smtp_require_tls: true

route:
  receiver: "logcrearack-email"
  group_by: ["alertname"]
  group_wait: 30s
  group_interval: 5m
  repeat_interval: 4h

receivers:
  - name: "logcrearack-email"
    email_configs:
      - to: "logcrearack@esfericlabs.com"
        send_resolved: true
        headers:
          Subject: '[CreaRack {{ or .CommonLabels.env "prod" | toUpper }}] {{ .Status | toUpper }} · {{ .CommonLabels.alertname }}'

Etiqueta de entorno env (28-07-2026 · PR #348)

El asunto lee la label env que vmalert estampa en cada alerta con --external.label=env=${ALERT_ENV:-prod} (compose.prod.yml):

⚠️ Footgun (s95): un cambio en alertmanager.yml NO se aplica con el deploy — el bind del archivo queda apuntando al inode viejo tras el git pull. Hay que docker compose -p <project> -f compose.prod.yml up -d --force-recreate --no-deps alertmanager (y relanzar netbird-proxies.sh, la IP cambia).

Parámetros clave

ParámetroValorPropósito
resolve_timeout5mSi una alerta no se confirma en 5m, se marca resuelta.
smtp_smarthostsmtp.resend.com:587Servidor Resend con STARTTLS.
smtp_auth_usernameresendUsuario PLAIN para Resend SMTP.
smtp_auth_password_file/etc/alertmanager/smtp_passwordRuta al secret (API key).
smtp_require_tlstrueObliga TLS.
group_by["alertname"]Agrupa por nombre de alerta (evita duplicados si múltiples targets activan la misma).
group_wait30sEspera 30s antes de enviar email (permite agregar más alertas).
group_interval5mRecomputa grupos cada 5m.
repeat_interval4hSi una alerta sigue activa, reenvía cada 4h (evita spam).
send_resolvedtrueEnvía notificación también cuando la alerta se resuelve.

Secret: API key de Resend

Cada entorno usa su PROPIA clave send-only (revocación granular, directiva s69):

Dónde obtener

  1. Login en Resend (https://resend.com).
  2. Crear una API key con permiso Sending access only, una por entorno.
  3. Copiar la clave (formato: re_...).

Almacenamiento

Verificación

Comportamiento

Ciclo de notificación

  1. vmalert envía una alerta: {alertname: "CreaRackDown", severity: "critical", env: "stage", ...}.
  2. Alertmanager recibe en POST /api/v1/alerts.
  3. Agrupa: busca alertas activas del mismo nombre (alertname).
  4. Espera 30s (group_wait): agrupa más si llegan.
  5. Envía email:
    • Asunto: [CreaRack STAGE] FIRING · CreaRackDown (el entorno sale de la label env).
    • Body: plantilla de Alertmanager con detalles.
    • De: CreaRack Pro <noreply@crearack.com>.
    • A: logcrearack@esfericlabs.com.
  6. Si sigue activa 4h después, reenvía.
  7. Cuando se resuelve (firing=false), envía otra notificación: [CreaRack STAGE] RESOLVED · CreaRackDown.

Métricas E2E medidas (simulacros 28-07-2026, STAGE)

Web parada → alerta activa en Alertmanager: ~2m15s (scrape + for: 1m + eval 30s). Email FIRING: +30-60s más. El disparo real de PROD del 29-06-2026 cuadró: firing 11:51 → email entregado 11:57.

UI web

En http://crearack-prod.netbird.cloud:9093 (PROD) · http://crearack-staging.netbird.cloud:9093 (STAGE) — solo VPN NetBird:

Debugging

# Ver logs (los envíos EXITOSOS no se loguean a nivel info; los fallos sí, como warn/error con retry)
docker logs <alertmanager> -f

# Chequear configuración
docker exec <alertmanager> cat /etc/alertmanager/alertmanager.yml

# Alertas activas (amtool viene en la imagen)
docker exec <alertmanager> amtool alert query --alertmanager.url=http://localhost:9093

Errores comunes

535 5.7.8 Authentication credentials invalid

starttls: certificate verify failed

Email no llega

smtp_password: No such file or directory / Is a directory

Integraciones futuras

Véase también

Subir