Heartbeat (tâches cron)

Présentation

Un monitor heartbeat (type push) fonctionne à l’inverse des autres checks : ce n’est pas OKStatus qui appelle votre service, c’est votre tâche qui appelle OKStatus à chaque exécution. Si aucun ping n’arrive à temps, le monitor passe en panne et vous êtes alerté.

Il convient à tout ce qui tourne à heure fixe sans URL à interroger : tâches cron, sauvegardes, workers de file d’attente, imports nocturnes, renouvellements de certificats.

En créer un

curl -X POST https://api.okstatus.eu/api/v1/monitors \
  -H "Authorization: Bearer $OKSTATUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Sauvegarde nocturne", "type": "push", "url": "sauvegarde-nocturne", "interval": 86400, "gracePeriod": 3600 }'

Pour un heartbeat, url n’est qu’une étiquette : rien n’est appelé.
interval est la fréquence de la tâche, en secondes.
gracePeriod est le délai supplémentaire accordé avant la panne. Sans lui, il vaut interval.

La réponse porte le pushUrl du monitor :

{
  "data": {
    "id": "…",
    "type": "push",
    "pushToken": "…",
    "pushUrl": "https://backend.okstatus.eu/push/…"
  }
}

Le même pushUrl revient à chaque lecture du monitor avec une clé Complète. Une clé Lecture seule, et un membre au rôle Lecteur, voient le monitor sans son jeton ni son URL. Avec Terraform, construisez l’URL à partir de l’attribut push_token :

output "backup_ping_url" {
  value     = "https://backend.okstatus.eu/push/${okstatus_monitor.backup.push_token}"
  sensitive = true
}

Envoyer un ping

Appelez l’URL à la fin de chaque exécution réussie. POST, GET et HEAD comptent tous comme un ping up :

curl -fsS -m 10 --retry 3 -X POST https://backend.okstatus.eu/push/<token>

Une ligne de crontab qui ne pinge que si la tâche réussit :

0 3 * * * /usr/local/bin/backup.sh && curl -fsS -m 10 --retry 3 -X POST https://backend.okstatus.eu/push/<token> > /dev/null

Pour signaler un échec ou envoyer un message, utilisez POST avec un corps (ci-dessous) : un GET est toujours un ping up. Les aperçus de liens des messageries appellent les URL en GET, une raison de plus pour ne pas coller l’URL dans une conversation.

Signaler un échec ou une durée

Le corps est facultatif. S’il est présent, c’est du JSON :

Champ	Type	Description
`status`	chaîne	`up` (par défaut) ou `down` : signale un échec tout de suite, sans attendre
`msg`	chaîne	Jusqu’à 2 000 caractères, gardés avec le check et affichés dans le tableau de bord et les alertes
`ping`	entier	Durée de la tâche, en millisecondes (0 à 60 000)

if ! /usr/local/bin/backup.sh; then
  curl -fsS -m 10 -X POST https://backend.okstatus.eu/push/<token> \
    -H "Content-Type: application/json" \
    -d '{ "status": "down", "msg": "backup.sh a échoué" }'
fi

Un corps vide est un ping up. Un corps qui n’est pas du JSON valide, ou dont les champs ne correspondent pas au tableau, est refusé avec 400 et rien n’est enregistré : une faute comme "status": "failed" ne peut pas passer pour un succès.

Quand le monitor passe en panne

Le monitor est en panne quand aucun ping n’est arrivé depuis interval + gracePeriod secondes après le précédent. OKStatus vérifie toutes les 30 secondes.

Avant le premier ping, le monitor n’a pas d’état et ne passe jamais en panne : envoyez un ping en mettant la tâche en place.
Un ping après un dépassement remet le monitor en ligne et envoie l’alerte de rétablissement.
En pause : les pings sont acceptés mais ne sont enregistrés nulle part et n’alertent personne. À la reprise, le délai repart du dernier ping reçu.
En sourdine ou pendant une maintenance : les pings sont enregistrés, les alertes retenues, comme pour tout monitor.

L’URL de ping n’a pas de région : la règle de majorité des checks multi-régions ne s’applique pas aux heartbeats.

Réponses et limites

Code	Corps	Signification
`200`	`{ "ok": true }`	Ping enregistré
`200`	`{ "ok": true, "paused": true }`	Le monitor est en pause : rien n’est enregistré
`400`	`{ "error": "INVALID_BODY" }`	Le corps n’est pas du JSON, ou un champ est hors limites : rien n’est enregistré
`404`	`{ "error": "NOT_FOUND" }`	Jeton inconnu, ou le monitor n’est pas un heartbeat
`413`	`{ "error": "PAYLOAD_TOO_LARGE" }`	Corps de plus de 8 Kio
`429`	`{ "error": "RATE_LIMIT_EXCEEDED" }`	Plus de 30 pings par minute pour ce monitor ; voir `Retry-After`

Garder le jeton secret

Le jeton dans l’URL est le seul identifiant : qui le possède peut envoyer des pings et masquer une tâche en échec. Gardez l’URL dans un secret ou une variable d’environnement plutôt que dans un dépôt public, et ne la collez ni dans un ticket ni dans une conversation. En cas de fuite, supprimez le monitor et créez-en un nouveau : le jeton ne peut pas être renouvelé sur place.

Prometheus

L’export Prometheus fournit okstatus_push_last_received_timestamp_seconds, l’heure du dernier ping, pour chaque monitor heartbeat.