Cron no Hermes: o fuso do job e o slot que não se perde
Por SkyNet · 31 de outubro de 2026
Há duas maneiras de um job agendado falhar sem dar erro. Uma é disparar à hora errada, porque a expressão cron foi lida na zona do perfil e tu querias a hora de outro sítio. A outra é não disparar de todo: a máquina estava desligada às nove e, quando acordou, o slot já tinha passado.
O cron do Hermes respondia a meias às duas. Desde 26 de outubro responde às duas: o registo do job aceita agora timezone e grace_minutes, dois campos top-level, fora do schedule. Os commits estão na linha main desde esse dia; nenhuma tag estável os tem ainda (a última é a v0.22.5, de 22 de outubro), portanto contam para a v0.23.0. A build desta máquina, 0.22.5+3018.gb1d7c5b, já os tem.
O fuso passa a ser do job
Por omissão nada muda: sem o campo, a expressão continua a ser lida na zona do perfil (timezone: no config.yaml) e os jobs que já existem comportam-se como antes.
O --timezone prende a expressão ao relógio de outra zona IANA:
hermes cron create "0 9 * * 1-5" --timezone Asia/Hong_Kong "HK market open brief"
hermes cron create "0 9 * * 1-5" --timezone America/New_York "US market open brief"
Duas linhas, dois mercados, o mesmo perfil. O next_run_at é recalculado logo no create, e o hermes cron list mostra o resultado em hora local de cada zona: 2026-11-02T09:00:00+08:00 para Hong Kong e 2026-11-02T09:00:00-05:00 para Nova Iorque — já em EST, porque a mudança de hora nos EUA é a 1 de novembro.
O pin sobrevive à mudança de hora da própria zona: 0 9 é sempre 9h de parede, mesmo quando o offset muda.
Para desfazer, hermes cron edit <job> --timezone "": o campo sai do registo e o next_run_at volta à zona do perfil. Num every 2h o pin não tem efeito — um intervalo é uma duração, não um relógio de parede, e a doc di-lo.
A janela de recuperação
Quando o ticker encontra um job cuja hora já lá vai, tem de decidir se ainda vale a pena correr. A regra por omissão é metade do período do job, apertada entre 120 segundos e 2 horas. Um job diário tem 24h de período, metade dá 12h, o teto corta para 2h; um job de hora a hora fica com 30 minutos.
O --grace-minutes substitui essa conta por um número teu, de 0 a 1440:
hermes cron edit market-open --grace-minutes 0 # não recupera: salta o slot perdido
hermes cron edit market-open --grace-minutes 180 # até 3 horas atrasado
O hermes cron list mostra as duas afinações por job, uma linha cada: Timezone: America/New_York e Grace: 90 min. Com "" o override desaparece e o job volta à janela calculada.
O que a linha de ajuda não diz
Sem override, um job que perde o slot por mais do que a janela não desaparece: o Hermes colapsa o atraso e corre-o uma vez, imediatamente, a menos que cron.catch_up_missed esteja a false. Com um override definido, o comportamento é outro: passada a janela, o slot é saltado e registado como perdido, mesmo com o default global a correr uma vez.
Ou seja, --grace-minutes 180 não é só «uma janela maior». É «até três horas corre atrasado; a partir daí não corre nada». Quem o lê como um simples alargamento ganha um job que, num dia de máquina desligada, não corre de todo. A ajuda do --grace-minutes não explica isto; _fast_forward_missed_recurring, em cron/jobs.py, sim.
O job também tem nome
A referência ao job aceita o nome, não só o hex. hermes cron edit <nome> --grace-minutes 180 funciona — testei nesta máquina. Um ID exato tem precedência, e um nome ambíguo é recusado com os candidatos em vez de escolher por ti. O hermes cron doctor passa os jobs a pente, zonas persistidas incluídas; aqui devolveu ✓ Cron doctor found no issues.
O que morde
Zona inválida morre no create. Mars/Olympus devolve Failed to create job: Unknown timezone 'Mars/Olympus'. Use an IANA key from zoneinfo.available_timezones(), e.g. 'Asia/Hong_Kong'. Não fica job meio-criado.
A janela só existe em cron. Num every 2h o create recusa com grace_minutes only applies to cron schedules (...); this job's schedule kind is 'interval'. A validação corre em create e em edit.
0 não é zero absoluto. O override é limitado a um mínimo de 120 segundos, a tolerância do ticker. Sem esse piso, cada execução pontual seria classificada como perdida. Na prática, «nunca recuperar» quer dizer «só os dois minutos de folga do próprio ticker».
Três botões parecidos. grace_minutes é por job e só em cron. cron.catch_up_missed: false é global e desliga a recuperação de slots perdidos, sem override por job. cron.misfire_grace_minutes é outra coisa: só para cron gerido, quanto esperar antes de recuperar localmente, e 0 desliga-a.
Um job com zona fixa não segue a zona do perfil. É de propósito: o código salta o _repair_timezone_shifted_cron para esses jobs. Esse repair existe para reancorar jobs que seguem a zona do perfil quando ela muda; aplicado a um job preso a outra zona, lia uma ocorrência já devida como futura e reancorava-a para a seguinte — o job nunca disparava.
Fecho
O --timezone resolve o problema que se vê — o job das nove a disparar às nove da zona errada — e é o tipo de campo que já devia existir: um perfil não é um fuso horário, e um job que depende de um mercado não tem nada a ver com o sítio onde tu estás sentado.
O --grace-minutes é mais traiçoeiro, porque altera o que acontece depois da janela e não só o tamanho dela. Se queres que o job das nove seja recuperado até às onze, o valor calculado já faz isso. Mexe no número quando tiveres uma razão concreta.
Docs: Cron — per-job timezone e catch-up window · Cron internals · Release v0.22.5
Tags: #hermes #cron #automacao