Voltar para o blog

Monitorar tarefas cron com Healthchecks.io: notificação push no celular quando um job falha ou não roda

Monitorar tarefas cron com Healthchecks.io: notificação push no celular quando um job falha ou não roda

Uma tarefa cron pode quebrar de duas formas. Ela pode rodar e falhar: o pg_dump não consegue acessar o banco, o disco está cheio. Ou pode simplesmente deixar de rodar: uma linha do crontab é apagada, o servidor é recriado sem ela, o daemon do cron morreu. A primeira forma deixa um erro em algum lugar. A segunda não deixa nada, e você só descobre no dia em que precisa do backup de ontem.

Um alerta que espera o job dizer "falhei" nunca ouve um job que não começou. Para pegar esse caso, você precisa da configuração oposta: o job avisa toda vez que termina, e outra coisa dispara o alarme quando o aviso não chega.

Este guia monta isso com o Healthchecks.io, o monitor de cron de código aberto, e envia os alertas para o seu celular com o Pocket Alert. Falhas chegam com alto impacto, recuperações chegam de forma discreta. Tudo abaixo foi testado com a imagem Docker do Healthchecks v5.0.3 auto-hospedada e funciona da mesma forma no serviço hospedado.

O que você precisa

  • Uma conta no healthchecks.io (o plano Hobbyist gratuito monitora 20 jobs), ou sua própria instância a partir da imagem Docker healthchecks/healthchecks.
  • O aplicativo Pocket Alert no seu iPhone ou Android e uma chave de API em Chaves de API. O plano gratuito já basta para começar.
  • curl na máquina que roda as tarefas cron.

O dead man's switch

O Healthchecks chama isso de monitoramento por heartbeat, um tipo de dead man's switch. Cada job recebe uma verificação com uma URL de ping única, que o job requisita quando termina. Se a próxima requisição não chegar a tempo, a verificação fica inativa e os alertas são enviados.

Duas configurações definem o que é "a tempo":

  • Período é com que frequência você espera um ping: a cada hora, todo dia.
  • Tempo de tolerância é quanto o Healthchecks espera depois do horário previsto antes de declarar a verificação inativa. Defina um valor maior que o tempo habitual do job, com uma folga.

Para uma tarefa cron, escolha o tipo de agendamento Cron e cole a expressão do seu crontab, além do fuso horário do servidor. Assim o Healthchecks espera pings nos horários certos do dia, e não apenas em intervalos corretos. O editor de expressões cron explica o que cada expressão significa.

No nosso teste, uma verificação com agendamento */2 * * * * e tolerância de um minuto recebeu um ping às 16:09:13. Nada pingou às 16:10, e a verificação ficou inativa às 16:11:00, exatamente um período de tolerância depois.

A URL de ping tem algumas variantes:

RequisiçãoSignificado
https://hc-ping.com/<uuid>Sucesso. O job terminou.
https://hc-ping.com/<uuid>/startO job começou. O Healthchecks agora espera um sucesso dentro do tempo de tolerância e registra a duração da execução.
https://hc-ping.com/<uuid>/failO job falhou. A verificação fica inativa imediatamente.
https://hc-ping.com/<uuid>/<0-255>Um código de saída. 0 conta como sucesso, qualquer outro valor como falha.

Em uma instância auto-hospedada, a base é o seu próprio domínio mais /ping/, por exemplo https://hc.example.com/ping/<uuid>.

Configure a tarefa cron

Crie uma verificação, copie a URL de ping e altere a linha do crontab. Rodamos isso com o daemon do cron no Debian 13:

PING=https://hc-ping.com/your-check-uuid
15 3 * * * curl -fsS -m 10 --retry 5 -o /dev/null $PING/start; /usr/local/bin/backup.sh; curl -fsS -m 10 --retry 5 -o /dev/null $PING/$?

PING= é uma variável do crontab, que o shell expande no comando. A linha faz três coisas:

  • Envia /start, então um job que trava fica inativo quando o tempo de tolerância acaba. No nosso teste, um /start sem continuação deixou a verificação inativa exatamente um período de tolerância depois.
  • Executa o job.
  • Envia $?, o código de saída do job. Uma execução limpa envia /0, uma falha envia /2 ou o que o script retornou, e a verificação fica inativa imediatamente.

