Monitorização de cron jobs e workers em background via heartbeat

Em resumo: A monitorização HTTP clássica não vai detetar que o teu cron noturno a enviar faturas ou a sincronizar dados caiu. O padrão heartbeat inverte a direção da comunicação - o cron reporta à monitorização, e se não chamar no tempo esperado, recebes um alerta.

O problema: tarefas em background sem endpoint HTTP

Um backend típico tem caminhos:

• Pedidos web (HTTP/HTTPS para o servidor) - monitorizas com uptime check.
• Cron jobs (backup diário, faturação mensal, sync horária) - não têm endpoint HTTP, a monitorização externa não os vê.
• Workers (Celery, BullMQ, Sidekiq) a consumir uma queue - também sem HTTP.

Se o cron cai (mudas crontab e fazes typo, o servidor não tem disco, falta uma variável de ambiente, um upgrade de dependência partiu o import), ninguém te avisa - até que segunda de manhã reparas que as faturas não foram enviadas no fim de semana.

Padrão heartbeat: o cron pinga a monitorização

O princípio é inverso à monitorização normal:

1. No serviço de monitorização crias um monitor heartbeat com intervalo esperado (ex. "a cada 60 minutos").
2. Recebes uma URL heartbeat única: https://epulz.io/heartbeat/abc123xyz.
3. No teu cron job no final de uma execução bem sucedida chamas esta URL (HTTP GET ou POST).
4. Se o ping não chegar no tempo esperado (+ período de grace), a monitorização alerta-te.

Exemplo prático: bash cron

# /etc/crontab
0 3 * * * www-data /usr/local/bin/backup.sh && curl -fsS -m 10 \
  https://epulz.io/heartbeat/abc123xyz > /dev/null

A chave é o && - o heartbeat é enviado apenas se backup.sh terminar com exit code 0. Se o script falhar, o ping não vem, e dentro de uma hora recebes um alerta.

Dica: Para cobertura mais minuciosa adiciona também um heartbeat "start":

curl -fsS -m 10 https://epulz.io/heartbeat/abc123xyz/start > /dev/null
/usr/local/bin/backup.sh
EXIT=$?
curl -fsS -m 10 "https://epulz.io/heartbeat/abc123xyz?exit=$EXIT" > /dev/null

A monitorização então distingue "começou e não terminou" (script congelou) de "não começou de todo" (o cron job não correu).

Python: requests + try/except

import os, requests
HEARTBEAT_URL = os.environ["HEARTBEAT_URL"]

def sync_data():
    # a tua lógica
    pass

try:
    sync_data()
    requests.get(HEARTBEAT_URL, timeout=10)
except Exception as e:
    # O heartbeat não é enviado - a monitorização vai alertar-te
    raise

Node.js: async / await

const HEARTBEAT_URL = process.env.HEARTBEAT_URL;

async function nightlyJob() {
  await processInvoices();
  await fetch(HEARTBEAT_URL, { signal: AbortSignal.timeout(10000) });
}

nightlyJob().catch(err => {
  console.error(err);
  process.exit(1);
});

Período de grace: quanto tempo dar antes do alerta

O monitor heartbeat precisa de tolerância - o cron por vezes corre mais que o habitual, a rede tem latência, a sync NTP pode estar levemente deslocada. O período de grace é o tempo após o intervalo esperado durante o qual a monitorização ainda espera.

Valores práticos:

• Hourly cron: intervalo 60 min + grace 10 min
• Daily backup (em média 20 min): intervalo 1440 min + grace 60 min
• Weekly report: intervalo 10080 min + grace 360 min (6 h)

Grace demasiado apertado = alertas falso-positivos. Demasiado largo = aviso atrasado quando realmente cai.

Onde o padrão heartbeat ajuda mais

• Backups noturnos de DB
• Sincronização com APIs externos (CRM, accounting, payment)
• Cálculos de relatórios
• Tarefas de cleanup (apagar sessões antigas, logs, ficheiros temporários)
• Ciclo de healthcheck de workers de longa duração
• Emails programados, newsletters, faturação

Conclusão

As tarefas em background são frequentemente mais críticas que o próprio web, mas permanecem ponto cego da monitorização. O padrão heartbeat exige 5 minutos de implementação (adicionar curl no fim da linha cron) e proporciona a mesma tranquilidade que a monitorização uptime para o frontend.

Começa a monitorizar cron jobs

O ePulz.io suporta heartbeat checks com período de grace configurável. 7 dias grátis.

Iniciar monitorização →