Cronjob überwachen: Heartbeat-Monitoring für Cron, Laravel und CI

Kurz gesagt: Cron führt Ihren Job aus und sagt niemandem, was passiert ist. Schlägt der Job fehl, bleibt er hängen oder startet er gar nicht, erfahren Sie es erst, wenn ein Kunde, ein leerer Backup-Ordner oder eine fehlende Rechnung es Ihnen verrät. Wer einen Cronjob überwachen will, dreht das Prinzip um: Der Job ruft nach Abschluss eine URL auf, und bleibt dieser Aufruf zur erwarteten Zeit aus, bekommen Sie einen Alarm. Das nennt sich Heartbeat Monitoring und kostet eine Zeile in Ihrer crontab.

Fakten geprüft am 14. Oktober 2026 anhand der Manpage zu crontab, der Laravel-Dokumentation zum Task Scheduling und der GitHub-Dokumentation zu geplanten Workflows. Die Quellen finden Sie am Ende des Artikels.

Warum Cronjobs still scheitern

Eine Webseite, die nicht mehr funktioniert, fällt innerhalb von Minuten auf. Ein nächtlicher Job, der nicht mehr funktioniert, fällt erst auf, wenn jemand das braucht, was er hätte liefern sollen. Die üblichen Ursachen, wenn ein Cronjob nicht läuft:

1. Eine andere Umgebung. Laut crontab-Manpage setzt cron für Ihren Job nur SHELL=/bin/sh, LOGNAME und HOME. Alles, was Ihre Login-Shell lädt – zusätzliche PATH-Einträge, Versionsmanager, exportierte Variablen –, fehlt. Ein Skript, das von Hand gestartet funktioniert, scheitert unter cron.
2. Ein Prozentzeichen. In einer crontab-Zeile wird ein nicht maskiertes % zu einem Zeilenumbruch, und alles danach geht als Eingabe an den Befehl. Ein date +%F im Namen einer Backup-Datei macht so stillschweigend die ganze Zeile kaputt.
3. Ausgaben, die ins Leere laufen. Cron schickt die Ausgabe eines Jobs per Mail an den Besitzer der crontab oder an MAILTO. Auf den meisten Servern liest dieses Postfach niemand, oder es wird gar keine Mail zugestellt – die Fehlermeldung existiert also, nur sieht sie keiner.
4. Ein Job, der nie fertig wird. Ein Netzwerkaufruf ohne Timeout oder ein Lock, den ein abgestürzter Lauf zurückgelassen hat, und der Job hängt. Kein Fehler, keine Ausgabe, einfach nichts.
5. Zeitumstellung. Die crontab-Manpage sagt es klar: Zeitpunkte, die es während der Umstellung nicht gibt, passen nie, die betroffenen Jobs laufen also nicht; Zeitpunkte, die doppelt vorkommen, lassen Jobs zweimal laufen.
6. Der Zeitplan verschwindet. Eine Servermigration, ein neu gebauter Container oder ein Deploy ohne die crontab – und der Job existiert schlicht nicht mehr.
7. Der Scheduler der Plattform ist keine Garantie. Laut GitHub-Dokumentation können geplante Workflows bei hoher Last verzögert werden, einzelne Jobs in der Warteschlange können verworfen werden, und in einem öffentlichen Repository werden sie nach 60 Tagen ohne Aktivität im Repository automatisch deaktiviert.

Keiner dieser Fälle löst von sich aus einen Alarm aus. Genau das ist das eigentliche Problem mit cron: Ein Fehler sieht exakt so aus wie ein Erfolg – Stille.

Warum Uptime-Monitoring das nicht erkennt

Uptime-Monitoring stellt Ihrem Server eine Frage und prüft die Antwort. Ein Cronjob beantwortet keine Fragen: Es gibt keinen Port, zu dem man sich verbinden, und keine Seite, die man laden könnte. Was Sie erkennen müssen, ist eine Abwesenheit – ein Lauf, der hätte stattfinden sollen und es nicht tat. Das bemerkt nur etwas, das zu einer bestimmten Zeit ein Signal erwartet und feststellt, dass es nie kam.

So funktioniert Heartbeat Monitoring

Sie teilen dem Monitoring-Dienst mit, wann der Job laufen soll – alle 15 Minuten oder als Cron-Ausdruck wie 0 3 * * * – und wie viel Verspätung akzeptabel ist (die Grace Period, also die Toleranzzeit). Der Job pingt nach jedem erfolgreichen Lauf eine eindeutige URL an. Damit weiß der Dienst, in welchem Zustand der Job ist:

Die letzten beiden Zeilen zeigen, warum ein gutes Setup mehr als ein Signal sendet. Ein Ping am Ende sagt Ihnen, dass der Job fertig ist. Ein zusätzlicher Ping am Anfang sagt Ihnen, dass er begonnen hat – so wird ein Job, der auf halbem Weg hängen bleibt, erkannt, statt wie einer auszusehen, der nie lief. Und ein expliziter Fehler-Ping schlägt sofort Alarm, statt bis zur Deadline zu warten.