As flags do curl evitam que o ping cause problemas próprios:

  • -m 10 limita cada requisição a 10 segundos. Um /start travado não pode segurar o job.
  • --retry 5 repete timeouts e respostas 408, 429, 500, 502, 503 e 504, com intervalos crescentes. Um pacote perdido não deve acionar um alerta.
  • -fsS faz o curl falhar em erros HTTP e ficar em silêncio, a menos que algo dê errado, para o cron não enviar por e-mail a barra de progresso do curl.
  • -o /dev/null descarta o corpo da resposta, que é apenas OK.

Se o job for um pipeline como pg_dump | gzip > dump.gz, o código de saída é o do gzip, não o do pg_dump. Mova-o para um script com set -o pipefail no bash, para que um dump com falha não seja reportado como sucesso.

Ou deixe o runitor fazer isso

O runitor é um pequeno binário em Go que envolve um comando e cuida dos pings: /start antes, o código de saída depois, e os últimos 10.000 bytes da saída do comando anexados ao ping.

curl -fsSL -o /usr/local/bin/runitor https://github.com/bdd/runitor/releases/download/v1.4.1-build.6/runitor-v1.4.1-build.6-linux-amd64
chmod +x /usr/local/bin/runitor

A linha do crontab fica mais curta:

15 3 * * * CHECK_UUID=your-check-uuid /usr/local/bin/runitor -- /usr/local/bin/backup.sh

Para uma instância auto-hospedada, adicione HC_API_URL=https://hc.example.com/ping. Rodamos o runitor v1.4.1 assim no cron: um backup com falha deixou a verificação inativa com código de saída 2, e a saída de erro apareceu no alerta.

Envie alertas ao Pocket Alert

O Healthchecks se conecta ao Pocket Alert pela integração genérica Webhook. Vá em Integrações, encontre Webhook e clique em Adicionar integração. O formulário tem duas seções, "Executar quando uma verificação ficar inativa" e "Executar quando uma verificação voltar", cada uma com sua própria URL, método, corpo e cabeçalhos. Essa divisão permite que o alerta de "inativa" seja forte e o de "voltou" seja discreto.

As duas seções aceitam marcadores: $NAME, $NAME_JSON, $STATUS, $NOW, $CODE, $SLUG, $TAGS, $EXITSTATUS, $BODY, $BODY_JSON, $JSON e mais alguns. Para corpos JSON, atenção à diferença: $NAME é colado sem tratamento, então uma verificação chamada Nightly "db" backup quebra o JSON, enquanto $NAME_JSON é uma string JSON completa, com aspas incluídas. O mesmo vale para $BODY e $BODY_JSON.

Opção 1: direto para a API

Na seção de inativa, escolha POST e a URL https://api.pocketalert.app/v1/messages. Cabeçalhos da requisição, um por linha:

Content-Type: application/json
Token: YOUR_API_KEY

Corpo da requisição:

{
  "title": $NAME_JSON,
  "message": "DOWN since $NOW. Exit status of the last ping: $EXITSTATUS",
  "level": "high",
  "actions": [{"type": "view", "label": "Open check", "value": "https://healthchecks.io/checks/$CODE/details/"}]
}

Na seção de voltou, o mesmo método, URL e cabeçalhos, e um corpo mais discreto:

{
  "title": $NAME_JSON,
  "message": "Back up at $NOW",
  "level": "low"
}

Clique em Salvar integração. Uma nova integração é vinculada a todas as verificações existentes do projeto. Isto é o que o Healthchecks enviou quando nossa verificação de teste falhou:

{
  "title": "Nightly \"db\" backup",
  "message": "DOWN since 2026-10-31T16:15:01+00:00. Exit status of the last ping: 2",
  "level": "high",
  "actions": [{"type": "view", "label": "Open check", "value": "https://healthchecks.io/checks/a4b72803-3a50-4b81-b33f-88dd2200ffc2/details/"}]
}

