Alertmanager no Node.js

O Alertmanager no Node.js recebe alertas do Prometheus, agrupa eventos relacionados, elimina duplicidades e encaminha notificações para os canais corretos. Ele também oferece silences, inhibition e roteamento por labels, evitando que uma única falha gere centenas de páginas para a equipe.

Alertmanager não define quando uma aplicação está com problema. As condições ficam nas alerting rules do Prometheus. O Alertmanager decide como, quando e para quem notificar. Uma estratégia confiável precisa combinar métricas úteis, regras testadas, labels estáveis, canais redundantes e procedimentos de resposta.

Neste guia, você aprenderá a criar alertas para uma API Node.js, configurar rotas, agrupamento, silences, inhibition, templates, webhooks, alta disponibilidade e práticas para reduzir ruído.

Como o Alertmanager funciona?

A documentação oficial do Prometheus Alertmanager descreve quatro funções centrais:

• Grouping: reúne alertas semelhantes em uma notificação.
• Deduplication: evita repetir a mesma notificação.
• Routing: escolhe receiver conforme labels.
• Silences e inhibition: suprimem alertas de forma controlada.

Fluxo completo

1. A aplicação Node.js expõe métricas.
2. Prometheus coleta séries temporais.
3. Uma alerting rule entra em estado firing.
4. Prometheus envia o alerta ao Alertmanager.
5. Alertmanager agrupa, roteia e notifica.
6. A equipe investiga por dashboards, logs e traces.

Consulte Prometheus no Node.js.

Métrica de erros HTTP

import client from 'prom-client';

const httpRequests = new client.Counter({
  name: 'http_requests_total',
  help: 'Total de requisições HTTP',
  labelNames: ['service', 'method', 'route', 'status_code']
});

Use rotas normalizadas, como /orders/:id, e não URLs completas. IDs em labels causam cardinalidade alta.

Regra de taxa de erro

groups:
  - name: orders-api
    rules:
      - alert: OrdersApiHighErrorRate
        expr: |
          sum(rate(http_requests_total{
            service="orders-api",
            status_code=~"5.."
          }[5m]))
          /
          sum(rate(http_requests_total{
            service="orders-api"
          }[5m]))
          > 0.05
        for: 10m
        labels:
          severity: page
          team: backend
          service: orders-api
          environment: production
        annotations:
          summary: "Taxa de erro alta na orders-api"
          description: "Mais de 5% das requisições retornam 5xx por 10 minutos."
          runbook_url: "https://runbooks.example.com/orders-api/high-error-rate"

O campo for evita notificar picos muito curtos. O valor precisa refletir o SLO e o tempo aceitável de resposta.

Regra de disponibilidade

- alert: OrdersApiUnavailable
  expr: up{job="orders-api"} == 0
  for: 2m
  labels:
    severity: page
    team: backend
    service: orders-api
    environment: production
  annotations:
    summary: "Orders API indisponível"

up == 0 significa que o Prometheus não conseguiu coletar o alvo. Isso pode indicar aplicação caída, rede, Service, autenticação ou configuração de scrape.

Teste de regras

promtool check rules alerts.yml
promtool test rules alerts_test.yml

A documentação de testes de regras do Prometheus permite fornecer séries e validar alertas esperados. Inclua testes no CI.

Configuração básica

global:
  resolve_timeout: 5m

route:
  receiver: default
  group_by: ['alertname', 'cluster', 'service']
  group_wait: 30s
  group_interval: 5m
  repeat_interval: 4h

receivers:
  - name: default
    webhook_configs:
      - url: https://alerts.example.com/hooks/default
        send_resolved: true

Group wait

group_wait é o tempo antes da primeira notificação do grupo. Uma pequena espera permite reunir alertas que surgem juntos. Para incidentes críticos, não use um valor tão alto que atrase a resposta.

Group interval

group_interval define quanto esperar antes de enviar mudanças em um grupo já notificado. Isso evita uma mensagem para cada nova instância afetada.

Repeat interval

repeat_interval controla lembretes enquanto o alerta continua ativo. Um intervalo curto gera fadiga; um intervalo longo pode deixar incidentes esquecidos.

Árvore de rotas

route:
  receiver: operations-email
  group_by: ['alertname', 'environment', 'service']
  routes:
    - matchers:
        - severity="page"
        - environment="production"
      receiver: pager
      repeat_interval: 1h

    - matchers:
        - team="backend"
        - severity="ticket"
      receiver: backend-tickets

    - matchers:
        - environment=~"development|staging"
      receiver: non-production

Rotas são avaliadas hierarquicamente. Teste matchers e use continue somente quando um alerta deve chegar a múltiplos receivers.

Labels de roteamento

Mantenha um conjunto consistente:

• alertname;
• severity;
• team;
• service;
• environment;
• cluster;
• region.

Evite usar labels mutáveis ou específicas de Pod no group_by, pois elas fragmentam notificações.

Severidade

Uma classificação prática:

• page: exige ação humana imediata.
• ticket: precisa de correção, mas não acorda alguém.
• info: contexto ou automação.

Se todo alerta é crítico, nenhum é crítico.

Webhook receiver

receivers:
  - name: incident-api
    webhook_configs:
      - url: https://incident.example.com/v1/alertmanager
        send_resolved: true
        max_alerts: 100

