Como monitorizar tarefas cron: 5 padrões com heartbeat

As tarefas cron falham em silêncio. Cinco padrões de heartbeat - do dead man's switch ao wrapper de exit code - para saber da falha primeiro.

O heartbeat (ou "dead man's switch") inverte a lógica. Em vez de alertar quando algo está mal, a sua tarefa faz ping a um endpoint de monitorização quando está tudo bem. Se o ping esperado não chegar a tempo, o monitor alerta. Sem ping, sem novidades, grande problema.

Em baixo estão cinco padrões, do mais simples ao mais robusto. Todos pressupõem que tem um URL de heartbeat da sua ferramenta de monitorização.

Padrão 1: O clássico dead man's switch

A configuração mais simples possível. A sua tarefa chama o URL quando termina. Se o monitor não receber novidades dentro da janela esperada, alerta.

# Backup diário às 02:30, ping ao terminar
30 2 * * * /usr/local/bin/backup.sh && curl -fsS https://o-seu-monitor/ping/abc123

O && é importante: o curl só corre se o backup.sh terminar com código 0 (sucesso). Se o backup falhar, nenhum ping é enviado e o monitor apanha-o. Os flags -fsS fazem o curl falhar em silêncio em erros HTTP, mas continuam a mostrar problemas reais.

Ponto fraco: confirma apenas que o script correu e terminou com zero. Se o script engole os seus próprios erros e termina na mesma com zero, recebe um falso "está tudo bem".

Padrão 2: Ping apenas em sucesso real

Torne o sinal de sucesso explícito, em vez de confiar no encadeamento de códigos de saída na shell. Em scripts com vários passos, é mais claro.

#!/bin/bash
set -euo pipefail   # falha alto em qualquer erro
run_the_backup
verify_the_backup    # confirme mesmo que a saída existe e faz sentido
curl -fsS https://o-seu-monitor/ping/abc123   # só alcançado se tudo acima passou

O set -euo pipefail significa que qualquer comando sem sucesso interrompe o script antes do ping. Acrescentar um passo de verificação real (existe o ficheiro de backup, é maior do que zero bytes) fecha a brecha "terminou com zero, mas não fez nada" do Padrão 1.

Padrão 3: Wrapper de código de saída

Quando não pode alterar a própria tarefa (um binário de terceiros, um script de fornecedor), embrulhe-a. O wrapper sinaliza o arranque, corre a tarefa e reporta o código de saída.

#!/bin/bash
URL=https://o-seu-monitor/ping/abc123
curl -fsS "$URL/start"                  # sinal "arranquei"
/opt/vendor/report-generator            # tarefa que não controla
EXIT=$?
curl -fsS "$URL/$EXIT"                   # reporta o código de saída

Sinalizar o arranque permite ao monitor medir também a duração da execução e detetar uma tarefa que arrancou mas nunca terminou (ficou pendurada). Reportar o código de saída permite-lhe distinguir "correu bem" de "correu e falhou".

Padrão 4: Ping condicional (faça ping só quando o trabalho teve sentido)

Algumas tarefas correm conforme o plano, mas só por vezes fazem trabalho real (um processador de fila que muitas vezes encontra a fila vazia). Não quer um alerta de "heartbeat em falta" quando a tarefa legitimamente não fez nada. Faça ping apenas quando o trabalho real aconteceu e ajuste o plano em conformidade.

#!/bin/bash
PROCESSED=$(process_queue)
if [ "$PROCESSED" -gt 0 ]; then
  curl -fsS "https://o-seu-monitor/ping/abc123?count=$PROCESSED"
fi

Defina o período esperado do monitor para o maior intervalo real entre execuções verdadeiras. O preço é a sensibilidade: uma janela mais longa significa deteção mais lenta, por isso use isto apenas quando o trabalho irregular for mesmo esperado.

Padrão 5: Jitter e janelas de grace

Os planos reais derivam. Uma tarefa marcada para as 02:00 pode arrancar às 02:00:04 por causa da carga e a duração de uma tarefa diária oscila. Se o monitor espera o ping exatamente no intervalo, o jitter normal alerta-o sem necessidade.

A solução é um período de grace: diga ao monitor para esperar uma margem extra depois do tempo esperado antes de alertar. Um backup diário que costuma demorar 8 minutos pode usar uma janela de grace de 20 minutos. Quer também algum jitter no próprio agendamento, quando tem muitas tarefas, para que não sobrecarreguem o mesmo recurso no mesmo segundo:

# Acrescenta um pequeno atraso aleatório (0-59s) para distribuir as tarefas das 02:00
0 2 * * * sleep $((RANDOM % 60)) && /usr/local/bin/backup.sh && curl -fsS https://o-seu-monitor/ping/abc123

As janelas de grace são a diferença entre um monitor em que confia e um que silencia depois do terceiro falso alarme. Defina o grace para exceder confortavelmente o pior tempo de execução real da tarefa, não a sua média.

Resumo rápido

Padrão	Melhor para	Apanha
Dead man's switch	Tarefas simples de um só comando	Tarefa não correu / terminou com erro
Ping em sucesso	Scripts com vários passos	"Terminou com zero, mas não fez nada" silencioso
Wrapper de código de saída	Tarefas que não pode alterar	Bloqueios, códigos de saída reais, duração
Ping condicional	Tarefas com trabalho irregular	Falhas sem falsos alertas de "em falta"
Jitter e grace	Qualquer coisa com tempo de execução variável	Elimina falsos alarmes por drift

Como pôr isto em prática

Comece com o Padrão 1 na tarefa mais importante ainda hoje (backup, execução de faturação, sincronização de dados). Acrescente a verificação (Padrão 2) e a janela de grace (Padrão 5) à medida que começa a depender dela. Para um guia mais detalhado de configuração do heartbeat, veja o nosso artigo monitorizar tarefas cron com heartbeat.

Se a sua tarefa comunica com um serviço através de uma porta específica, confirme primeiro a acessibilidade com o verificador de portas gratuito. E quando estiver pronto para monitorizar tarefas agendadas juntamente com sites e APIs num só lugar, veja como funciona o monitoring de uptime do ePulz.io - o período experimental de 7 dias é gratuito, sem cartão.