Zurück zum Blog

Cron-Job-Überwachung mit Healthchecks.io: Push-Benachrichtigung aufs Handy, wenn ein Job fehlschlägt oder gar nicht läuft

Cron-Job-Überwachung mit Healthchecks.io: Push-Benachrichtigung aufs Handy, wenn ein Job fehlschlägt oder gar nicht läuft

Ein Cron-Job kann auf zwei Arten kaputtgehen. Er läuft und schlägt fehl: pg_dump erreicht die Datenbank nicht, die Festplatte ist voll. Oder er läuft gar nicht mehr: Eine Zeile in der Crontab wird gelöscht, der Server wird ohne sie neu aufgesetzt, der Cron-Daemon ist tot. Die erste Art hinterlässt irgendwo eine Fehlermeldung. Die zweite hinterlässt nichts, und du merkst es an dem Tag, an dem du das Backup von gestern Nacht brauchst.

Eine Alarmierung, die darauf wartet, dass ein Job „Ich bin fehlgeschlagen“ meldet, hört nie von einem Job, der gar nicht gestartet ist. Dafür brauchst du den umgekehrten Aufbau: Der Job meldet sich bei jedem Abschluss, und etwas anderes schlägt Alarm, wenn die Meldung ausbleibt.

Diese Anleitung baut das mit Healthchecks.io, dem quelloffenen Cron-Monitor, und schickt die Alarme mit Pocket Alert aufs Handy. Fehler kommen laut an, Entwarnungen leise. Alles unten wurde mit dem selbst gehosteten Healthchecks-v5.0.3-Docker-Image getestet und funktioniert im gehosteten Dienst genauso.

Was du brauchst

  • Ein Healthchecks-Konto auf healthchecks.io (der kostenlose Tarif Hobbyist überwacht 20 Jobs) oder eine eigene Instanz aus dem Docker-Image healthchecks/healthchecks.
  • Die Pocket Alert App auf deinem iPhone oder Android-Handy und einen API-Schlüssel aus API Keys. Der kostenlose Tarif reicht zum Start.
  • curl auf dem Rechner, der die Cron-Jobs ausführt.

Der Dead-Man’s-Switch

Healthchecks nennt das Heartbeat-Überwachung, eine Art Dead-Man’s-Switch. Jeder Job bekommt einen Check mit einer eindeutigen Ping-URL, die der Job beim Abschluss aufruft. Kommt der nächste Aufruf nicht rechtzeitig, geht der Check auf down, und die Alarme werden verschickt.

Zwei Einstellungen bestimmen, was „rechtzeitig“ heißt:

  • Periode ist, wie oft du einen Ping erwartest: jede Stunde, jeden Tag.
  • Nachfrist ist, wie lange Healthchecks nach dem erwarteten Zeitpunkt wartet, bevor es auf down schaltet. Stelle sie länger ein als die übliche Laufzeit des Jobs plus etwas Puffer.

Bei einem Cron-Job wählst du stattdessen den Zeitplantyp Cron und fügst den Ausdruck aus deiner Crontab ein, dazu die Zeitzone des Servers. Healthchecks erwartet die Pings dann zu den richtigen Uhrzeiten und nicht nur in den richtigen Abständen. Der Cron-Ausdruck-Editor erklärt, was ein Ausdruck bedeutet.

In unserem Test wurde ein Check mit dem Zeitplan */2 * * * * und einer Nachfrist von einer Minute um 16:09:13 angepingt. Um 16:10 kam kein Ping, und der Check ging um 16:11:00 auf down, genau eine Nachfrist später.

Die Ping-URL gibt es in mehreren Varianten:

AufrufBedeutung
https://hc-ping.com/<uuid>Erfolg. Der Job ist fertig.
https://hc-ping.com/<uuid>/startDer Job wurde gestartet. Healthchecks erwartet nun innerhalb der Nachfrist einen Erfolg und protokolliert die Laufzeit.
https://hc-ping.com/<uuid>/failDer Job ist fehlgeschlagen. Der Check geht sofort auf down.
https://hc-ping.com/<uuid>/<0-255>Ein Exit-Status. 0 zählt als Erfolg, alles andere als Fehler.

Bei einer selbst gehosteten Instanz besteht die Basis aus deiner eigenen Domain plus /ping/, zum Beispiel https://hc.example.com/ping/<uuid>.

Den Cron-Job anbinden

