Heartbeat (Cronjobs)

Überblick

Ein Heartbeat-Monitor (Typ push) arbeitet umgekehrt zu den anderen Prüfungen: Nicht OKStatus ruft Ihren Dienst auf, sondern Ihr Job ruft OKStatus bei jedem Lauf auf. Kommt kein Ping rechtzeitig an, gilt der Monitor als ausgefallen und Sie werden alarmiert.

Er eignet sich für alles, was nach Zeitplan läuft und keine URL zum Prüfen hat: Cronjobs, Backups, Queue-Worker, nächtliche Importe, Zertifikatserneuerungen.

Einen anlegen

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

Bei einem Heartbeat ist url nur eine Bezeichnung: Es wird nichts abgerufen.
interval ist die Laufhäufigkeit des Jobs in Sekunden.
gracePeriod ist die zusätzliche Frist vor dem Ausfall. Ohne Angabe entspricht sie interval.

Die Antwort enthält die pushUrl des Monitors:

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

Dieselbe pushUrl kommt bei jedem Lesen des Monitors mit einem Schlüssel mit Zugriff Voll zurück. Ein Schlüssel mit Zugriff Nur Lesen und ein Mitglied mit der Rolle Viewer sehen den Monitor ohne Token und URL. Mit Terraform bauen Sie die URL aus dem Attribut push_token:

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

Einen Ping senden

Rufen Sie die URL am Ende jedes erfolgreichen Laufs auf. POST, GET und HEAD zählen alle als up-Ping:

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

Eine Crontab-Zeile, die nur bei Erfolg des Jobs pingt:

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

Um einen Fehler zu melden oder eine Nachricht zu senden, verwenden Sie POST mit einem Body (unten): Ein GET ist immer ein up-Ping. Linkvorschauen in Chat-Tools rufen URLs per GET ab – ein weiterer Grund, die URL nicht in eine Unterhaltung einzufügen.

Einen Fehler oder eine Dauer melden

Der Body ist optional. Wenn vorhanden, ist er JSON:

Feld	Typ	Beschreibung
`status`	String	`up` (Standard) oder `down`: meldet einen Fehler sofort, ohne zu warten
`msg`	String	Bis zu 2.000 Zeichen, mit der Prüfung gespeichert und im Dashboard und in Alarmen angezeigt
`ping`	Integer	Dauer des Jobs in Millisekunden (0 bis 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 ist fehlgeschlagen" }'
fi

Ein leerer Body ist ein up-Ping. Ein Body, der kein gültiges JSON ist oder dessen Felder nicht zur Tabelle passen, wird mit 400 abgelehnt und nichts wird gespeichert: Ein Tippfehler wie "status": "failed" kann nicht als Erfolg durchgehen.

Wann der Monitor ausfällt

Der Monitor gilt als ausgefallen, wenn seit dem letzten Ping interval + gracePeriod Sekunden lang keiner angekommen ist. OKStatus prüft alle 30 Sekunden.

Vor dem ersten Ping hat der Monitor keinen Zustand und fällt nie aus: Senden Sie beim Einrichten des Jobs einen Ping.
Ein Ping nach einer Überschreitung setzt den Monitor wieder auf online und sendet den Wiederherstellungsalarm.
Pausiert: Pings werden angenommen, aber nirgends gespeichert und alarmieren niemanden. Beim Fortsetzen zählt der zuletzt empfangene Ping.
Stummgeschaltet oder im Wartungsfenster: Pings werden gespeichert, Alarme zurückgehalten, wie bei jedem Monitor.

Die Ping-URL hat keine Region: Die Mehrheitsregel der Multi-Region-Prüfungen gilt für Heartbeats nicht.

Antworten und Grenzen

Status	Body	Bedeutung
`200`	`{ "ok": true }`	Ping gespeichert
`200`	`{ "ok": true, "paused": true }`	Der Monitor ist pausiert: nichts gespeichert
`400`	`{ "error": "INVALID_BODY" }`	Der Body ist kein JSON oder ein Feld liegt außerhalb der Grenzen: nichts gespeichert
`404`	`{ "error": "NOT_FOUND" }`	Unbekanntes Token, oder der Monitor ist kein Heartbeat
`413`	`{ "error": "PAYLOAD_TOO_LARGE" }`	Body größer als 8 KiB
`429`	`{ "error": "RATE_LIMIT_EXCEEDED" }`	Mehr als 30 Pings pro Minute für diesen Monitor; siehe `Retry-After`

Das Token geheim halten

Das Token in der URL ist die einzige Zugangsangabe: Wer es hat, kann Pings senden und einen fehlgeschlagenen Job verbergen. Bewahren Sie die URL in einem Secret oder einer Umgebungsvariable auf statt in einem öffentlichen Repository, und fügen Sie sie weder in Tickets noch in Chats ein. Bei einem Leck löschen Sie den Monitor und legen einen neuen an: Das Token lässt sich nicht an Ort und Stelle erneuern.

Prometheus

Der Prometheus-Export liefert okstatus_push_last_received_timestamp_seconds, den Zeitpunkt des letzten Pings, für jeden Heartbeat-Monitor.