Uma expressão cron parece pequena porque descreve apenas quando acordar um processo. O custo de produção está ao redor do gatilho: entregas duplicadas, execuções sobrepostas, janelas perdidas, interpretação de fuso, retries, gravações parciais e a pergunta que surge na hora do incidente: como saber se o trabalho terminou corretamente?
Agendadores têm semânticas de entrega, atraso e retry diferentes. Alguns podem chamar duas vezes; outros atrasam ou perdem uma execução sob certas condições; o destino também pode rejeitar a chamada muito depois do horário previsto. Trate a invocação como pelo menos uma vez, a menos que o contrato da plataforma prove o contrário, e torne o trabalho idempotente. Uma chave como nome da tarefa mais período lógico impede efeitos de negócio duplicados.
| Falha | Sintoma | Resposta de projeto |
|---|---|---|
| Invocação duplicada | Duas cobranças, exportações ou notificações | Chave de idempotência, restrição única e upsert seguro |
| Sobreposição | Execução nova disputa estado com a anterior | Lease com expiração, limite de concorrência ou partição |
| Execução atrasada ou perdida | Relatório defasado ou janela de sincronização pulada | Watermark e busca retroativa do intervalo não processado |
| Conclusão parcial | Parte dos registros muda, mas o job falha | Checkpoint por lote e replay seguro |
| Fuso ou horário de verão | Tarefa de negócio roda em hora inesperada | Instantes em UTC e fuso de negócio declarado |
| Falha silenciosa | Agendador invocou, mas a saída está errada ou vazia | Validar pós-condições e alertar sobre ausência de resultado |
“Todo dia às 02:00” é incompleto quando o negócio usa fuso local ou muda o horário de verão. Decida se a tarefa segue tempo decorrido em UTC ou calendário local. Persista o período pretendido, não apenas o horário de início. Uma reconciliação diária precisa saber qual data de negócio atende mesmo quando começa atrasada.
Defina duração máxima e tamanho dos lotes. Registre horário agendado, início real, período lógico, tentativa, checkpoint, volume processado, resultado e categoria do erro. Grave a execução antes de efeitos irreversíveis. Alerte também para conclusão atrasada: um job pode terminar sem exceção e processar zero registros por uma janela de consulta incorreta.
Retries precisam de limite, backoff exponencial com jitter quando apropriado e caminho terminal como dead-letter ou revisão humana. Não repita efeitos não idempotentes às cegas. Defina quem pode reprocessar um período com segurança e como isso fica auditado.
Uma limpeza simples pode exigir apenas agendador e handler idempotente. Trabalho com várias etapas, esperas, aprovação humana, compensação ou progresso durável pede workflow ou máquina de estados com fila. Mantenha o agendador enxuto: calcule o período e enfileire; o worker reserva e processa com concorrência limitada.
Veja também filas para equipes pequenas, chaves de idempotência e observabilidade econômica.
A expressão cron é a parte mais barata. Tarefas confiáveis precisam de identidade lógica, efeitos idempotentes, controle de concorrência, recuperação de janelas, retries limitados e prova de conclusão. Projete essas garantias e então escolha o agendador.