Lege einen Check an, kopiere seine Ping-URL und ändere die Zeile in der Crontab. Wir haben das unter dem Cron-Daemon auf Debian 13 getestet:

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= ist eine Crontab-Variable, die die Shell im Befehl ersetzt. Die Zeile erledigt drei Dinge:

  • Sie sendet /start, damit ein hängender Job auf down geht, sobald die Nachfrist abgelaufen ist. In unserem Test schaltete ein /start ohne Folgemeldung den Check genau eine Nachfrist später auf down.
  • Sie startet den Job.
  • Sie sendet $?, den Exit-Status des Jobs. Ein sauberer Lauf sendet /0, ein fehlgeschlagener /2 oder was immer das Skript zurückgegeben hat, und der Check geht sofort auf down.

Die curl-Optionen verhindern, dass der Ping selbst Probleme macht:

  • -m 10 begrenzt jede Anfrage auf 10 Sekunden. Ein hängendes /start darf den Job nicht aufhalten.
  • --retry 5 wiederholt Timeouts sowie die Antworten 408, 429, 500, 502, 503 und 504, mit wachsenden Wartezeiten. Ein verlorenes Paket soll dich nicht alarmieren.
  • -fsS lässt curl bei HTTP-Fehlern fehlschlagen und ansonsten still bleiben, sodass cron dir nicht den Fortschrittsbalken von curl per Mail schickt.
  • -o /dev/null verwirft den Antwortinhalt, der nur aus OK besteht.

Wenn der Job eine Pipeline wie pg_dump | gzip > dump.gz ist, entspricht sein Exit-Status dem von gzip und nicht dem von pg_dump. Lagere ihn in ein Skript mit set -o pipefail in bash aus, damit ein fehlgeschlagener Dump nicht als Erfolg gemeldet wird.

Oder lass runitor das erledigen

runitor ist ein kleines Go-Binary, das einen Befehl umschließt und die Pings übernimmt: /start vorher, den Exit-Status danach, und die letzten 10.000 Bytes der Befehlsausgabe werden an den Ping angehängt.

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

Die Crontab-Zeile wird kürzer:

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

Bei einer selbst gehosteten Instanz ergänze HC_API_URL=https://hc.example.com/ping. Wir haben runitor v1.4.1 so unter cron betrieben: Ein fehlgeschlagenes Backup schaltete den Check mit Exit-Status 2 auf down, und seine Fehlerausgabe erschien im Alarm.

Alarme an Pocket Alert senden

Healthchecks erreicht Pocket Alert über seine allgemeine Webhook-Integration. Gehe zu Integrations, finde Webhook und klicke auf Add Integration. Das Formular hat zwei Abschnitte, „Execute when a check goes down“ und „Execute when a check goes up“, jeweils mit eigener URL, Methode, Body und Headern. Diese Trennung macht „down“ laut und „up“ leise.

Beide Abschnitte akzeptieren Platzhalter: $NAME, $NAME_JSON, $STATUS, $NOW, $CODE, $SLUG, $TAGS, $EXITSTATUS, $BODY, $BODY_JSON, $JSON und ein paar weitere. Bei JSON-Bodies ist der Unterschied wichtig: $NAME wird roh eingefügt, sodass ein Check namens Nightly "db" backup das JSON zerstört. $NAME_JSON dagegen ist eine vollständige JSON-Zeichenkette, inklusive Anführungszeichen. Dasselbe gilt für $BODY und $BODY_JSON.

Option 1: direkt an die API

Im Abschnitt down wählst du POST und die URL https://api.pocketalert.app/v1/messages. Request-Header, einer pro Zeile:

Content-Type: application/json
Token: YOUR_API_KEY

Request-Body:

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

Im Abschnitt up dieselbe Methode, URL und Header, und ein leiserer Body:

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

Klicke auf Save Integration. Eine neue Integration wird allen bestehenden Checks im Projekt zugeordnet. So sah der Body aus, den Healthchecks beim Fehlschlag unseres Test-Checks gesendet hat:

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

