Torna al blog

Monitoraggio cron job con Healthchecks.io: una notifica push sul telefono quando un job fallisce o non parte

Monitoraggio cron job con Healthchecks.io: una notifica push sul telefono quando un job fallisce o non parte

Un cron job può rompersi in due modi. Può partire e fallire: pg_dump non riesce a raggiungere il database, il disco è pieno. Oppure può smettere del tutto di girare: una riga del crontab viene cancellata, il server viene ricostruito senza di essa, il demone cron è morto. Il primo tipo lascia un errore da qualche parte. Il secondo non lascia niente, e te ne accorgi il giorno in cui ti serve il backup di ieri sera.

Un sistema di alert che aspetta che il job dica "ho fallito" non sente mai un job che non è partito. Per intercettarlo serve il setup opposto: il job segnala la sua esecuzione ogni volta che termina, e qualcos'altro fa scattare l'allarme quando la segnalazione non arriva.

Questa guida costruisce proprio questo con Healthchecks.io, il monitor open source per cron, e invia i suoi avvisi al telefono con Pocket Alert. I fallimenti arrivano in modo evidente, i ripristini in modo discreto. Tutto ciò che segue è stato testato con l'immagine Docker self-hosted di Healthchecks v5.0.3 e funziona allo stesso modo sul servizio cloud.

Cosa ti serve

  • Un account Healthchecks su healthchecks.io (il piano gratuito Hobbyist monitora 20 job), oppure una tua istanza dall'immagine Docker healthchecks/healthchecks.
  • L'app Pocket Alert sul tuo iPhone o Android e una chiave API da Chiavi API. Il piano gratuito basta per iniziare.
  • curl sulla macchina che esegue i cron job.

Il dead man's switch

Healthchecks chiama questo meccanismo monitoraggio heartbeat, una sorta di dead man's switch. Ogni job ottiene un check con un URL di ping unico, che il job richiama quando termina. Se la richiesta successiva non arriva in tempo, il check passa a down e partono gli avvisi.

Due impostazioni decidono cosa significa "in tempo":

  • Period è la frequenza con cui ti aspetti un ping: ogni ora, ogni giorno.
  • Grace time è quanto Healthchecks aspetta oltre l'orario previsto prima di dichiarare il check down. Impostalo più lungo della durata abituale del job, più un margine.

Per un cron job, scegli invece il tipo di pianificazione Cron e incolla l'espressione dal crontab, insieme al fuso orario del server. Healthchecks si aspetta così i ping agli orari giusti della giornata, non solo a intervalli regolari. L'editor di espressioni cron spiega il significato di ogni espressione.

Nel nostro test, un check con pianificazione */2 * * * * e grace time di un minuto ha ricevuto un ping alle 16:09:13. Nessun ping alle 16:10, e il check è passato a down alle 16:11:00, esattamente un grace period dopo.

L'URL di ping ha alcune varianti:

RichiestaSignificato
https://hc-ping.com/<uuid>Successo. Il job è terminato.
https://hc-ping.com/<uuid>/startIl job è partito. Healthchecks ora si aspetta un successo entro il grace time e registra la durata dell'esecuzione.
https://hc-ping.com/<uuid>/failIl job è fallito. Il check passa subito a down.
https://hc-ping.com/<uuid>/<0-255>Un codice di uscita. 0 conta come successo, qualsiasi altro valore come fallimento.

Su un'istanza self-hosted la base è il tuo dominio seguito da /ping/, per esempio https://hc.example.com/ping/<uuid>.

Collega il cron job

Crea un check, copia il suo URL di ping e modifica la riga del crontab. Abbiamo eseguito tutto sotto il demone cron su 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= è una variabile del crontab, che la shell espande nel comando. La riga fa tre cose:

  • Invia /start, così un job bloccato passa a down allo scadere del grace time. Nel nostro test, un /start senza seguito ha portato il check a down esattamente un grace period dopo.
  • Esegue il job.
  • Invia $?, il codice di uscita del job. Un'esecuzione pulita invia /0, una fallita invia /2 o qualunque valore abbia restituito lo script, e il check passa subito a down.

I flag di curl evitano che il ping crei problemi a sua volta:

  • -m 10 limita ogni richiesta a 10 secondi. Un /start bloccato non deve trattenere il job.
  • --retry 5 ritenta in caso di timeout e risposte 408, 429, 500, 502, 503 e 504, con ritardi crescenti. Un pacchetto perso non deve farti svegliare.
  • -fsS fa fallire curl sugli errori HTTP e lo tiene silenzioso finché non succede qualcosa, così cron non ti spedisce per mail la barra di avanzamento di curl.
  • -o /dev/null scarta il corpo della risposta, che è solo OK.

Se il job è una pipeline come pg_dump | gzip > dump.gz, il suo codice di uscita è quello di gzip, non di pg_dump. Spostala in uno script con set -o pipefail in bash, così un dump fallito non risulta come successo.

