Escrevendo expressões cron que não disparam surpresas

Uma expressão cron clássica tem cinco campos separados por espaço: minuto (0–59), hora (0–23), dia do mês (1–31), mês (1–12) e dia da semana (0–7). Cada campo aceita um valor único, uma lista separada por vírgulas, um intervalo com hífen, um passo após uma barra ou um asterisco para todo valor.

A maioria dos bugs de cron não é sintaxe exótica, mas um campo comum lido com descuido: um passo que reinicia no limite do intervalo, ou um campo de hora escrito para um relógio de doze horas num sistema que conta até vinte e três.

• ListasListas escolhem valores discretos: 0,30 no campo de minuto dispara no início da hora e na meia hora.
• Intervalos e passosIntervalos escolhem uma faixa: 9-17 no campo de hora cobre o horário comercial, e um passo o afina — 9-17/2 dispara a cada duas horas dentro da faixa.
• O asterisco casa tudoO asterisco não é «ignore este campo»; ele casa ativamente todo valor, o que se torna importante no momento em que dois campos de dia interagem.

Os campos de mês e dia da semana aceitam nomes ingleses de três letras — JAN a DEC e SUN a SAT — como aliases para seus números. 0 9 * JAN MON e 0 9 * 1 1 descrevem o mesmo agendamento, mas a versão com nomes se explica para o próximo leitor e resiste a edições de um a mais ou a menos.

• Sem distinção de maiúsculasOs nomes são analisados sem distinção de maiúsculas — mon, Mon e MON funcionam —, mas maiúsculas são a convenção que parece intencional.
• Nomes em intervalosOs nomes funcionam dentro de intervalos e listas também: MON-FRI é a faixa padrão de dias úteis, e JAN,APR,JUL,OCT escolhe os meses trimestrais.
• Leia a explicaçãoO Construtor e Explicador de Cron normaliza a expressão e explica cada campo separadamente — «mês: todo valor», «dia da semana: 1, 2, 3, 4, 5» — para você confirmar que o analisador leu os nomes como você pretendia.

Esta ferramenta segue regras de dia no estilo Vixie: quando nenhum campo de dia começa com *, basta que um deles corresponda. 0 9 13 * FRI significa todo dia 13 e toda sexta-feira, não apenas sexta-feira 13.

A saída do explicador é explícita sobre isso: ela relata a semântica como dom-dow-or junto às execuções calculadas, então uma expressão que vai disparar com muito mais frequência do que o pretendido mostra as cartas antes de chegar a um crontab.

• Passos com * ainda restringemSe um campo de dia começa com *, inclusive com passo como */2, esta ferramenta exige correspondência dos dois campos; a restrição do passo continua valendo.
• Sem * inicial, vale OUSe nenhum campo de dia começa com *, a ferramenta aplica OU: pode corresponder o dia do mês ou o dia da semana.
• E precisa de gambiarraPara acertar uma sexta-feira 13 de verdade, deixe o cron selecionar o dia 13 e faça o próprio comando verificar o dia da semana — ou use um agendador com semântica de E, que o cron clássico não é.

O campo de dia da semana numera domingo como 0, segunda como 1, e assim por diante até sábado como 6. A maioria das implementações também aceita 7 como um segundo domingo para quem conta a partir de segunda — o analisador do Toolars normaliza 7 para 0 internamente —, mas alguns sistemas aceitam só um dos dois, e numeração no estilo ISO começando segunda em 1 existe em outros lugares.

• 0 e 70 e 7 são ambos domingo onde 7 é aceito; escrever 0 é a escolha portátil entre agendadores.
• Um a menos silenciosoUm dia da semana 7 num sistema que o rejeita falha ruidosamente na hora do deploy, mas um dia da semana lido como «sétimo dia contando da segunda» falha em silêncio no dia errado.
• Reconfirme por plataformaQuando uma expressão migra entre implementações — crontab do sistema, uma plataforma de contêineres, um agendador de CI — reconfirme a numeração dos dias da semana em vez de presumir que ela sobreviveu à viagem.

Mudanças de horário de verão criam minutos locais inexistentes ou repetidos. Esta prévia pula um 02:30 inexistente na primavera e lista duas vezes um minuto correspondente repetido no outono. Um agendador real pode compensar a execução ou evitar a duplicata; confira sua política.

• A hora que faltaNa lacuna da primavera, a prévia não encontra um minuto local 02:30; alguns agendadores executam a tarefa perdida após a mudança.
• A hora dobradaNa sobreposição do outono, a prévia pode listar as duas ocorrências; um agendador real pode suprimir a segunda execução.
• UTC não tem DSTA saída limpa é UTC: ele não tem transições de horário de verão, então 30 2 * * * significa o mesmo instante todo dia do ano. O explicador oferece UTC, o fuso local do dispositivo e fusos nomeados como America/New_York e Europe/London.

A diferença entre uma expressão correta e uma que só parece plausível é uma lista de horários concretos de disparo. O Construtor e Explicador de Cron calcula as próximas dez execuções a partir de agora no fuso que você escolher, buscando até 366 dias à frente, e avalia num worker em segundo plano para que uma expressão pesada não trave a aba.

• Leia as execuçõesLeia as primeiras execuções contra a intenção: «dias úteis às 09:00» deve mostrar segunda a sexta às nove, e um sábado na lista é a armadilha do OU se anunciando.
• Cruze uma transiçãoSelecione um fuso horário nomeado e veja as próximas execuções se a próxima mudança de horário de verão cair na prévia de 366 dias. O cálculo começa agora; não é possível escolher uma data inicial.
• Erros explícitosExpressões inválidas geram erros. Nenhuma correspondência em 366 dias gera erro de limite de busca; uma a nove correspondências retornam um resultado parcial.