Cron e fusos: por que seu job dispara na hora errada

Seu job não "quebrou do nada" — ele disparou em UTC enquanto você pensava em horário de Brasília. Agendamento parece trivial até o horário de verão (onde ainda existe), até o Kubernetes falar outro dialeto de cron que o Linux, e até um * no campo errado transformar limpeza mensal em tempestade a cada minuto. Este guia cobre campos, armadilhas de fuso e diferenças de plataforma — e por que validar expressões no navegador com o Safe Local Tools evita colar cron interno em sites públicos.

Cron em um parágrafo (e por que dialetos divergem)

O cron clássico tem cinco campos: minuto, hora, dia do mês, mês, dia da semana. Alguns sistemas acrescentam segundos ou ano. Cada campo aceita *, listas com vírgula, intervalos com hífen e passos com barra.

Não existe cron universal. crontab do Linux, atalhos @hourly, Quartz, AWS EventBridge e Kubernetes CronJob estendem ou restringem a sintaxe de formas diferentes. Copiar e colar entre eles é fonte clássica de incidente.

UTC versus local: escolha uma âncora e documente

Servidores muitas vezes rodam em UTC; humanos planejam em America/Sao_Paulo. O hiato gera relatórios "faltando" uma hora na primavera, execuções duplicadas no outono se você amar hora local ingenuamente e alertas de "9h local" que deriva duas vezes por ano.

Boa prática: armazenar horários em UTC na configuração; mostrar próximas execuções em fuso de negócio na interface usando base IANA.

Interações dia‑da‑semana × dia‑do‑mês e a armadilha */5

Alguns motores tratam DOW e DOM como OU, outros como E — sempre imprima as próximas N execuções. */5 no campo de minuto é a cada cinco minutos; no campo de hora, a cada cinco horas. Quem cola */5 * * * * esperando "cinco em cinco horas" cria avalanche.

Em Kubernetes: política de concorrência (Forbid, Allow, Replace), startingDeadlineSeconds pulando execuções após indisponibilidade e suspend desligando a agenda sem apagar o objeto importam tanto quanto a string cron.

Horário de verão e observabilidade

Na primavera, horários locais inexistentes precisam de política explícita; no outono, horas repetidas exigem deduplicação por id de execução se a carga tiver efeito colateral.

Monitore last_success_timestamp, duração e alerte se o silêncio passar de duas vezes o intervalo esperado — silêncio de cron corrói confiança em pipelines de dados.

Validar no Safe Local Tools roda no cliente, útil quando você não pode mandar nomes internos de job e expressões sigilosas para parsers de terceiros.

Documentação legível e segurança

Guarde no README o cron com comentário de fuso e dono. Trate cron como execução remota de código: controle quem edita CronJob, segredos montados e egress de workers. Para regras de calendário corporativo (último dia útil), cron puro não basta — registre quando você precisa de lib ou serviço adicional para não forçar expressões impossíveis.

Em microsserviços, nem toda tarefa periódica deveria ser um único tick de cron que precisa terminar antes do próximo: filas com backoff costumam absorver variação melhor do que um worker que falha sempre que a execução anterior extrapola o intervalo. Um padrão saudável é usar cron só para enfileirar trabalho e medir filas separadamente.

Quando integrações cruzam Windows Task Scheduler, SQL Server Agent e Kubernetes CronJob, mantenha um registro único de agendamentos com colunas de fuso, dialeto, blast radius e canal de escalonamento — senão o plantão perde tempo descobrindo qual sistema realmente dispara o relatório que sumiu.

Tabela rápida (UTC, cinco campos — confira o dialeto)

Intenção	Exemplo	Notas
Diário 09:00 UTC	0 9 * * *	Não confunda com minuto 9
Dias úteis 09:00 UTC	0 9 * * 1-5	0 ou 7 = domingo depende do dialeto
A cada 15 min	*/15 * * * *	Garanta runtime < 15 min
Primeiro dia do mês meia‑noite	0 0 1 * *	Monitore execuções espaçadas

Traduza cada linha para o dialeto real da sua plataforma antes de aplicar em produção.

Erros de cron são erros de configuração: alinhe o dialeto, ancore em UTC, pré‑visualize próximas execuções e revise semanas de DST. Quando precisar das próximas datas de disparo sem vazar cron interno, Experimentar o analisador de expressões cron →