Exemplos de expressão Cron: 30 cronogramas explicados (com armadilhas)

Cron tem agendado trabalhos recorrentes em sistemas Unix desde a década de 1970, e sua sintaxe de cinco campos agora impulsiona Kubernetes CronJobs, GitHub Actions, agendadores de nuvem como AWS EventBridge e Google Cloud Scheduler, CI pipelines e inúmeras bibliotecas de trabalhos. A sintaxe é compacta o suficiente para memorizar, mas sutil o suficiente para que a maioria dos engenheiros tenha enviado pelo menos um cronograma que correu na hora errada. Este guia explica cada campo, e depois lista 30 expressões práticas com notas sobre as armadilhas.

Os cinco campos

┌───────────── minute (0–59)
│ ┌─────────── hour (0–23)
│ │ ┌───────── day of month (1–31)
│ │ │ ┌─────── month (1–12 or JAN–DEC)
│ │ │ │ ┌───── day of week (0–6 or SUN–SAT; 7 is also Sunday on most systems)
│ │ │ │ │
* * * * *

Cada campo aceita:

• * todos os valores.
• Um número 5 significa exatamente 5.
• Uma lista 1,15 significa 1 e 15.
• Um intervalo 9-17 significa 9 a 17 inclusive.
• Um passo */15 significa cada quinquagésimo valor a partir do mínimo; 10-50/20 significa 10, 30, 50.

