Cron job monitoring: get told when a job does not run

How lateness is calculated

A heartbeat monitor has two numbers, both in seconds: how often the job should ping, and how much grace to allow. The deadline is the time of the last finish ping plus the period plus the grace. Once the clock passes that moment, an incident opens, with a message such as "Heartbeat missed, last ping 26 hours ago". Before the very first ping, the countdown starts from the moment you created the monitor, so a brand new heartbeat that never hears from its job also alerts.

The deadline moves with each ping, not with the wall clock. A nightly backup with a period of 86400 and a grace of 3600 is late if the next ping is more than 25 hours after the previous one. That sliding behaviour has a practical consequence: choose the grace to cover your longest normal run plus start-up jitter. If the job runs at 03:00, usually finishes by 03:20 but sometimes takes 80 minutes, a grace of one hour is too tight, and a grace of two hours is safe. The checker evaluates deadlines at the monitor's own check interval, so the alert can trail the deadline by up to one interval.

The three URLs

Saving the monitor gives you a ping URL of the form https://YOUR-APP-HOST/hb/hb_TOKEN. The token is the only secret, so keep it out of public repositories. GET and POST both work, and a successful call answers "ok".

• The bare URL, or /finish: the job succeeded. This resets the deadline and closes any open incident, which also sends a recovery notice.
• /fail: the job failed. An incident opens immediately, without waiting for the deadline, and the cause is whatever message you sent.
• /start: the job began. It is stored in the monitor history so you can see a run that started and never finished, but it does not move the deadline.
• Notes: ?msg=text or ?exit=2 on a GET, or a POST body of up to 10 KB, such as the tail of the log. The incident shows it.

Curl recipes

Keep these one-liners short; the shell does the rest. Replace the URL with yours.

• Plain cron: 0 3 * * * /usr/local/bin/backup.sh && curl -fsS -m 10 --retry 3 https://YOUR-APP-HOST/hb/hb_TOKEN > /dev/null. Because of &&, a failing script sends no ping and the miss alert covers it.
• Immediate failure: backup.sh && curl -fsS $URL || curl -fsS "$URL/fail?msg=backup+failed". The second branch opens an incident right away.
• Attach output: out=$(backup.sh 2>&1); curl -fsS --data-binary "$out" $URL/finish. Use $URL/fail in the failure branch so the log tail appears in the incident.
• systemd: add ExecStartPost=/usr/bin/curl -fsS https://YOUR-APP-HOST/hb/hb_TOKEN to a oneshot service, so it runs only after the main command exits successfully.
• Kubernetes CronJob or CI: put the curl as the last step of the job script; in GitHub Actions or GitLab, as the final step of a scheduled workflow.

Schedules the form cannot express

Heartbeats work with a plain period, not with a cron expression or a time zone. A job that runs only on weekdays therefore needs a period long enough to bridge the weekend, for example 3 days, which also means a Friday failure is noticed on Monday. Better: use a period of one day with two monitors, or have the job ping every day, including a "nothing to do" ping on weekends. For monthly jobs, a period of 32 days plus a day of grace does the job. The cron builder helps work out the real interval between runs of an unusual expression.

What a heartbeat catches, and what it cannot

It catches everything that stops the job from reaching its last line: a dead cron daemon, a reboot that disabled the entry, a full disk, a changed PATH, an expired password, a hung process that never exits, and a wrong edit to the crontab. It cannot know that a job which finished was also correct. A backup script that exits zero after writing a zero-byte file will happily ping. Put the ping after a verification step, for instance a file-size test or a row count, so success means something.

Heartbeats do not go through multi-region confirmation, because nothing network-dependent is being tested; the server either called in or did not. A missed ping inside an active maintenance window opens no incident, and a paused monitor keeps recording pings without alerting.

Limits and plans

Heartbeats start on the Starter plan; the Free plan has none. Allowances are 20 on Starter, 100 on Pro and 500 on Agency. Each ping URL accepts up to 30 calls a minute, and an IP gets 60 across all tokens; beyond that the endpoint answers 429, so pinging more often than once every few seconds from a busy loop is pointless. For queue workers, ping once a minute with a period of 120 and a grace of 60. The alert channels are the same as for any monitor, with escalation from Pro for the nightly job that cannot be allowed to fail; see alert escalation. The URL formats are listed in the heartbeat API docs.