Detecção de incidentes no PostgreSQL: de threshold de métrica a alerta resolvido

Um gráfico que fica vermelho não é gestão de incidentes. Um email que diz "CPU está alta" não é gestão de incidentes. Detecção real de incidentes significa: uma métrica cruza um threshold, um incidente é aberto com contexto, a pessoa certa é notificada, o incidente é rastreado de aberto a reconhecido a resolvido, e alertas duplicados não spamam a equipe. Este post percorre exatamente como o PG Monitoring faz isso.

O que dispara um incidente?

O PG Monitoring gera incidentes a partir de três fontes distintas, cada uma com sua própria lógica de detecção:

• Regras de threshold — métricas escalares que cruzam thresholds configuráveis de warning/critical. São o pão com manteiga: cache hit ratio abaixo de 95%, dead tuples acima de 100.000, uso de conexões acima de 80%, replication lag acima de 300 segundos, espaço livre em disco abaixo de 10%.
• Detecção de anomalias — detecção baseada em ML que sinaliza métricas que se desviam de uma linha de base aprendida, mesmo que não tenham cruzado um threshold fixo. Uma query que normalmente leva 50 ms e de repente está em 800 ms é uma anomalia, não uma violação de threshold.
• Regressão de plano — quando o PostgreSQL troca o plano de execução de uma query (ex.: de Index Scan para Seq Scan) e o novo plano é significativamente mais lento. Detectado comparando baselines de latência por query antes e depois da troca de plano.

Regras de threshold: configuráveis por organização e por instância

Cada métrica escalar que o agente coleta tem um threshold padrão de warning e critical. Os padrões são sensatos para a maioria das cargas, mas você pode sobrescrever por organização ou por instância:

-- Exemplo: regras de alerta avaliadas a cada push de métrica
{
  cache_hit_ratio:     { warning: 95,  critical: 90,  comparator: :lt },
  dead_tuples:         { warning: 100_000, critical: 500_000, comparator: :gt },
  long_running_queries:{ warning: 5,  critical: 15, comparator: :gt },
  connection_usage:    { warning: 80, critical: 95, comparator: :gt },
  replication_lag:     { warning: 300, critical: 600, comparator: :gt },
  disk_free_pct:       { warning: 15, critical: 5,  comparator: :lt }
}

Quando o agente envia um snapshot de métricas, o SaaS avalia cada regra contra o valor atual. Se o valor cruzar o threshold de warning, um incidente de warning é aberto. Se cruzar o critical, um incidente critical é aberto — ou o incidente de warning existente é escalado para critical.

Deduplicação: um incidente por problema, não por ponto de dado

O agente envia métricas a cada 60 segundos. Se o cache hit ratio está abaixo de 90% por uma hora, são 60 envios — mas você deve receber um incidente, não 60. O PG Monitoring deduplica por rule_key: antes de abrir um novo incidente, verifica se já existe um incidente não resolvido para a mesma regra e instância. Se existe, o incidente existente é atualizado (severidade renovada, último valor) em vez de duplicado.

A mesma lógica se aplica a alertas de query longa: se uma query com PID 12345 está rodando há 35 minutos e já existe um incidente para ela, o título do incidente é atualizado para "Query rodando há 35 min (PID 12345)" em vez de abrir um novo. Quando a query termina, o incidente é auto-resolvido.

O ciclo de vida do incidente

Cada incidente segue um ciclo de três estados:

1. Aberto (open) — o incidente foi detectado mas ainda não foi olhado. É aqui que começa.
2. Reconhecido (acknowledged) — alguém da equipe viu e assumiu. O usuário e timestamp do reconhecimento são registrados.
3. Resolvido (resolved) — o problema subjacente foi corrigido (ou se auto-corrigiu). O usuário que resolveu, texto de resolução e causa raiz são registrados. A duração total do incidente (de detected_at a resolved_at) é calculada automaticamente.

Incidentes também podem ser reabertos se o problema voltar, e atribuídos a um membro específico da equipe para roteamento.

Transmissão em tempo real

Quando um incidente é criado ou atualizado, ele é transmitido via WebSocket para todos os clientes conectados na mesma organização. Se você tem o dashboard aberto, o incidente aparece instantaneamente — sem refresh. A transmissão inclui título, severidade, nome da instância e timestamp de detecção.

Roteamento de notificações

Além da transmissão por WebSocket, incidentes disparam entrega assíncrona de notificações:

• Email — enviado via NotificationDeliveryJob, enriquecido com sugestões de melhoria geradas por IA quando o analisador de IA está ativado.
• Slack / PagerDuty / webhooks — configuráveis por organização, roteados por severidade (ex.: critical → PagerDuty, warning → Slack).
• Webhooks n8n / Grafana — sistemas externos também podem enviar incidentes para dentro do PG Monitoring via webhooks autenticados, então alertas de outras ferramentas aparecem na mesma fila de incidentes.

Detecção de anomalias: além de thresholds fixos

Thresholds pegam "cache hit ratio abaixo de 95%." Não pegam "o tempo médio de execução desta query foi de 50 ms para 400 ms" — porque 400 ms pode estar bem abaixo de qualquer threshold fixo que você estabeleceria. O detector de anomalias do PG Monitoring roda como um job periódico do Sidekiq e usa análise estatística (z-score, médias móveis) sobre métricas por query do pg_stat_statements:

• Computa uma baseline de comportamento normal por fingerprint de query.
• Sinaliza desvios onde o z-score excede uma sensibilidade configurável (tipicamente 3σ).
• Abre um incidente com o texto da query, a média da baseline, o valor atual e o z-score.
• Incidentes são deduplicados por fingerprint de query por hora — sem spam.

Regressão de plano: o assassino silencioso

O planner do PostgreSQL é bom, mas não é perfeito. Uma estatística desatualizada, um problema de parameter sniffing, ou uma mudança de config pode fazer o planner trocar de Index Scan para Sequential Scan em uma tabela grande. O texto da query não muda — só o plano — e de repente uma query que levava 20 ms leva 800 ms. O detector de regressão de plano do PG Monitoring:

1. Rastreia o tempo médio de execução por fingerprint de query ao longo do tempo.
2. Detecta quando a média salta por um fator significativo (3× ou mais).
3. Abre um incidente critical com a porcentagem de lentidão, a latência antes/depois, e uma sugestão de verificar estatísticas desatualizadas (rodar ANALYZE).

Integração via webhook: alertas externos como incidentes

O PG Monitoring aceita alertas vindos de sistemas externos via webhooks autenticados. Tanto payloads de alerta do Grafana quanto alertas de workflows do n8n são suportados. O webhook autentica via um secret compartilhado ou API key por organização, resolve a instância de destino por nome ou ID, e cria um incidente com o título, descrição e severidade do alerta externo. Isso significa que toda sua superfície de alertas — métricas nativas do Postgres, dashboards do Grafana, e workflows customizados do n8n — converge para uma única fila de incidentes.

Por que isso importa

Um incidente não é apenas um alerta. É um registro rastreado de um problema da detecção à resolução, com severidade, propriedade, timeline e causa raiz. Quando você olha para trás e pergunta "o que aconteceu na terça-feira passada às 3 da manhã", você não precisa greppear logs de email — você abre o incidente e vê o histórico completo: quando foi detectado, quem reconheceu, quanto tempo levou para resolver, e qual foi a causa raiz. Essa é a diferença entre monitoramento e gestão de incidentes.