Um trabalho é executado quando a hora atual corresponde a todos os campos com uma exceção importante coberta abaixo. Coloque qualquer expressão em um [cron expression parser] ((/tools/cron-parser) para ver uma descrição em linguagem simples e os próximos tempos de execução.

A cada N minutos ou horas

1. * * * * * a cada minuto.
2. */5 * * * * a cada 5 minutos (a partir de: 00, 00, 05 e 10 ...).
3. */15 * * * * a cada 15 minutos.
4. 0,30 * * * * a cada meia hora, na hora e meia.
5. 7 * * * * a cada hora, 7 minutos depois. Escolher um minuto ímpar afasta a carga da hora mais movimentada.
6. 0 */2 * * * a cada 2 horas, às 00:00, 02:00, 04:00 ...
7. 0 */6 * * * quatro vezes por dia: 00:00, 06:00, 12:00, 18:00.
8. 15 8-18/2 * * * às 08:15, 10:15, 12:15, 14:15, 16:15 e 18:15.

Pitfall: os passos reiniciam em cada limite. */7 no campo de minutos dispara em: 00,: 07 ...: 56 e depois: 00 novamente, então o intervalo na hora é de 4 minutos, não 7. Se você precisar de um intervalo realmente fixo que não divida 60, use um agendador que suporte intervalos ou faça a verificação do tempo decorrido do trabalho.

Horários diários

9. 0 0 * * * todos os dias à meia-noite.
10. 30 2 * * * todos os dias às 02:30, uma janela de reserva clássica.
11. 0 9,17 * * * às 09h00 e às 17h00 diariamente.
12. 0 12 * * * ao meio-dia.
13. 45 23 * * * às 23:45, pouco antes da meia-noite para os relatórios de fim de dia.

Pitfall: Os trabalhos entre as 01:00 e as 03:00 horas locais podem ser ignorados ou executados duas vezes nas transições para a hora de verão. Se o seu servidor usa uma zona com horário de verão, agende tarefas críticas fora dessa janela ou execute o servidor em UTC.

Dias úteis e fins de semana

14. 0 9 * * 1-5 09:00 de segunda a sexta-feira.
15. */10 9-17 * * 1-5 a cada 10 minutos durante o horário de funcionamento nos dias úteis (última circulação às 17h50).
16. 0 10 * * 6,0 10:00 aos sábados e domingos.
17. 0 8 * * MON 08:00 todas as segundas. Os nomes são insensiveis a maiúsculas e minúsculas na maioria das implementações.
18. 30 16 * * 5 Sexta às 16h30.

Mensal e anual

19. 0 0 1 * * meia-noite do primeiro dia de cada mês.
20. 0 6 15 * * 06:00 no dia 15 de cada mês
21. 0 0 1,15 * * nos dias 1 e 15, comum para folha de pagamento.
22. 0 0 1 1 * à meia-noite de 1 de Janeiro.
23. 0 9 1 */3 * 09:00 no primeiro dia de cada trimestre (janeiro, abril, julho, outubro).
24. 0 0 L * * o último dia do mês. Nota: L é uma extensão suportada pelo Quartz, alguns agendadores de nuvem e algumas bibliotecas, mas não pelo cron clássico do Unix.
25. 0 22 28-31 * * combinado com uma verificação dentro do script ([ "$(date -d tomorrow +%d)" = "01" ]) uma maneira portátil de executar no último dia do mês com cron padrão.

Dia do mês ou dia da semana?

26. 0 9 13 * 5 muitas pessoas lêem isto como "sexta-feira 13". Em cron clássico significa ** todos os 13 do mês e todas as sextas-feiras **. Quando ambos os campos de dia são restritos (nem o *), o Vixie cron e seus descendentes executam o trabalho quando ** qualquer ** coincide.

Para executar apenas na sexta-feira 13, agende 0 9 13 * * e verifique o dia da semana no script, ou use um agendador com semântica AND explícita. Esta é a regra mais surpreendente no cron e vale a pena lembrar.

Cordas especiais

Muitas implementações de cron aceitam atalhos:

27. @hourly igual a 0 * * * *.
28. @daily ou @midnight 0 0 * * *.
29. @weekly — 0 0 * * 0.
30. @reboot uma vez na inicialização (apenas cron Unix; não disponível em Kubernetes ou GitHub Actions).

Diferenças de plataforma

• Kubernetes CronJobs usam sintaxe padrão de cinco campos. Desde o Kubernetes 1.27 você pode definir spec.timeZone: "Europe/Berlin"; caso contrário, os horários seguem a zona do gerente do controlador, que geralmente é UTC.
• Os cronogramas Ações do GitHub são sempre executados em UTC, podem ser atrasados durante períodos de alta carga, e o intervalo mínimo é de 5 minutos. Evite o 0 * * * * se a precisão for importante; escolha um minuto ímpar.
• AWS EventBridge utiliza seis campos (minute hour day-of-month month day-of-week year) e requer ? em um dos dois campos de dia.
• **Quartz (Java) ** e Spring usam seis ou sete campos com segundos primeiro: 0 0 9 * * MON-FRI.
• Os temporizadores do sistema usam uma sintaxe diferente e mais legível (OnCalendar=Mon..Fri 09:00) e lidam com corridas perdidas com Persistent=true.

Sempre confirme qual dialeto sua plataforma espera antes de copiar uma expressão.

Fusões horárias

Cron avalia expressões no fuso horário do agendador. Um trabalho escrito como 0 9 * * * por um desenvolvedor em Tóquio é executado às 09:00 UTC em um servidor UTC 18:00 em Tóquio. Recomendações:

• Executar servidores e agendadores em UTC e converter horários locais pretendidos para UTC ao escrever agendamentos.
• Se uma tarefa deve seguir o horário comercial local em todas as mudanças de horário de verão, use um agendador que suporte fusos horários explícitos.
• Registre o carimbo de hora de cada execução em UTC veja o [Guia de carimbo de tempo Unix] ((/blog/unix-timestamp-explained) para saber porquê.

Reforçar o emprego

O momento certo é apenas metade da batalha:

• Evitar sobreposições. Se um trabalho pode ser executado por mais tempo do que seu intervalo, use um bloqueio (flock no Unix, concurrencyPolicy: Forbid no Kubernetes).
• ** Fazer com que os empregos sejam idempotentes.** Um trabalho que se executa duas vezes, por exemplo após uma reatendimento ou uma sobreposição no horário de trabalho, não deve cobrar duas vezes aos clientes.
• ** Captura de saída.** E-mails cron clássicos de saída para o usuário local, que geralmente não vai a lugar nenhum. Redireccionar para registos e alerta em falhas.
• ** Use caminhos absolutos.** Cron é executado com um ambiente mínimo e PATH; scripts que funcionam em seu shell muitas vezes falham no cron.
• Monitor de silêncio. Um serviço de batimentos cardíacos que alerta quando um trabalho não é verificado detecta agendas quebradas que de outra forma falhariam silenciosamente.

Resumo

Os cinco campos do Cron minuto, hora, dia do mês, mês, dia da semana combinados com listas, intervalos e etapas cobrem quase todos os cronogramas recorrentes. Observe a regra OR quando ambos os campos de dia são definidos, passos que se reiniciam nos limites, DST em torno de 01:0003:00, e dialetos de plataforma com campos extras. Verifique cada expressão com um analisador que mostra corridas futuras antes de implementá-la.