Algumas observações sobre este corpo:

  • high é urgente. Ele fura o Foco e o resumo programado. Em um plano pago, troque para critical e um job de backup parado acorda você mesmo com o modo silencioso e o Não perturbe ativados. No plano gratuito, critical é aceito e entregue como high.
  • low para recuperações. "Back up" aparece no feed sem som. Você quer saber, mas não às 3 da manhã.
  • $EXITSTATUS diferencia falha de ausência. É o código de saída do último ping antes do alerta. 2 significa que o job rodou e retornou 2. Uma notificação de inatividade com 0 significa que a última execução teve sucesso e a seguinte nunca aconteceu. -1 significa que o último ping não trouxe código de saída: uma URL de sucesso simples, /fail ou /start.
  • O botão abre a verificação no Healthchecks. Em uma instância auto-hospedada, coloque o seu próprio domínio na URL. Botões de ação são um recurso pago; no plano gratuito são removidos e a mensagem é entregue normalmente.

Opção 2: um webhook do Pocket Alert com template

A segunda forma envia um pequeno documento JSON para um webhook do Pocket Alert, que formata a notificação push. A vantagem: ele pode incluir a saída do job.

Abra Webhooks no console do Pocket Alert, crie um chamado Healthchecks e defina o template da mensagem:

%name% is %status% since %time%
%log%

Deixe Prioridade padrão sem seleção, porque o payload traz o próprio nível. Copie a URL do webhook, que tem o formato https://p4a.me/wh/abc123xyz. A URL é o segredo, então trate-a como uma senha.

No Healthchecks, crie a integração de webhook com essa URL como POST nas duas seções, o cabeçalho Content-Type: application/json e estes corpos. Inativa:

{"name": $NAME_JSON, "status": "$STATUS", "time": "$NOW", "code": "$CODE", "log": $BODY_JSON, "level": "high"}

Voltou:

{"name": $NAME_JSON, "status": "$STATUS", "time": "$NOW", "code": "$CODE", "log": $BODY_JSON, "level": "low"}

$BODY_JSON é o corpo do último ping, que é onde o runitor coloca a saída do job. Quando o backup envolvido pelo runitor falhou no nosso teste, a notificação mostrou:

Webhook Healthchecks
DB backup (runitor) is down since 2026-10-31T16:15:02+00:00
dumping appdb
pg_dump: error: connection to server on socket failed: No such file or directory

[runitor] exit status 2

O Pocket Alert lê o campo level de primeiro nível de um payload recebido, então high e low funcionam como na Opção 1. Sem o runitor, $BODY_JSON é uma string vazia e a segunda linha fica em branco. A API não consegue fazer isso: $BODY_JSON é uma string JSON completa, então só pode ser a message inteira, e quando o ping não tinha corpo essa mensagem fica vazia e a API a rejeita.

Mais duas diferenças: o título da notificação é sempre Webhook <name>, então o nome da verificação vai para a mensagem, e os botões de webhook são definidos pelo campo actions da API de webhooks, não pelo formulário do console.

Teste

Na página Integrações do Healthchecks, cada integração tem um botão Test!. Ele envia uma notificação de "inativa" para uma verificação chamada TEST, que chega como uma notificação push high. Depois, rode um job que termine com 1 e veja o alerta real chegar.

Sem o Healthchecks: um wrapper que envia push na falha

Se você não quer mais um serviço, um pequeno wrapper cobre o caso mais comum: um job que termina com erro. Salve-o como /usr/local/bin/cron-alert:

#!/bin/sh
# Usage: cron-alert <job name> <command> [args...]
name="$1"
shift

log=$(mktemp)
"$@" >"$log" 2>&1
status=$?

if [ "$status" -ne 0 ]; then
  curl -fsS -m 10 --retry 3 --retry-max-time 30 -o /dev/null \
    -H "Token: $POCKETALERT_API_KEY" \
    --form-string "title=Cron failed: $name on $(hostname)" \
    --form-string "message=Exit status $status. $(tail -c 2000 "$log")" \
    --form-string "level=high" \
    "${POCKETALERT_API_URL:-https://api.pocketalert.app/v1/messages}"
fi

cat "$log"
rm -f "$log"
exit "$status"

E no crontab:

POCKETALERT_API_KEY=your-api-key
15 3 * * * /usr/local/bin/cron-alert "nightly backup" /usr/local/bin/backup.sh