Monitoring zu einem Cronjob hinzufügen

Die einfachste Variante pingt nur nach einem erfolgreichen Lauf. Das && ist wichtig: Schlägt der Job fehl, wird der Ping nie gesendet, und der Check geht zur Deadline auf Ausgeblieben.

0 3 * * * /path/to/backup.sh && curl -fsS --retry 3 https://api.alertsleep.com/v1/ping/YOUR-TOKEN

Die vollständige Variante meldet Start, Erfolg und Fehler:

0 3 * * * curl -fsS --retry 3 https://api.alertsleep.com/v1/ping/YOUR-TOKEN/start; if /path/to/backup.sh; then curl -fsS --retry 3 https://api.alertsleep.com/v1/ping/YOUR-TOKEN; else curl -fsS --retry 3 https://api.alertsleep.com/v1/ping/YOUR-TOKEN/fail; fi

Zwei Details sind Absicht. Auf den Start-Ping folgt ;, nicht &&, damit der Job auch dann läuft, wenn der Ping nicht zugestellt werden kann. Und die Zeile verwendet if/then/else statt der beliebten Kurzform job && success || fail, die einen Fehler meldet, wenn der Job zwar erfolgreich war, aber nur der Erfolgs-Ping nicht angekommen ist.

Sie können auch den Exit Code übergeben und die Entscheidung dem Monitoring-Dienst überlassen. Ein Code ungleich null, der an die Erfolgs-URL geschickt wird, wird als Fehler gewertet:

0 3 * * * /path/to/backup.sh; curl -fsS --retry 3 --data "exit_code=$?" https://api.alertsleep.com/v1/ping/YOUR-TOKEN

Die curl-Optionen sollten Sie beibehalten: -f sorgt dafür, dass ein HTTP-Fehler als Fehler zählt, -sS bleibt still, solange nichts schiefgeht, und --retry 3 übersteht einen kurzen Netzwerk-Schluckauf.

Laravel Scheduler überwachen

Ist der Job bereits ein geplanter Laravel-Befehl, kann der Scheduler die URLs selbst aufrufen – ohne Shell-Quoting und ohne Exit Codes, die Sie von Hand weiterreichen müssen:

// routes/console.php
Schedule::command('backup:run')
    ->cron('0 3 * * *')
    ->pingBefore('https://api.alertsleep.com/v1/ping/YOUR-TOKEN/start')
    ->pingOnSuccess('https://api.alertsleep.com/v1/ping/YOUR-TOKEN')
    ->pingOnFailure('https://api.alertsleep.com/v1/ping/YOUR-TOKEN/fail');

Einen Punkt sollten Sie bei Laravel noch im Blick behalten: Der gesamte Scheduler hängt an einem einzigen crontab-Eintrag, der jede Minute php artisan schedule:run ausführt. Geht dieser Eintrag verloren, stoppen alle geplanten Tasks auf einen Schlag – und genau das zeigt Ihnen ein Heartbeat auf Ihrem wichtigsten Task.

Geplante Workflows in GitHub Actions

Da geplante Workflows verzögert, verworfen oder deaktiviert werden können, brauchen sie einen Heartbeat genauso wie ein Server. Legen Sie die Ping-URL in einem Repository-Secret ab, behandeln Sie sie wie ein Passwort und fügen Sie drei Schritte hinzu:

on:
  schedule:
    - cron: '0 3 * * *'

jobs:
  nightly:
    runs-on: ubuntu-latest
    steps:
      - run: curl -fsS --retry 3 "${{ secrets.ALERTSLEEP_PING_URL }}/start" || true
      - run: ./scripts/nightly.sh
      - if: success()
        run: curl -fsS --retry 3 "${{ secrets.ALERTSLEEP_PING_URL }}"
      - if: failure()
        run: curl -fsS --retry 3 "${{ secrets.ALERTSLEEP_PING_URL }}/fail"

Das || true beim Start-Ping hält den Workflow am Laufen, falls der Ping nicht zugestellt werden kann. Ein Lauf, den GitHub über Ihre Grace Period hinaus verzögert oder gar nicht erst startet, erscheint als ausgebliebener Heartbeat – der eine Fehler, den der Workflow selbst niemals melden kann.

Wie lang sollte die Grace Period sein?