Einige Hinweise zu diesem Body:

  • high ist zeitkritisch. Es durchbricht Fokus und die geplante Zusammenfassung. Im kostenpflichtigen Tarif kannst du es auf critical setzen. Dann weckt dich ein toter Backup-Job auch über den lautlosen Schalter und Nicht stören. Im kostenlosen Tarif wird critical akzeptiert und als high zugestellt.
  • low für Entwarnungen. „Back up“ landet ohne Ton im Feed. Du willst es wissen, aber nicht um 3 Uhr nachts.
  • $EXITSTATUS unterscheidet Fehler von Ausbleiben. Es ist der Exit-Status des letzten Pings vor dem Alarm. 2 heißt, der Job lief und gab 2 zurück. Ein down mit 0 heißt, der letzte Lauf war erfolgreich und der nächste kam nie. -1 heißt, der letzte Ping trug keinen Exit-Status: eine einfache Erfolgs-URL, /fail oder /start.
  • Der Button öffnet den Check in Healthchecks. Bei einer selbst gehosteten Instanz trägst du deine eigene Domain in die URL ein. Aktionsbuttons sind ein kostenpflichtiges Feature. Im kostenlosen Tarif werden sie entfernt, und die Nachricht selbst wird wie gewohnt zugestellt.

Option 2: ein Pocket-Alert-Webhook mit Vorlage

Der zweite Weg schickt ein kleines JSON-Dokument an einen Pocket-Alert-Webhook, der die Push-Benachrichtigung formatiert. Sein Vorteil: Er kann die Ausgabe des Jobs enthalten.

Öffne Webhooks in der Pocket-Alert-Konsole, lege einen namens Healthchecks an und setze die Nachrichtenvorlage:

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

Lass Default priority unausgewählt, denn die Nutzlast bringt ihre eigene Priorität mit. Kopiere die Webhook-URL, sie sieht aus wie https://p4a.me/wh/abc123xyz. Die URL ist das Geheimnis, behandle sie wie ein Passwort.

Lege in Healthchecks die Webhook-Integration mit dieser URL als POST in beiden Abschnitten an, mit dem Header Content-Type: application/json und diesen Bodies. 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 ist der Body des letzten Pings, und dorthin schreibt runitor die Ausgabe des Jobs. Als unser runitor-umschlossenes Backup im Test fehlschlug, lautete die Push-Benachrichtigung:

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 liest das oberste Feld level einer eingehenden Nutzlast, daher funktionieren high und low wie in Option 1. Ohne runitor ist $BODY_JSON eine leere Zeichenkette, und die zweite Zeile bleibt leer. Die API kann das nicht: $BODY_JSON ist eine vollständige JSON-Zeichenkette und kann deshalb nur die ganze message sein. Hatte der Ping keinen Body, ist diese Nachricht leer, und die API lehnt sie ab.

Zwei weitere Unterschiede: Der Titel der Push-Benachrichtigung lautet immer Webhook <name>, deshalb gehört der Check-Name in die Nachricht. Webhook-Buttons setzt du über das Feld actions der Webhook-API und nicht über das Konsolenformular.

Teste es

Auf der Seite Integrations in Healthchecks hat jede Integration einen Button Test!. Er sendet eine „down“-Benachrichtigung für einen Check namens TEST, die als high-Push ankommt. Starte danach einen Job, der mit 1 beendet wird, und beobachte, ob der echte Alarm ankommt.

Ohne Healthchecks: ein Wrapper, der bei Fehlern pusht

Wenn du keinen weiteren Dienst willst, deckt ein kurzer Wrapper den häufigsten Fall ab: ein Job, der mit einem Fehler endet. Speichere ihn als /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"

Und in der Crontab:

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

Einige bewusste Entscheidungen:

  • --form-string statt JSON. Die API akzeptiert Multipart-Formulardaten, und --form-string sendet die Ausgabe unverändert, inklusive Anführungszeichen und Zeilenumbrüchen, ohne jq oder Escaping. Mit einfachem -F würde ein Wert, der mit @ oder < beginnt, als Datei behandelt.
  • tail -c 2000 behält das Ende der Ausgabe, wo meist der Fehler steht.
  • --retry-max-time 30 ist wichtig. Über dem täglichen Nachrichtenlimit antwortet die API mit 429 und einem Retry-After in Sekunden bis Mitternacht UTC, und curls --retry berücksichtigt das. In unserem Test wartete curl ohne diese Option auf Retry-After: 30000, bis wir es abbrachen. Mit ihr gibt curl nach einem Versuch auf.
  • Der Wrapper behält den Exit-Status und gibt die Ausgabe aus, sodass Cron-Logs und MAILTO weiterhin funktionieren.

