Monitoramento e alertas em integrações: o mínimo para não apagar incêndio

Painel cheio de gráfico que ninguém olha não reduz incidente. O que reduz é um conjunto pequeno de sinais que respondem rápido à pergunta certa: o sistema está saudável agora? Comece pelo essencial e cresça só quando houver dor real.

• Prefira poucos sinais acionáveis a muitos gráficos decorativos.
• Todo alerta precisa de um dono e de uma ação clara associada.
• Se um alerta não muda nenhuma decisão, ele é ruído e deve ser removido.
• Meça primeiro o que afeta o cliente: tempo de resposta e taxa de erro.

Os Golden Signals do SRE (latência, tráfego, erros e saturação) cabem bem em integrações. Eles cobrem 80% dos incidentes com pouca instrumentação.

• Latência: tempo de resposta do webhook e das chamadas a APIs externas, sempre em p95 e p99, nunca só a média.
• Tráfego: volume de eventos recebidos por minuto e mensagens processadas pela fila.
• Erros: taxa de respostas 5xx, falhas de processamento no worker e timeouts de parceiros.
• Saturação: profundidade da fila, uso de conexões do banco e memória ou CPU do worker.

Regra prática: latência e erros avisam que algo já está ruim para o cliente; tráfego e saturação avisam que algo vai ficar ruim em breve.

Cada componente da cadeia tem um punhado de métricas que vale a pena coletar. Abaixo o conjunto enxuto que entrega visibilidade sem virar projeto.

A idade da mensagem mais antiga na fila é a métrica mais subestimada. Profundidade alta pode ser pico saudável; idade alta significa que alguém já está esperando demais.

De todas as métricas, poucas merecem acordar alguém. Foque nos alertas que representam dor para o cliente ou risco iminente de fila travada.

• Taxa de erro 5xx acima de um limite por janela curta, por exemplo 2% em 5 minutos.
• Fila acumulando: profundidade crescente sem cair ou idade da mensagem acima do SLA.
• p95 de latência do webhook ou de API parceira acima do limite acordado.
• Falha de API parceira: sequência de timeouts ou taxa de erro que indica parceiro fora do ar.

Alerta demais é tão perigoso quanto alerta de menos. Quando tudo apita, ninguém reage. Três alavancas mantêm o ruído baixo: thresholds, janelas e severidade.

• Thresholds calibrados: defina limites a partir do comportamento real, não de chute, e revise após cada incidente.
• Janelas e duração: só dispare se a condição persistir por X minutos, evitando ruído de picos instantâneos.
• Severidade clara: separe page (acorda alguém) de ticket (revisa no horário comercial) de info (só registra).
• Agrupamento e silenciamento: agrupe alertas correlatos e silencie durante deploys ou janelas de manutenção conhecidas.

Meta saudável: todo alerta de page deve ser acionável e raro. Se ele dispara toda semana sem ação real, vire ticket ou ajuste o threshold.

O mínimo viável cabe em duas rotas: um /health para liveness e readiness, e um /metrics no formato Prometheus. Em Node, prom-client resolve com pouca cola.

Parceiro --> /webhook --> Fila --> Worker --> API externa
                 |          |        |
              metricas   metricas metricas
                 \         |        /
                  ---> /metrics ---> Prometheus --> Alertas

// metrics.js
const client = require('prom-client');
const register = new client.Registry();
client.collectDefaultMetrics({ register });

const httpDuration = new client.Histogram({
  name: 'http_request_duration_seconds',
  help: 'Latencia das requisicoes HTTP',
  labelNames: ['route', 'status'],
  buckets: [0.05, 0.1, 0.3, 0.5, 1, 2, 5],
});

const webhookErrors = new client.Counter({
  name: 'webhook_errors_total',
  help: 'Total de erros no processamento do webhook',
  labelNames: ['reason'],
});

const queueDepth = new client.Gauge({
  name: 'queue_depth',
  help: 'Mensagens pendentes na fila',
});

const queueOldestAge = new client.Gauge({
  name: 'queue_oldest_message_age_seconds',
  help: 'Idade da mensagem mais antiga na fila',
});

register.registerMetric(httpDuration);
register.registerMetric(webhookErrors);
register.registerMetric(queueDepth);
register.registerMetric(queueOldestAge);

module.exports = { register, httpDuration, webhookErrors, queueDepth, queueOldestAge };

// server.js
const express = require('express');
const { register, httpDuration } = require('./metrics');
const app = express();

// /health: liveness + readiness em um lugar
app.get('/health', async (req, res) => {
  const checks = { fila: await pingQueue(), banco: await pingDb() };
  const healthy = Object.values(checks).every(Boolean);
  res.status(healthy ? 200 : 503).json({ status: healthy ? 'ok' : 'degraded', checks });
});

// /metrics: exposicao no formato Prometheus
app.get('/metrics', async (req, res) => {
  res.set('Content-Type', register.contentType);
  res.end(await register.metrics());
});

// middleware para medir latencia por rota e status
app.use((req, res, next) => {
  const end = httpDuration.startTimer({ route: req.path });
  res.on('finish', () => end({ status: res.statusCode }));
  next();
});

Alerta sem runbook gera pânico. Cada disparo precisa de um roteiro de 3 a 5 passos que qualquer pessoa de plantão consiga seguir às 3 da manhã.

Runbook para taxa de 5xx alta no webhook:

1. Abra o painel e confirme se o pico é geral ou de uma rota específica.
2. Verifique logs recentes de erro e correlacione com o último deploy.
3. Cheque dependências: banco, fila e APIs externas estão respondendo?
4. Se foi deploy, faça rollback; se for dependência externa, ative o fallback ou circuit breaker.
5. Registre a causa e abra ticket de follow-up para ação definitiva.

Runbook para fila acumulada ou idade da mensagem alta:

1. Confirme se o worker está vivo e consumindo, olhando throughput recente.
2. Verifique se há mensagem em loop de retry travando o consumo.
3. Avalie escalar workers temporariamente para drenar o acúmulo.
4. Se a causa for API externa lenta, considere pausar produção até o parceiro normalizar.