Lang genug für die normale Schwankung des Jobs, kurz genug, dass ein echtes Problem noch frisch ist. Eine brauchbare Faustregel: Nehmen Sie den längsten Lauf, den Sie beobachtet haben, und geben Sie einen Puffer dazu. Ein Backup, das normalerweise 20 bis 40 Minuten dauert, braucht etwa eine Stunde; einem Aufräum-Job, der Sekunden dauert, reichen fünf Minuten. Geht der Check immer wieder auf Verspätet, ohne dass etwas nicht stimmt, ist die Grace Period zu kurz – und ein Alarm, der meistens ein Fehlalarm ist, bringt Menschen bei, ihn zu ignorieren.

So überwacht AlertSleep Cronjobs

Ein Cron-Check in AlertSleep besteht aus einem Zeitplan und einer Ping-URL:

• Der Zeitplan ist entweder ein Intervall – von einer Minute bis zu 30 Tagen – oder ein Cron-Ausdruck mit eigener Zeitzone;
• die Grace Period kann zwischen 30 Sekunden und 24 Stunden liegen, Standard sind fünf Minuten;
• die Ping-URL akzeptiert GET, POST und HEAD, mit den Varianten /start und /fail, optional mit Exit Code, Laufzeit und einer kurzen Nachricht;
• ein Job, der /start gesendet hat und innerhalb der Grace Period nichts weiter, wird als hängend gemeldet, nicht als ausgefallen;
• Alarme kommen per E-Mail und im Dashboard, sobald ein Check einen Ausfall meldet, und nach dem nächsten erfolgreichen Ping folgt eine Entwarnung;
• jeder Ping wird mit Exit Code und Laufzeit gespeichert, sodass Sie sehen, ab wann ein Job länger gebraucht hat;
• das Dashboard zeigt für jeden Check fertige crontab- und Laravel-Snippets zum Einfügen, und das Token lässt sich neu erzeugen, falls eine Ping-URL nach außen gelangt.

Details finden Sie auf der Seite zum Cron-Monitoring. Wenn Sie den Zeitplan selbst noch schreiben, erstellt der kostenlose Cron-Ausdrucks-Generator einen Ausdruck aus einem Formular und listet die nächsten fünf Ausführungen auf.

Cron-Checkliste für 20 Minuten

1. Finden Sie jeden geplanten Job. crontab -l für jeden Benutzer, die Dateien in /etc/cron.d, systemctl list-timers, geplante CI-Workflows und jeden Scheduler innerhalb Ihrer Anwendung.
2. Fragen Sie bei jedem: Was geht kaputt, wenn er eine Woche lang nicht läuft? Backups, Rechnungen, Datensynchronisation, Zertifikatserneuerungen und Aufräum-Jobs stehen meist ganz oben.
3. Versehen Sie die wichtigen mit einem Heartbeat – fangen Sie mit Backups an, denn ein fehlgeschlagenes Backup bemerkt man erst, wenn man wiederherstellen muss.
4. Legen Sie Grace Periods anhand echter Laufzeiten fest, nicht nach Schätzung.
5. Testen Sie es: Stoppen Sie absichtlich einen Job oder lassen Sie ihn auf einen falschen Pfad zeigen, und prüfen Sie, ob der Alarm ankommt.
6. Maskieren Sie jedes % in Ihren crontab-Zeilen und setzen Sie die Umgebung, die der Job braucht, explizit am Anfang des Skripts.

FAQ

Was ist der Unterschied zwischen Cronjob Monitoring und Uptime-Monitoring?

Uptime-Monitoring prüft etwas, das immer da ist – eine Website, eine API, einen Port. Cronjob Monitoring wartet auf ein Signal von etwas, das nur ab und zu läuft, und schlägt Alarm, wenn das Signal ausbleibt.

Muss der Job aus dem Internet erreichbar sein?

Nein. Der Job stellt nur eine ausgehende HTTPS-Anfrage an die Ping-URL. Nichts muss sich mit Ihrem Server verbinden.

Was passiert, wenn der Ping nicht zugestellt werden kann?

--retry 3 fängt kurze Netzwerkprobleme ab. Kommt der Ping trotzdem nicht an, geht der Check zur Deadline auf Ausgeblieben, und Sie erhalten einen Alarm. Das kann gelegentlich ein Fehlalarm sein, aber es ist die sichere Richtung: Ein übersehener echter Fehler kostet weit mehr als eine überflüssige E-Mail.

Kann ich Jobs überwachen, die öfter als einmal pro Minute laufen?

Das kürzeste Intervall ist eine Minute. Bei Jobs, die öfter laufen, pingen Sie einmal pro Minute aus dem Job heraus oder überwachen den Prozess, der sie startet.

Ist die Ping-URL geheim?

Ja. Wer sie kennt, kann Ihren Job als gesund melden. Halten Sie sie aus öffentlichen Repositories heraus, speichern Sie sie in der CI als Secret und erzeugen Sie das Token neu, falls sie jemals nach außen gelangt.

Quellen

• crontab(5) – Linux-Manpage
• Laravel – Task Scheduling
• GitHub Docs – Ereignisse, die Workflows auslösen: schedule