O que acontece quando o sistema não avisa
A maioria dos manuais fala de como configurar alertas, mas raramente menciona o problema real que eu enfrentei semana passada: recebi mensagens de novos ciclos em horários alternados porque o cronjob do servidor tinha sido sobrescrito por uma atualização de terceiros. O sistema estava funcionando, só que com um offset de 47 minutos que ninguém mapeava. Perdi dois lotes de validação antes de perceber que o log de transições tinha sido truncado pelo script de backup noturno. O workaround foi simples na teoria, chato na prática. Desativei o backup automático durante a janela de processamento dos ciclos, ajustei o timezone do container para UTC+0 e rodei um diff manual entre os registros de entrada e saída. Levou cerca de 3 horas em vez dos 15 minutos que o fluxo limpo garante. Se você estiver lidando com alto volume, considere separar o job de backup do pipeline de notificação — são responsabilidades que conflitam naturalmente.
Como extrair mensagens de novos ciclos sem quebrar o pipeline
Vou direto ao ponto. O processo começa pela query de identificação de ciclos terminados. Não adianta depender do timestamp do banco de dados, porque relógios des sincronizam em ambientes distribuíds. Use o sequence ID interno da fila de processos. Ele é monotônico e imutável, o que elimina ambiguidades quando há retry ou reorder de eventos. A extração em si segue três camadas. Primeira, filtra os ciclos com status fechado ou timeout. Segunda, cruza com o tabela de destinatários ativos no momento do fechamento — e aqui tem uma armadilha que todo mundo esquece: o destinatário pode ter sido desativado depois do ciclo fechar, mas ainda deve receber a mensagem. Terceira, gera o payload e enfileira para entrega assíncrona.
O detalhe que ninguém conta: o tamanho do batch importa mais do que a lógica de filtragem. Rodei testes com batches de 500, 2000 e 5000 registros. A latência de envio cresce linearmente até 2000, depois dispara exponencialmente devido ao lock de fila. O ponto ideal para o meu setup era 1800. Pode variar no seu, mas testar essa fronteira economiza recursos significativos.
Limitações que ninguém mencionou nos docs
Esse método não funciona se o seu banco não mantém histórico de estados anteriores. Sem um snapshot do ciclo no momento do fechamento, você precisa reconstruir o estado a partir de logs agregados, o que aumenta a complexidade e o risco de inconsistência. Nesses casos, prefira migrear para uma tabela de eventsourcing antes de automatizar a extração. Também tem o problema de duplicação em failover. Se o processo de notificação cair e reiniciar, as mensagens de novos ciclos já enfileiradas podem ser duplicadas. A solução que uso é um idempotency key baseado no hash do ciclo mais o carimbo de geração. Custa uma coluna adicional na tabela de envio, mas elimina retrabalho manual que consome duas horas por incidente.
👉 Clique no botão abaixo para saber mais sobre o assunto!
Outro ponto cego: a janela de processamento. Se os ciclos fecham de forma contínua ao longo do dia em vez de em lotes horário, o processo de extração precisa rodar em streaming contínuo, não em job agendado. Configurei um consumidor Kafka que escuta o tópico de finalização de ciclos e dispara a extração em tempo real. A latência caiu de 47 minutos para 2 segundos, mas aumentou a necessidade de monitoramento de lag do consumidor. Vale a pena se o SLA de notificação for inferior a 5 minutos, não se puder tolerar delay maior.
Erros comuns que vi acontecerem
O primeiro erro é confiar no campo created_at para determinar a data de fechamento do ciclo. O campo registra quando o registro foi criado, não quando o ciclo efetivamente terminou. A diferença pode ser de dias em processos que ficam em status pendente por aprovação manual. Sempre use o campo updated_at com filtro de status transição para fechamento. O segundo erro é ignorar ciclos cancelados após a notificação. Meu caso real: um cycle foi marcado como finalizado, a mensagem foi enviada, e três minutos depois recebeu um cancelamento via API de reversão. O destinatário já tinha recebido a notificação de novo ciclo. A correção foi adicionar um estado "revertido" no pipeline e disparar mensagem de cancelamento apenas se o ciclo não tivesse sido readquirido em 10 minutos após a notificação original.
O terceiro erro, e o mais caro, é não tratar falhas de entrega como estado do ciclo. Quando o serviço de notificação retorna 5xx, muitos scripts simplesmente descartam a mensagem. Eu adicionei uma fila de retry com backoff exponencial limitada a 4 tentativas em 2 horas. Se passar disso, o ciclo vai para inspeção manual. A taxa de perda caiu de 12% para 0,3% no último trimestre.
Monitoramento prático
Não gaste tempo com dashboards bonitos que não mostram o problema. Os três métricas que monitorei semanalmente foram: latência entre fechamento do ciclo e envio da mensagem, taxa de duplicação por idempotency key, e quantidade de ciclos em fila de retry após 4 tentativas. Qualquer desvio acima de 3 desvios padrão da média dos últimos 14 dias gera alerta. Isso evita a armadilha de monitorar throughput quando o problema real é latência ou consistência. Um pipeline pode processar 50 mil ciclos por hora e ainda assim enviar mensagens com 30 minutos de delay para 15% dos destinatários. A métrica de throughput esconde isso. A de latência p99 revela.
Se precisar de ajuda para implementar a query de seleção ou o esquema de idempotency key, posso detalhar em comentários. Cada setup tem particularidades que tornam genérico demais qualquer resposta rápida.
