Surveillance de tâches cron avec Healthchecks.io : une notification push sur votre téléphone quand une tâche échoue ou ne se lance pas

Une tâche cron peut tomber en panne de deux façons. Elle peut s’exécuter et échouer : pg_dump ne parvient pas à joindre la base de données, le disque est plein. Ou elle peut ne plus s’exécuter du tout : une ligne de crontab est supprimée, le serveur est reconstruit sans elle, le démon cron est arrêté. Le premier cas laisse une erreur quelque part. Le second ne laisse rien, et vous le découvrez le jour où vous avez besoin de la sauvegarde de la veille.
Une alerte qui attend que la tâche dise « j’ai échoué » n’entend jamais une tâche qui n’a pas démarré. Pour détecter ce cas, il faut le montage inverse : la tâche signale sa fin à chaque exécution, et quelque chose d’autre déclenche l’alarme quand ce signalement n’arrive pas.
Ce guide met cela en place avec Healthchecks.io, le moniteur cron open source, et envoie ses alertes sur votre téléphone avec Pocket Alert. Les échecs arrivent en mode bruyant, les rétablissements en mode discret. Tout ce qui suit a été testé avec l’image Docker Healthchecks v5.0.3 auto-hébergée, et fonctionne de la même façon sur le service hébergé.
Ce dont vous avez besoin
- Un compte Healthchecks sur healthchecks.io (l’offre gratuite Hobbyist surveille 20 tâches), ou votre propre instance à partir de l’image Docker
healthchecks/healthchecks. - L’application Pocket Alert sur votre iPhone ou Android et une clé API issue de Clés API. L’offre gratuite suffit pour commencer.
curlsur la machine qui exécute les tâches cron.
Le dead man's switch
Healthchecks appelle cela la surveillance par battement de cœur, une forme de dead man's switch. Chaque tâche obtient un check doté d’une URL de ping unique, que la tâche appelle à la fin de son exécution. Si la requête suivante n’arrive pas à temps, le check passe en down et les alertes partent.
Deux réglages déterminent « à temps » :
- Période : la fréquence à laquelle vous attendez un ping, toutes les heures, tous les jours.
- Délai de tolérance : le temps que Healthchecks attend après l’heure prévue avant de considérer le check comme down. Réglez-le plus long que la durée habituelle de la tâche, avec une marge.
Pour une tâche cron, choisissez plutôt le type de planification Cron et collez l’expression de votre crontab, ainsi que le fuseau horaire du serveur. Healthchecks attend alors des pings aux bons moments de la journée, et pas seulement à intervalles réguliers. L’éditeur d’expressions cron détaille la signification d’une expression.
Lors de notre test, un check avec la planification */2 * * * * et un délai de tolérance d’une minute a reçu un ping à 16:09:13. Rien n’a été reçu à 16:10, et le check est passé en down à 16:11:00, exactement une période de tolérance plus tard.
L’URL de ping existe en plusieurs variantes :
| Requête | Signification |
|---|---|
https://hc-ping.com/<uuid> | Succès. La tâche s’est terminée. |
https://hc-ping.com/<uuid>/start | La tâche a démarré. Healthchecks attend désormais un succès dans le délai de tolérance et enregistre la durée d’exécution. |
https://hc-ping.com/<uuid>/fail | La tâche a échoué. Le check passe immédiatement en down. |
https://hc-ping.com/<uuid>/<0-255> | Un code de sortie. 0 compte comme un succès, toute autre valeur comme un échec. |
Sur une instance auto-hébergée, la base est votre propre domaine suivi de /ping/, par exemple https://hc.example.com/ping/<uuid>.
Brancher la tâche cron
Créez un check, copiez son URL de ping et modifiez la ligne de crontab. Nous avons testé cela avec le démon cron sur 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= est une variable de crontab, que le shell développe dans la commande. La ligne fait trois choses :
- Elle envoie
/start, donc une tâche bloquée passe en down une fois le délai de tolérance écoulé. Lors de notre test, un/startsans suite a fait passer le check en down exactement une période de tolérance plus tard. - Elle lance la tâche.
- Elle envoie
$?, le code de sortie de la tâche. Une exécution réussie envoie/0, un échec envoie/2ou la valeur renvoyée par le script, et le check passe immédiatement en down.
Les options de curl évitent que le ping lui-même pose problème :
-m 10limite chaque requête à 10 secondes. Un/startbloqué ne doit pas retenir la tâche.--retry 5relance les délais dépassés et les réponses 408, 429, 500, 502, 503 et 504, avec des délais croissants. Un paquet perdu ne doit pas vous réveiller.-fsSfait échouer curl sur les erreurs HTTP et reste silencieux tant que tout va bien, pour que cron ne vous envoie pas la barre de progression de curl par e-mail.-o /dev/nulljette le corps de la réponse, qui se limite àOK.
Si la tâche est un pipeline comme pg_dump | gzip > dump.gz, son code de sortie est celui de gzip, et non celui de pg_dump. Placez-la dans un script avec set -o pipefail en bash, pour qu’un export échoué ne soit pas signalé comme réussi.
Ou laissez runitor s’en charger
runitor est un petit binaire Go qui enveloppe une commande et gère les pings : /start avant, le code de sortie après, et les 10 000 derniers octets de la sortie de la commande joints au 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 ligne de crontab devient plus courte :
15 3 * * * CHECK_UUID=your-check-uuid /usr/local/bin/runitor -- /usr/local/bin/backup.sh
Pour une instance auto-hébergée, ajoutez HC_API_URL=https://hc.example.com/ping. Nous avons utilisé runitor v1.4.1 de cette façon sous cron : une sauvegarde en échec a fait passer le check en down avec le code de sortie 2, et sa sortie d’erreur apparaissait dans l’alerte.
Envoyer les alertes vers Pocket Alert
Healthchecks se connecte à Pocket Alert via son intégration générique Webhook. Rendez-vous dans Intégrations, trouvez Webhook et cliquez sur Ajouter une intégration. Le formulaire comporte deux sections, « Exécuter quand un check passe en down » et « Exécuter quand un check repasse en up », chacune avec sa propre URL, sa méthode, son corps et ses en-têtes. Cette séparation permet de rendre le « down » bruyant et le « up » discret.
Les deux sections acceptent des variables : $NAME, $NAME_JSON, $STATUS, $NOW, $CODE, $SLUG, $TAGS, $EXITSTATUS, $BODY, $BODY_JSON, $JSON et quelques autres. Pour les corps JSON, attention à la différence : $NAME est inséré tel quel, donc un check nommé Nightly "db" backup casse le JSON, alors que $NAME_JSON est une chaîne JSON complète, guillemets compris. Il en va de même pour $BODY et $BODY_JSON.
Option 1 : directement vers l’API
Dans la section down, choisissez POST et l’URL https://api.pocketalert.app/v1/messages. En-têtes de requête, un par ligne :
Content-Type: application/json
Token: YOUR_API_KEY
Corps de la requête :
{
"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/"}]
}
Dans la section up, la même méthode, la même URL et les mêmes en-têtes, avec un corps plus discret :
{
"title": $NAME_JSON,
"message": "Back up at $NOW",
"level": "low"
}
Cliquez sur Enregistrer l’intégration. Une nouvelle intégration est rattachée à tous les checks existants du projet. Voici ce que Healthchecks a envoyé lorsque notre check de test a échoué :
{
"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/"}]
}
Quelques remarques sur ce corps :
highest prioritaire. Il traverse Concentration et le récapitulatif programmé. Sur une offre payante, passez-le àcritical: une sauvegarde morte vous réveille alors malgré le mode silencieux et Ne pas déranger. Sur l’offre gratuite,criticalest accepté et livré commehigh.lowpour les rétablissements. « Sauvegarde de retour » arrive dans le fil sans son. Vous voulez le savoir, mais pas à 3 h du matin.$EXITSTATUSdistingue l’échec de l’absence. C’est le code de sortie du dernier ping avant l’alerte.2signifie que la tâche s’est exécutée et a renvoyé 2. Un down avec0signifie que la dernière exécution a réussi et que la suivante n’a jamais eu lieu.-1signifie que le dernier ping ne portait aucun code de sortie : une simple URL de succès,/failou/start.- Le bouton ouvre le check dans Healthchecks. Pour une instance auto-hébergée, mettez votre propre domaine dans l’URL. Les boutons d’action sont une fonctionnalité payante : sur l’offre gratuite, ils sont retirés et le message est livré normalement.
Option 2 : un webhook Pocket Alert avec un modèle
La seconde méthode envoie un petit document JSON à un webhook Pocket Alert, qui met en forme la notification push. Son avantage : elle peut inclure la sortie de la tâche.
Ouvrez Webhooks dans la console Pocket Alert, créez-en un nommé Healthchecks et définissez le modèle de message :
%name% is %status% since %time%
%log%
Laissez Priorité par défaut non sélectionnée, car la charge utile porte son propre niveau. Copiez l’URL du webhook, qui ressemble à https://p4a.me/wh/abc123xyz. L’URL est un secret : traitez-la comme un mot de passe.
Dans Healthchecks, créez l’intégration webhook avec cette URL en POST dans les deux sections, l’en-tête Content-Type: application/json et les corps suivants. 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 est le corps du dernier ping, c’est là que runitor place la sortie de la tâche. Lorsque la sauvegarde encapsulée par runitor a échoué lors de notre test, la notification affichait :
Webhook Healthchecks
DB backup (runitor) est down depuis 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 lit le champ level de premier niveau d’une charge utile entrante, donc high et low fonctionnent comme dans l’option 1. Sans runitor, $BODY_JSON est une chaîne vide et la deuxième ligne est vide. L’API ne peut pas faire cela : $BODY_JSON est une chaîne JSON complète, elle ne peut donc former que la totalité du message, et lorsque le ping n’avait pas de corps, ce message est vide et l’API le rejette.
Deux autres différences : le titre de la notification est toujours Webhook <name>, donc le nom du check passe dans le message, et les boutons de webhook se définissent via le champ actions de l’API webhooks, et non dans le formulaire de la console.
Tester
Sur la page Intégrations de Healthchecks, chaque intégration possède un bouton Test!. Il envoie une notification « down » pour un check nommé TEST, qui arrive sous forme de notification push high. Lancez ensuite une tâche qui se termine avec le code 1 et observez l’arrivée de l’alerte réelle.
Sans Healthchecks : un script enveloppe qui notifie en cas d’échec
Si vous ne voulez pas d’un service de plus, un petit script enveloppe couvre le cas le plus courant : une tâche qui se termine par une erreur. Enregistrez-le sous /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"
Et dans la crontab :
POCKETALERT_API_KEY=your-api-key
15 3 * * * /usr/local/bin/cron-alert "nightly backup" /usr/local/bin/backup.sh
Quelques choix délibérés :
--form-stringau lieu du JSON. L’API accepte les données de formulaire multipart, et--form-stringenvoie la sortie telle quelle, guillemets et retours à la ligne compris, sansjqni échappement. Un simple-Ftraiterait une valeur commençant par@ou<comme un fichier.tail -c 2000conserve la fin de la sortie, où se trouve généralement l’erreur.--retry-max-time 30est important. Au-delà de la limite quotidienne de messages, l’API répond429avec unRetry-Aftercorrespondant au nombre de secondes jusqu’à minuit UTC, et l’option--retryde curl le respecte. Lors de notre test, sans cette option, curl attendaitRetry-After: 30000jusqu’à ce que nous l’arrêtions. Avec elle, curl abandonne après une tentative.- Le script conserve le code de sortie et affiche la sortie, donc les journaux cron et
MAILTOfonctionnent comme avant.
Il passe shellcheck, et sous cron sur Debian 13, la sauvegarde en échec est arrivée sous la forme « Cron en échec : sauvegarde nocturne sur » suivi du nom d’hôte, avec l’erreur de pg_dump dans le texte.
Soyez clair sur ce que cela ne peut pas faire. Le script ne s’exécute que si cron l’exécute. Si la ligne de crontab est supprimée, si le démon est arrêté ou si la machine est éteinte, rien n’est envoyé : c’est l’échec silencieux du début de cet article. Une tâche qui se bloque indéfiniment passe aussi inaperçue. Pour ces cas, il faut quelque chose d’extérieur à la machine qui attend un battement de cœur, et c’est à cela que sert Healthchecks. La CLI Pocket Alert peut remplacer l’appel curl si vous le préférez.
Limites honnêtes
- Healthchecks doit être en ligne pour détecter le problème. Sur le service hébergé, c’est leur travail. Si vous l’auto-hébergez sur la même machine que les tâches cron, une machine morte emporte le moniteur avec elle. Hébergez-le ailleurs.
- Le modèle de corps est limité à 1 000 caractères dans Healthchecks. C’est largement suffisant pour les corps ci-dessus, mais pas pour un long message rédigé à la main.
- Les longues sorties sont tronquées dans la notification push. Elle contient environ les 3 premiers Ko du message ; le texte complet se trouve dans l’historique des messages de l’application.
- Chaque alerte est un message. Une tâche instable qui passe en down et en up toutes les quelques minutes envoie une notification à chaque fois, et sur les 50 messages par jour de l’offre gratuite, cela s’accumule. Corrigez la tâche ou augmentez le délai de tolérance.
Si rien n’arrive
- Utilisez d’abord le bouton Test!. Si le test arrive mais pas les vraies alertes, vérifiez que l’intégration est activée pour ce check sur la page du check.
- Consultez la page Intégrations de Healthchecks. Une intégration en échec y est marquée Failed ; survolez-la pour voir la dernière erreur, par exemple
Received status code 401. Un401signifie que l’en-têteTokenest incorrect. Un400indique généralement que le corps n’est pas du JSON valide : vérifiez que vous avez utilisé$NAME_JSONsans guillemets autour, et non"$NAME". - Un nouveau check n’alerte qu’après son premier ping. Jusque-là, il est « new », pas « down ».
- Vérifiez le fuseau horaire des checks cron. Si un check est toujours en avance ou en retard d’une heure, le fuseau horaire du serveur ne correspond pas à celui défini sur le check.
- Regardez dans le fil. Les notifications
lown’émettent aucun son : un rétablissement peut donc sembler ne jamais être arrivé.
FAQ
Dois-je utiliser l’API ou le webhook ?
La voie API place le nom du check dans le titre de la notification et ne nécessite rien de créer dans Pocket Alert. La voie webhook peut inclure la sortie de la tâche : avec runitor, privilégiez donc le webhook.
Puis-je ne recevoir que les alertes « down » ?
Oui. Utilisez un corps low discret pour « up », comme ci-dessus, ou laissez l’URL « up » vide : Healthchecks n’envoie alors rien au rétablissement.
Et les timers systemd ?
Même principe. Healthchecks propose un type de planification OnCalendar qui accepte les mêmes expressions que votre timer. Envoyez /start depuis ExecStartPre, ou encapsulez la commande ExecStart dans runitor.
Où en savoir plus sur les alertes cron ?
La page alertes de tâches cron explique comment envoyer une notification push depuis la tâche elle-même, alertes de sauvegarde traite des outils de sauvegarde, et le guide Proxmox couvre les sauvegardes sur un hyperviseur.
Créez un compte gratuit, ajoutez une seule intégration webhook dans Healthchecks, et que la tâche qui a discrètement cessé de tourner soit celle qui vous réveille.