Oppure lascia fare a runitor

runitor è un piccolo binario Go che avvolge un comando e gestisce i ping: /start prima, il codice di uscita dopo, e gli ultimi 10.000 byte dell'output del comando allegati al 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

La riga del crontab diventa più corta:

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

Per un'istanza self-hosted aggiungi HC_API_URL=https://hc.example.com/ping. Abbiamo eseguito runitor v1.4.1 in questo modo sotto cron: un backup fallito ha portato il check a down con codice di uscita 2, e il suo output di errore è comparso nell'avviso.

Invia gli avvisi a Pocket Alert

Healthchecks si collega a Pocket Alert tramite la sua integrazione generica Webhook. Vai su Integrations, trova Webhook e clicca Add Integration. Il form ha due sezioni, "Execute when a check goes down" ed "Execute when a check goes up", ognuna con il proprio URL, metodo, body e header. Questa separazione permette di rendere "down" evidente e "up" discreto.

Entrambe le sezioni accettano dei segnaposto: $NAME, $NAME_JSON, $STATUS, $NOW, $CODE, $SLUG, $TAGS, $EXITSTATUS, $BODY, $BODY_JSON, $JSON e alcuni altri. Per i body JSON fai attenzione alla differenza: $NAME viene incollato così com'è, quindi un check chiamato Nightly "db" backup rompe il JSON, mentre $NAME_JSON è una stringa JSON completa, virgolette incluse. Vale lo stesso per $BODY e $BODY_JSON.

Opzione 1: direttamente all'API

Nella sezione down scegli POST e l'URL https://api.pocketalert.app/v1/messages. Header della richiesta, uno per riga:

Content-Type: application/json
Token: YOUR_API_KEY

Body della richiesta:

{
  "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/"}]
}

Nella sezione up lo stesso metodo, URL e header, e un body più discreto:

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

Clicca Save Integration. Una nuova integrazione viene collegata a tutti i check esistenti del progetto. Questo è ciò che Healthchecks ha inviato quando il nostro check di test è fallito:

{
  "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/"}]
}

Alcune note su questo body:

  • high è per ciò che è urgente. Passa attraverso Full immersion e il riepilogo programmato. Con un piano a pagamento, cambialo in critical e un job di backup fermo ti sveglia anche con l'interruttore silenzioso e Non disturbare. Con il piano gratuito critical è accettato e consegnato come high.
  • low per i ripristini. "Back up" arriva nel feed senza suono. Vuoi saperlo, ma non alle 3 di notte.
  • $EXITSTATUS distingue il fallimento dall'assenza. È il codice di uscita dell'ultimo ping prima dell'avviso. 2 significa che il job è girato e ha restituito 2. Un down con 0 significa che l'ultima esecuzione è riuscita e quella successiva non è mai partita. -1 significa che l'ultimo ping non aveva un codice di uscita: un semplice URL di successo, /fail o /start.
  • Il pulsante apre il check in Healthchecks. Per un'istanza self-hosted, inserisci nell'URL il tuo dominio. I pulsanti di azione sono una funzione a pagamento: nel piano gratuito vengono rimossi e il messaggio viene comunque consegnato normalmente.

Opzione 2: un webhook Pocket Alert con un template

Il secondo modo invia un piccolo documento JSON a un webhook Pocket Alert, che formatta la notifica push. Il suo vantaggio: può includere l'output del job.

Apri Webhooks nella console di Pocket Alert, crea un webhook chiamato Healthchecks e imposta il template del messaggio:

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

Lascia Default priority non selezionata, perché il payload porta il proprio livello. Copia l'URL del webhook, che ha la forma https://p4a.me/wh/abc123xyz. L'URL è il segreto, quindi trattalo come una password.

In Healthchecks crea l'integrazione webhook con quell'URL come POST in entrambe le sezioni, l'header Content-Type: application/json e questi body. Down:

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

Up:

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

$BODY_JSON è il body dell'ultimo ping, dove runitor inserisce l'output del job. Quando il backup avvolto da runitor è fallito nel nostro test, la notifica diceva:

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

Pocket Alert legge il campo level di primo livello di un payload in arrivo, quindi high e low funzionano come nell'Opzione 1. Senza runitor, $BODY_JSON è una stringa vuota e la seconda riga resta bianca. L'API non può fare questo: $BODY_JSON è una stringa JSON completa, quindi può essere solo l'intero message, e quando il ping non aveva body quel messaggio è vuoto e l'API lo rifiuta.

Altre due differenze: il titolo della notifica è sempre Webhook <name>, quindi il nome del check va nel messaggio, e i pulsanti del webhook si impostano tramite il campo actions dell'API dei webhook, non dal form della console.

Prova

