Monitoramento de Tarefas Cron

Problema com tarefas agendadas

Uma característica cruel dos crons é que, quando falham, ninguém te avisa. A aplicação web continua a servir pedidos, a página inicial parece normal, o monitoring está verde – mas algures no servidor, o backup noturno não foi executado há duas semanas. O worker da fila caiu após o deploy e os trabalhos pendentes estão a acumular-se. A sincronização horária silenciosamente perde linhas por um problema de permissões. Só dás conta quando algo a jusante acaba por falhar – normalmente mesmo no momento em que mais precisavas. A equipa de dados quer uma exportação, o suporte precisa da fila de emails, os ops do backup. Aí já é tarde demais.

O monitoring standard de uptime não apanha isto, porque não há nada para pingar. O cron não expõe endpoint HTTP, não abre porta, não inicia servidor. Arranca, termina, termina. Se deixar de funcionar – não há nenhum sinal da sua ausência, até começares a procurar.

Padrão inverso: monitoring heartbeat

O monitoring heartbeat (também chamado de "interruptor do homem morto" ou "monitorização de crons") inverte o sentido. Em vez de nós verificarmos o teu serviço, o teu serviço faz check-in no nosso. Adicionas uma linha ao cron – curl para um URL único que geramos – e esse URL regista um carimbo de data/hora em cada contacto. Nós monitorizamos a ausência destes pings. Se o URL não for contactado no intervalo esperado (mais margem), tratamos como uma corrida falhada e enviamos um alerta.

O modelo é simples, fiável e independente da linguagem. Tudo o que consiga fazer um pedido HTTP – integra-se. Bash com curl, Python com requests, Node com fetch, PHP com curl_init, Task Scheduler no Windows com Invoke-WebRequest, GitHub Actions, Kubernetes CronJobs, eventos agendados Lambda – qualquer coisa. Sem SDKs, sem agente, sem daemon para instalar.

Como configurar

No DiagnoSEO Uptime Monitoring, clica em "Adicionar monitor", escolhe o tipo "Heartbeat / cron". A ferramenta gera um URL único com token – por exemplo, https://app.diagnoseo.com/tools/uptime-monitoring/hb.php?t=abc123xyz9. Define o intervalo esperado (com que frequência o job deve correr, em minutos) e a margem (quanto atraso é aceitável antes de soarmos o alarme). Guarda.

De seguida, modifica o cron para fazer ping ao URL após cada execução bem sucedida. Três estilos, dependendo do ambiente:

# Bash cron – ping apenas em caso de sucesso
0 3 * * * /usr/bin/backup.sh && curl -fsS https://app.diagnoseo.com/tools/uptime-monitoring/hb.php?t=abc123xyz9 > /dev/null

# Ou se um sucesso parcial for aceitável
0 3 * * * /usr/bin/backup.sh; curl -fsS https://app.diagnoseo.com/tools/uptime-monitoring/hb.php?t=abc123xyz9 > /dev/null

# Python
import requests
def main():
    do_the_work()
    requests.get('https://app.diagnoseo.com/tools/uptime-monitoring/hb.php?t=abc123xyz9', timeout=5)

# GitHub Actions
- name: Notify heartbeat
  if: success()
  run: curl -fsS https://app.diagnoseo.com/tools/uptime-monitoring/hb.php?t=abc123xyz9

A partir desse momento, cada corrida bem-sucedida faz ping a nós, e nós registamos o timestamp. Se não virmos um ping dentro de intervalo + margem minutos, é aberto um incidente e as notificações são enviadas por todos os canais ativos: Email, Telegram, Slack, Discord, SMS.

Escolha do intervalo e margem

O intervalo deve corresponder ao agendamento do job. Backup noturno às 3:00 – intervalo 1440 minutos (24h). Sincronização horária – 60. Worker a consultar de 5 em 5 minutos – 5.