O endpoint Node.js deve autenticar o Alertmanager, limitar payload, validar JSON e ser idempotente.

Endpoint Node.js

app.post('/v1/alertmanager', async (req, res) => {
  const signature = req.get('x-alert-signature');
  await verifySignature(signature, req.rawBody);

  const payload = alertmanagerSchema.parse(req.body);

  await processAlertGroup({
    groupKey: payload.groupKey,
    status: payload.status,
    alerts: payload.alerts
  });

  res.status(202).end();
});

Não execute lógica lenta antes de responder. Grave em fila ou banco e processe de forma assíncrona. Veja Idempotência em APIs Node.js.

Segurança do webhook

• Use HTTPS.
• Restrinja origem por rede quando possível.
• Configure autenticação HTTP ou mTLS.
• Valide tamanho e Content-Type.
• Não renderize annotations como HTML sem sanitização.
• Não registre secrets ou payloads completos.

Consulte mTLS no Node.js.

Silences

Silence desativa notificações que combinam com matchers durante um período. Use em manutenção programada:

alertname="OrdersApiUnavailable"
environment="production"
service="orders-api"

Inclua criador, motivo, ticket e expiração. Silences sem prazo escondem incidentes futuros.

Inhibition

Se o cluster inteiro está indisponível, alertas de cada Pod não acrescentam informação:

inhibit_rules:
  - source_matchers:
      - alertname="ClusterUnavailable"
      - severity="page"
    target_matchers:
      - severity=~"page|ticket"
    equal:
      - cluster
      - environment

A inhibition só deve suprimir alertas causados pelo incidente fonte. Matchers amplos podem esconder problemas independentes.

Templates

{{ define "alert.title" }}
[{{ .Status | toUpper }}] {{ .CommonLabels.alertname }}
{{ end }}

{{ define "alert.body" }}
Serviço: {{ .CommonLabels.service }}
Ambiente: {{ .CommonLabels.environment }}
Alertas: {{ len .Alerts }}
{{ range .Alerts }}
- {{ .Annotations.summary }}
{{ end }}
{{ end }}

Templates devem ser curtos e incluir links para dashboard, logs, trace e runbook.

Runbooks

Um alerta acionável responde:

• qual impacto é esperado;
• como confirmar o problema;
• quais dashboards abrir;
• como mitigar;
• como escalar;
• quando encerrar o incidente.

Alertas baseados em SLO

Prefira alertar sobre impacto ao usuário e consumo de error budget, não sobre cada variação de CPU. CPU alta pode ser saudável quando a latência e os erros permanecem dentro do objetivo.

Multi-window burn rate

Alertas de burn rate combinam janelas rápidas e lentas para detectar incidentes intensos sem reagir a ruído. A regra deve ser derivada do SLO e testada com dados históricos.

Alertas de fila

Para workers Node.js, monitore idade da mensagem mais antiga, profundidade, taxa de erro e ausência de consumo. Uma fila grande pode ser normal em horários de pico; idade costuma representar impacto melhor.

Alertas de event loop

Event loop lag alto pode indicar CPU síncrona, GC ou overload. Combine com throughput, CPU e latência antes de paginar.

Alta disponibilidade

Alertmanager suporta cluster. A documentação recomenda que o Prometheus envie para todos os Alertmanagers, em vez de colocar um load balancer simples entre eles. Configure peers, storage e rede conforme o ambiente.

Kubernetes

Em Kubernetes, use réplicas, PodDisruptionBudget, anti-affinity, armazenamento quando necessário e Service para a interface. Proteja a UI e a API de gestão.

Recarregamento

Valide a configuração antes de aplicar:

amtool check-config alertmanager.yml

Use rollout controlado e verifique métricas do Alertmanager depois da mudança.

Observabilidade do Alertmanager

Monitore:

• alertas recebidos e ativos;
• notificações enviadas e falhas;
• latência de receivers;
• silences ativos;
• erros de configuração;
• membros do cluster;
• alertas limitados ou descartados;
• fila de notificações.

Testes de ponta a ponta

Crie um alerta sintético não crítico e confirme:

1. regra entra em pending;
2. passa a firing;
3. chega ao Alertmanager;
4. é roteada ao canal correto;
5. resolve após a métrica normalizar.

Erros comuns

• Group by Pod: gera uma notificação por réplica.
• Sem for: picos curtos paginam a equipe.
• Severity inconsistente: rotas não correspondem.
• Silence sem expiração: alertas desaparecem permanentemente.
• Inhibition ampla: problemas independentes são ocultados.
• Webhook sem autenticação: qualquer origem cria incidentes.
• Sem runbook: a notificação não orienta ação.
• Alertar causa técnica isolada: equipe recebe ruído sem impacto.

Conclusão

O Alertmanager no Node.js transforma alertas do Prometheus em notificações agrupadas e roteadas. Labels, group intervals, silences e inhibition reduzem tempestades durante incidentes grandes.

Crie regras baseadas em impacto, teste-as com promtool e mantenha runbooks. Proteja webhooks, configure alta disponibilidade e monitore o próprio Alertmanager. Assim, a equipe recebe menos mensagens, mas cada página tem maior chance de exigir uma ação real.