Nella pagina Integrations di Healthchecks, ogni integrazione ha un pulsante Test!. Invia una notifica "down" per un check chiamato TEST, che arriva come notifica push high. Poi esegui un job che termina con 1 e osserva arrivare l'avviso reale.

Senza Healthchecks: un wrapper che invia una push in caso di errore

Se non vuoi un altro servizio, un breve wrapper copre il caso più comune, cioè un job che termina con errore. Salvalo come /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 nel crontab:

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

Alcune scelte deliberate:

  • --form-string invece di JSON. L'API accetta dati multipart form, e --form-string invia l'output così com'è, virgolette e a capo inclusi, senza jq né escaping. Con -F puro, un valore che inizia con @ o < verrebbe trattato come file.
  • tail -c 2000 mantiene la fine dell'output, dove di solito si trova l'errore.
  • --retry-max-time 30 è importante. Oltre il limite giornaliero di messaggi, l'API risponde 429 con un Retry-After pari ai secondi fino a mezzanotte UTC, e --retry di curl lo rispetta. Nel nostro test, senza questo flag curl restava in attesa di Retry-After: 30000 finché non lo abbiamo interrotto. Con il flag, curl si arrende dopo un tentativo.
  • Il wrapper conserva il codice di uscita e stampa l'output, quindi i log di cron e MAILTO continuano a funzionare come prima.

Passa shellcheck, e sotto cron su Debian 13 il backup fallito è arrivato come "Cron failed: nightly backup on" seguito dal nome host, con l'errore di pg_dump nel testo.

Sii chiaro su ciò che questo non può fare. Il wrapper gira solo quando cron lo esegue. Se la riga del crontab viene cancellata, il demone è giù o la macchina è spenta, non parte nulla: è il fallimento silenzioso da cui siamo partiti. Anche un job che si blocca per sempre passa inosservato. Per questi casi serve qualcosa fuori dalla macchina che aspetti un heartbeat, ed è a questo che serve Healthchecks. La CLI di Pocket Alert può sostituire la chiamata curl se preferisci.

Limiti onesti

  • Healthchecks deve essere raggiungibile per accorgersi di un problema. Sul servizio cloud se ne occupa il fornitore. Se lo self-hosti sulla stessa macchina dei cron job, una macchina morta porta giù anche il monitor. Eseguilo altrove.
  • Il template del body è limitato a 1.000 caratteri in Healthchecks. Sono abbastanza per i body qui sopra, ma non per un messaggio lungo scritto a mano.
  • L'output lungo viene tagliato nella push. La push contiene circa i primi 3 KB del messaggio; il testo completo è nella cronologia dei messaggi nell'app.
  • Ogni avviso è un messaggio. Un job instabile che va giù e su ogni pochi minuti invia una push ogni volta, e con i 50 messaggi al giorno del piano gratuito il conto sale in fretta. Correggi il job oppure aumenta il grace time.

Se non arriva nulla

  • Usa prima il pulsante Test!. Se il test arriva ma gli avvisi reali no, controlla che l'integrazione sia abilitata per quel check nella sua pagina.
  • Guarda la pagina Integrations di Healthchecks. Un'integrazione in errore è segnata come Failed; passa sopra per vedere l'ultimo errore, per esempio Received status code 401. Un 401 significa che l'header Token è sbagliato. Un 400 di solito indica un body JSON non valido: verifica di aver usato $NAME_JSON senza virgolette attorno, e non "$NAME".
  • Un check nuovo non avvisa fino al primo ping. Fino ad allora è "new", non "down".
  • Controlla il fuso orario dei check cron. Se un check è sempre un'ora in anticipo o in ritardo, il fuso orario del server non corrisponde a quello impostato nel check.
  • Controlla il feed. Le push low non fanno suono, quindi un ripristino può sembrare mai arrivato.

FAQ

Devo usare la via API o la via webhook?

La via API mette il nome del check nel titolo della push e non richiede nulla da creare in Pocket Alert. La via webhook può includere l'output del job, quindi con runitor scegli il webhook.

Posso ricevere solo gli avvisi "down"?

Sì. Usa un body low discreto per "up", come sopra, oppure lascia vuoto l'URL "up" e Healthchecks non invia nulla al ripristino.

E i timer systemd?

Stessa idea. Healthchecks ha un tipo di pianificazione OnCalendar che accetta le stesse espressioni del tuo timer. Invia /start da ExecStartPre, oppure avvolgi il comando ExecStart con runitor.

Dove posso leggere di più sugli avvisi cron?

La pagina avvisi cron job spiega come inviare una push dal job stesso, avvisi di backup copre gli strumenti di backup, e la guida Proxmox tratta i backup su un hypervisor.

Crea un account gratuito, aggiungi un'integrazione webhook in Healthchecks e lascia che sia il job che ha smesso in silenzio di girare a svegliarti.

Condividi questo articolo