A margem absorve o jitter natural. Os crons não correm à nanosegundo certo – estão em fila, aguardam pelo fim da corrida anterior, fazem back-off em erros momentâneos. Um job de 24h com margem de 1h dá um buffer confortável sem atrasar alertas. Um worker de 5 minutos com 2 minutos de margem deteta quedas reais rapidamente sem falsos positivos por um hiato de 30 segundos. Regra geral: define a margem entre 10-50% do intervalo, conforme o job costuma "oscilar".

Padrões recomendados

• Ping só em caso de sucesso. Usa && no bash – uma corrida falhada não faz ping. Nós detetamos a ausência do ping e alertamos.
• Ping a cada iteração do loop. Para workers longos, faz ping dentro do loop após cada unidade de trabalho bem sucedida, não no fim. Assim, um worker bloqueado é detetado durante a execução.
• Um heartbeat por job lógico, não por script. Se três scripts juntos formam um pipeline noturno, faz ping uma só vez no fim da cadeia. Isso dá um sinal claro de "pipeline está ativo".
• Conjugação com logs. O heartbeat indica que o job executou. Os logs dizem o que fez. Juntos, oferecem uma visão completa.

O que acontece quando o heartbeat falha

O incidente é aberto quando o deadline passa. O dashboard mostra o monitor a vermelho com o erro "Sem heartbeat há X minutos". Notificações são enviadas por todos os canais que tens ativos. Quando recebemos novo heartbeat, o monitor volta automaticamente a up – fica marcado como ativo, o incidente fecha-se, e (se tiveres alertas de recuperação ligados) recebes notificação de regresso ao serviço.

Tudo segue a mesma lógica dos outros monitores – mapa de calor, percentagem de uptime, histórico, tags, pesquisa, exportação. Para o dashboard, o monitor heartbeat é apenas mais uma linha, ordenável e filtrável junto com HTTP, ping, porta e API.

Lista de verificação

Adiciona monitor → tipo Heartbeat → copia o URL gerado → adiciona ao cron / worker / scheduler → define intervalo e margem → guarda → concluído. Agora serás avisado em segundos quando uma tarefa agendada falhar – o que, a longo prazo, é das decisões mais críticas de monitorização que podes tomar.

Perguntas frequentes

• O que é o monitoring heartbeat / cron-job?

  Monitorização invertida — a tua tarefa agendada faz ping ao nosso URL quando arranca com sucesso. Se não ouvirmos dela dentro da janela esperada, enviamos alerta. Resolve o problema de falhas silenciosas: um cron job falhado não gera erro e não dispara o alerta tradicional de uptime.

• Como integrar o URL de heartbeat no meu cron?

  Adiciona curl -fsS <heartbeat_url> no final do comando cron. Se o comando anterior falhar, o curl não será executado e o heartbeat será omitido. Alternativamente, faz ping no início E no fim por caminhos diferentes — assim tens sinais separados de "started" e "completed".

• Que grace period devo definir?

  Cerca de 2 a 3x o tempo típico de execução da tarefa. Se o teu backup diário demora 30 minutos, define a grace em 90 minutos — cobre lentidões sem falsos alertas. Para tarefas com tempo de execução variável, define generosamente e usa o dashboard para identificar outliers.

• Posso monitorizar cron jobs que correm de hora a hora?

  Sim — define o intervalo de acordo (ex.: 60 minutos esperados e 15 minutos de grace). O monitor espera um ping pelo menos a cada 75 minutos. Se o teu job correr com maior frequência (por ex.: cada 5 minutos), o URL de heartbeat suporta — só tens de ajustar o intervalo.

• O heartbeat monitoring funciona com AWS Lambda / serverless?

  Sim. Adiciona um pedido HTTP de saída para o URL heartbeat no fim da função Lambda. O monitor trata isto tal como heartbeat de cron — mesmo alerting, mesmo grace period. Útil para Lambdas agendadas, onde os alarmes CloudWatch não apanham falhas silenciosas de execução.