Das Skript besteht shellcheck, und unter cron auf Debian 13 kam das fehlgeschlagene Backup als „Cron failed: nightly backup on“ plus Hostname an, mit dem pg_dump-Fehler im Text.

Sei dir klar darüber, was das nicht kann. Der Wrapper läuft nur, wenn cron ihn startet. Wird die Crontab-Zeile gelöscht, ist der Daemon tot oder die Maschine aus, wird nichts gesendet: der stille Ausfall vom Anfang dieses Artikels. Ein Job, der für immer hängt, bleibt ebenfalls unbemerkt. Dafür brauchst du etwas außerhalb der Maschine, das auf einen Heartbeat wartet, und genau dafür ist Healthchecks da. Die Pocket Alert CLI kann den curl-Aufruf ersetzen, falls du das lieber möchtest.

Ehrliche Grenzen

  • Healthchecks muss laufen, um etwas zu bemerken. Im gehosteten Dienst ist das deren Aufgabe. Wenn du es auf demselben Rechner wie die Cron-Jobs selbst hostest, reißt ein ausgefallener Rechner den Monitor mit sich. Betreibe ihn woanders.
  • Die Body-Vorlage ist in Healthchecks auf 1.000 Zeichen begrenzt. Für die Bodies oben reicht das, für eine lange handgeschriebene Nachricht nicht.
  • Lange Ausgaben werden in der Push-Benachrichtigung gekürzt. Die Push-Benachrichtigung trägt ungefähr die ersten 3 KB der Nachricht. Der vollständige Text steht im Nachrichtenverlauf der App.
  • Jeder Alarm ist eine Nachricht. Ein flackernder Job, der alle paar Minuten auf down und wieder auf up geht, sendet jedes Mal eine Push-Benachrichtigung, und im kostenlosen Tarif mit 50 Nachrichten pro Tag summiert sich das. Behebe den Job oder erhöhe die Nachfrist.

Wenn nichts ankommt

  • Verwende zuerst den Button Test!. Kommt der Test an, echte Alarme aber nicht, prüfe auf der Seite des Checks, ob die Integration für diesen Check aktiviert ist.
  • Schau auf die Seite Integrations in Healthchecks. Eine fehlschlagende Integration ist dort mit Failed markiert. Fahre mit der Maus darüber, um den letzten Fehler zu sehen, etwa Received status code 401. Ein 401 heißt, der Header Token ist falsch. Ein 400 bedeutet meist, dass der Body kein gültiges JSON ist: Prüfe, ob du $NAME_JSON ohne Anführungszeichen drumherum verwendet hast und nicht "$NAME".
  • Ein neuer Check alarmiert erst nach seinem ersten Ping. Bis dahin ist er „new“, nicht „down“.
  • Prüfe die Zeitzone von Cron-Checks. Wenn ein Check immer eine Stunde zu früh oder zu spät ist, passt die Zeitzone des Servers nicht zu der im Check.
  • Schau in den Feed. low-Pushes sind lautlos, daher kann eine Entwarnung so aussehen, als wäre sie nie angekommen.

FAQ

Soll ich den API-Weg oder den Webhook-Weg nehmen?

Der API-Weg setzt den Check-Namen in den Titel der Push-Benachrichtigung und braucht nichts, was du in Pocket Alert anlegen musst. Der Webhook-Weg kann die Ausgabe des Jobs enthalten. Nimmst du also runitor, wähle den Webhook.

Kann ich nur die „down“-Alarme bekommen?

Ja. Verwende für „up“ einen leisen low-Body wie oben, oder lass die „up“-URL leer, dann sendet Healthchecks bei einer Entwarnung nichts.

Und systemd-Timer?

Gleiche Idee. Healthchecks hat einen Zeitplantyp OnCalendar, der dieselben Ausdrücke wie dein Timer akzeptiert. Sende /start aus ExecStartPre oder umschließe den Befehl in ExecStart mit runitor.

Wo finde ich mehr über Cron-Alarme?

Die Seite Cron-Job-Alarme beschreibt, wie der Job selbst eine Push-Benachrichtigung schickt. Backup-Alarme behandelt Backup-Werkzeuge, und der Proxmox-Leitfaden beschreibt Backups auf einem Hypervisor.

Erstelle ein kostenloses Konto, füge in Healthchecks eine Webhook-Integration hinzu, und lass den Job, der still aufgehört hat zu laufen, dich wecken.

Artikel teilen