cron-doctor

Visão Geral

Cron é enganosamente propenso a erros. O modo de falha é silencioso — uma expressão sintaticamente válida que simplesmente nunca é executada, ou é executada com muito mais frequência do que o pretendido. 0 0 30 2 * é analisado corretamente e depois fica inativo para sempre (fevereiro não tem dia 30). 0 0 1,15 * 1 parece "dia 1 e 15 se for segunda-feira", mas na verdade significa "dia 1, dia 15, OU toda segunda-feira" — ~6 execuções/mês em vez de ~2.

Esta habilidade ensina um agente a capturar esses erros antes que cheguem à produção. Ela vem com um mecanismo de validação sem dependências (scripts/cron-engine.js, sem necessidade de instalação) que analisa, descreve, valida profundamente e calcula os próximos horários de execução.

Quando Usar Esta Habilidade

• Use quando um usuário escrever, editar, revisar ou implantar uma expressão cron — em um crontab, um CronJob do Kubernetes, um schedule do GitHub Actions, um DAG do Airflow, uma agenda Celery beat, um timer systemd, ou qualquer tarefa agendada.
• Use ao depurar um job que "não foi executado" ou "foi executado no momento errado".
• Use quando um usuário perguntar "o que essa expressão cron significa?" ou "quando isso será executado a seguir?" ou "com que frequência isso é executado por ano?"
• Use ao revisar um pipeline de CI/CD ou configuração de infraestrutura que contenha um campo schedule.
• Use quando um usuário colar uma expressão cron de 5 campos e pedir uma verificação de sanidade.

Como Funciona

Passo 1: Analisar a expressão

Divida por espaços em 5 campos: minuto, hora, dia-do-mês, mês, dia-da-semana. Confirme os intervalos válidos:

Passo 2: Descrever em linguagem clara

Declare o que o usuário acha que a expressão faz versus o que ela realmente faz. Seja explícito sobre a semântica de OU vs. E para dia-do-mês + dia-da-semana (veja a armadilha nº 2).

Passo 3: Executar a lista de verificação de armadilhas

Verifique as cinco armadilhas abaixo e sinalize qualquer uma que se aplique.

Passo 4: Calcular as próximas execuções e a contagem anual de execuções

Calcule os próximos 5 horários de execução como datas concretas para que o usuário possa verificar se o agendamento se comporta como esperado. Estime a contagem anual de execuções — um agendamento que executa 365 vezes/ano versus 12 vezes/ano representa uma diferença de custo e carga de ~30×.

As Cinco Armadilhas do Cron

Estes são os bugs que passam na validação crontab -l, mas falham em produção.

1. Datas impossíveis — o bug "nunca executa"

0 0 30 2 *

Sintaxe válida. Nunca executa. Fevereiro não tem dia 30. Este agendamento é um job morto que fica inativo para sempre. O mesmo se aplica ao dia 31 em qualquer mês de 30 dias: 0 0 31 4 *, 0 0 31 6 *, 0 0 31 9 *, 0 0 31 11 *.

Correção: use 0 0 28-31 * * e verifique o fim do mês no script, ou use a sintaxe L (último dia) se o seu agendador suportar.

2. Semântica de OU — o bug "executa com muita frequência"

0 0 1,15 * 1

NÃO significa "meia-noite no dia 1 e 15 se for segunda-feira." Significa "meia-noite no dia 1, no dia 15, OU toda segunda-feira." Isso são ~6 execuções/mês em vez de ~2.

Esta é a regra de cron mais mal compreendida. Quando tanto o dia-do-mês QUANTO o dia-da-semana são restritos (nenhum é *), o cron usa lógica OU, não E.

Correção: se você precisa de "dia 1 e 15 apenas se for segunda-feira", execute diariamente e verifique no script:

0 0 * * 1 [ "$(date +%d)" = "01" -o "$(date +%d)" = "15" ] && your-command

3. Pico de meia-noite — o bug "tudo de uma vez"

0 0 * * *

Todo job agendado para 0 0 compete por recursos exatamente às 00:00. Backups de banco de dados, rotação de logs, renovação de certificados, geração de relatórios — todos executam simultaneamente. Isso causa picos de carga, esgotamento de pools de conexão e timeouts em cascata.

Correção: distribua os jobs pela hora. Use 17 2 * * * ou 43 3 * * * em vez de 0 0. Jitter é seu amigo.

4. Passos irregulares — o bug "deriva"

*/7 * * * *

NÃO significa "a cada 7 minutos uniformemente." Significa "a cada 7 minutos começando em 0, depois reinicia em 60." Então: 0, 7, 14, 21, 28, 35, 42, 49, 56 — depois 0 novamente (uma lacuna de 4 minutos). Os intervalos derivam: 7,7,7,7,7,7,7,7,4.

Correção: 60 não é divisível por 7. Use valores de passo que dividam 60 uniformemente: */5, */10, */15, */20, */30. Se você realmente precisa de a cada 7 minutos, use um loop com sleep 420.

5. 29 de fevereiro em ano bissexto — a "surpresa anual"

0 0 29 2 *

Executa apenas em anos bissextos — 29 de fevereiro de 2024 / 2028 / 2032… Se alguém escrever isso

…