Heartbeat monitoring for cron jobs
A heartbeat, also called a dead man's switch, is a request your cron job sends to CronRadar each time it succeeds. If the next heartbeat doesn't arrive by the job's next scheduled time plus a grace period, CronRadar alerts you. It works for any scheduler that can make an HTTP request: crontab, systemd timers, Kubernetes CronJobs, CI schedules or a script on a server.
A heartbeat tells you a job stopped succeeding. It doesn't tell you why. Add start and fail reports, described below, when you need to know that a run failed or got stuck.
Send a heartbeat with curl
Run the heartbeat after the job's command, and only when it succeeds:
# crontab: run the backup at 02:00, then report success
0 2 * * * /opt/backup/run.sh && { curl --fail --silent --show-error --max-time 5 --user "$CRONRADAR_API_KEY:" "https://cron.life/api/v1/ping/daily-backup?schedule=0\%202\%20*\%20*\%20*" || true; }daily-backupis the monitor key: a stable name for this job, at most 100 characters.scheduleis the job's cron expression, URL-encoded. The first heartbeat with a schedule creates the monitor, so there is nothing to set up in the console. Keep sending it so a deleted monitor registers again on the next run.--max-time 5and|| truekeep a slow or unreachable CronRadar from delaying or failing the job, and the braces keep the job's own exit code when the job fails.- In a crontab,
%starts a new line of input, so each%in the URL is written\%. In a script, write%as it is. --user "$CRONRADAR_API_KEY:"sends the application's API key with Basic authentication, so the key stays out of the URL. SetCRONRADAR_API_KEYwhere cron runs the job, and use a separate application and key for each environment.
A heartbeat without schedule for a key CronRadar doesn't know returns 404. See the HTTP API reference for every parameter.
Grace period
The grace period is how long CronRadar waits after a job's due time before it treats the run as missed. It absorbs normal lateness, such as a slow start or a busy server.
- A monitor created by its first heartbeat gets a grace period of 90 seconds unless the heartbeat sends
gracePeriod. - The minimum is 60 seconds. Send
gracePeriod=300, in seconds, for a job whose start time varies, or change it in the console. - Between the due time and the end of the grace period the job shows
warning, and no alert is sent. When grace ends with no heartbeat, and no sooner than two minutes after the due time, the job turnscriticaland CronRadar sendsInitialFailure.
Missed, vanished and never-ran jobs covers reminders and recovery.
When to add start and fail reports
A heartbeat alone catches one problem: the job stopped succeeding on schedule. Two questions need more:
| You want to know | Add | Why a heartbeat can't tell you |
|---|---|---|
| The job ran and failed | A fail report when the command fails | Without it, a failure looks like a missed run, found only after grace |
| The job started and never finished | A start report before the command | Without a start, CronRadar can't tell a hung run from one that never began |
| How long each run took | start and complete around the command | A heartbeat records only that the job succeeded |
| Whether the run's output was right | Outcome values on complete | A heartbeat carries no values |
A fail report alerts at once instead of waiting for the grace period. A start without a complete or fail by the next due time plus grace is a stuck run. The HTTP API reference has a full start, complete and fail script that keeps the job's own exit code.
If your jobs run in Hangfire, Quartz.NET, Celery or Laravel, you don't need heartbeats: the framework integrations find every job and send start, completion and failure for you.