Heartbeats: surveillance des tâches planifiées

Un heartbeat veille sur une tâche planifiée : un cron, une sauvegarde nocturne, le nettoyage d'un worker, une génération de rapport. Le principe est celui de l'homme mort, au lieu que Quiet Guard demande à votre tâche si elle a tourné, c'est votre tâche qui prévient Quiet Guard à chaque exécution (un « ping »). Quand les pings s'arrêtent, vous êtes alerté.

Le problème que ça résout

Le suivi d'exceptions attrape le code qui échoue bruyamment : quelque chose lève une exception, vous recevez un rapport. Mais les pannes les plus sournoises sont silencieuses :

• l'entrée cron a été perdue lors d'une migration de serveur,
• le scheduler est mal configuré (schedule:run n'est plus invoqué),
• la tâche plante si tôt qu'aucun gestionnaire d'exception ne la voit,
• quelqu'un a désactivé le job « temporairement » il y a trois mois.

Dans tous ces cas, rien ne lève d'exception, donc rien n'est rapporté. Votre sauvegarde nocturne cesse simplement d'exister, et vous le découvrez le jour où vous en avez besoin. Le heartbeat inverse la logique : le silence devient lui-même l'alerte.

Démarrage rapide

Le câblage recommandé est la macro du scheduler, chaînée directement sur la tâche dans routes/console.php :

Schedule::command('backup:run')->daily()->monitorHeartbeat('nightly-backup');

La macro ne pingue que si la tâche réussit, une tâche qui plante reste silencieuse et déclenche donc l'alerte de retard. Vous pouvez aussi pinger manuellement depuis n'importe quel code :

php artisan monitor:heartbeat nightly-backup

ou en HTTP (toute stack, pas seulement Laravel) :

curl -X POST https://votre-monitor.example/api/v1/heartbeats/nightly-backup \
  -H "Authorization: Bearer <clé API du projet>"

Enregistrement et armement

• Le premier ping enregistre automatiquement le heartbeat sur le projet. À ce stade il est non armé : les pings sont enregistrés, rien n'alerte jamais. C'est voulu: on branche le ping d'abord, on décide ensuite de ce que « en retard » veut dire.
• L'armement se fait dans le tableau de bord : ouvrez l'onglet Heartbeats du projet, modifiez le heartbeat et définissez sa période attendue (la fréquence à laquelle la tâche doit pinger, en minutes) plus une tolérance (retard supplémentaire accepté: un scheduler tombe rarement à la seconde exacte).
• Un heartbeat sans période attendue reste un journal passif de pings, à jamais inoffensif.

Statuts

Chaque minute, le serveur vérifie chaque heartbeat armé : passé dernier ping + période + tolérance, il bascule en retard et déclenche une alerte par panne via les canaux de notification du projet abonnés à l'événement heartbeat.overdue (e-mail, Slack ou webhook, voir Alertes). La protection anti-tempête s'applique.

Le rétablissement est silencieux par conception : le ping réussi suivant repasse le heartbeat en sain, sans notification. L'alerte vous a dit que la tâche est bloquée ; le tableau de bord montre qu'elle est repartie.

Choisir période et tolérance

• Période = le planning de la tâche. Quotidienne → 1440. Horaire → 60.
• Tolérance = le retard normal pour cette tâche. Une sauvegarde qui prend 5 à 40 minutes mérite une tolérance généreuse (60 par exemple) ; une tâche courte peut garder les 5 par défaut.
• Dans le doute, voyez large. Un faux « en retard » à 3 h du matin apprend à ignorer le canal: la seule chose qu'une alerte ne doit jamais faire.

Limites et détails

• Les slugs sont normalisés en minuscules-et-tirets (nightly-backup) ; créez-les dans l'interface avec le même alphabet, ou laissez le premier ping les créer.
• Un projet contient au plus 200 heartbeats: une clé API fuitée ne peut pas inonder la table.
• Les pings s'authentifient avec la clé API du projet, comme tout appel d'ingestion (référence API).
• Les heartbeats en retard remontent sur la vue d'ensemble du projet (stats santé) et comptent comme activité dans le résumé hebdomadaire.