Algumas escolhas deliberadas:

  • --form-string em vez de JSON. A API aceita dados de formulário multipart, e --form-string envia a saída como está, com aspas e quebras de linha, sem jq nem escape. O -F simples trataria um valor começando com @ ou < como um arquivo.
  • tail -c 2000 mantém o fim da saída, onde geralmente está o erro.
  • --retry-max-time 30 é importante. Acima do limite diário de mensagens, a API responde 429 com um Retry-After com os segundos até a meia-noite UTC, e o --retry do curl respeita isso. No nosso teste, sem essa flag, o curl ficou esperando Retry-After: 30000 até o matarmos. Com ela, o curl desiste após uma tentativa.
  • O wrapper preserva o código de saída e imprime a saída, então os logs do cron e o MAILTO continuam funcionando como antes.

Ele passa no shellcheck, e rodando no cron do Debian 13 o backup com falha chegou como "Cron failed: nightly backup on" seguido do hostname, com o erro do pg_dump no texto.

Seja claro sobre o que isso não faz. O wrapper só roda quando o cron o executa. Se a linha do crontab for apagada, o daemon cair ou a máquina estiver desligada, nada é enviado: é a falha silenciosa do início deste artigo. Um job que trava para sempre também passa despercebido. Para esses casos você precisa de algo fora da máquina esperando um heartbeat, que é para isso que serve o Healthchecks. A CLI do Pocket Alert pode substituir a chamada ao curl, se você preferir.

Limites honestos

  • O Healthchecks precisa estar no ar para perceber algo. No serviço hospedado, isso é responsabilidade deles. Se você auto-hospedar na mesma máquina das tarefas cron, uma máquina caída derruba o monitor junto. Rode-o em outro lugar.
  • O template do corpo é limitado a 1.000 caracteres no Healthchecks. Isso basta para os corpos acima, mas não para uma mensagem longa escrita à mão.
  • Saídas longas são cortadas na notificação push. A notificação carrega cerca de 3 KB do início da mensagem; o texto completo fica no histórico de mensagens do aplicativo.
  • Cada alerta é uma mensagem. Um job instável que cai e volta a cada poucos minutos envia uma notificação a cada vez, e no limite de 50 mensagens por dia do plano gratuito isso soma rápido. Corrija o job ou aumente o tempo de tolerância.

Se nada chegar

  • Use primeiro o botão Test!. Se o teste chegar, mas os alertas reais não, verifique se a integração está habilitada para essa verificação, na página da própria verificação.
  • Veja a página Integrações no Healthchecks. Uma integração com falha aparece marcada como Failed; passe o mouse sobre ela para ver o último erro, como Received status code 401. Um 401 significa que o cabeçalho Token está errado. Um 400 geralmente significa que o corpo não é um JSON válido: confira se você usou $NAME_JSON sem aspas ao redor, e não "$NAME".
  • Uma verificação nova não alerta até o primeiro ping. Até lá ela está "nova", não "inativa".
  • Confira o fuso horário das verificações de cron. Se uma verificação sempre aparece uma hora adiantada ou atrasada, o fuso horário do servidor não bate com o da verificação.
  • Olhe o feed. Notificações low não fazem som, então uma recuperação pode parecer que nunca chegou.

FAQ

Devo usar a rota da API ou a do webhook?

A rota da API coloca o nome da verificação no título da notificação e não precisa de nada criado no Pocket Alert. A rota do webhook pode incluir a saída do job, então, com o runitor, escolha o webhook.

Posso receber só os alertas de "inativa"?

Sim. Use um corpo low discreto para "voltou", como acima, ou deixe a URL de "voltou" vazia e o Healthchecks não envia nada na recuperação.

E os timers do systemd?

A ideia é a mesma. O Healthchecks tem um tipo de agendamento OnCalendar que aceita as mesmas expressões do seu timer. Envie /start a partir de ExecStartPre, ou envolva o comando ExecStart com o runitor.

Onde posso ler mais sobre alertas de cron?

A página alertas de tarefas cron explica como enviar uma notificação push a partir do próprio job, os alertas de backup cobrem ferramentas de backup, e o guia do Proxmox trata de backups em um hypervisor.

Crie uma conta gratuita, adicione uma integração de webhook no Healthchecks e deixe que o job que parou de rodar em silêncio seja quem acorda você.

Compartilhe este artigo