Heartbeat monitoring for cron jobs

How heartbeat monitoring works

Each heartbeat monitor has its own private URL. Your job calls it when it finishes. You tell Uptime Dog how often to expect a call (anything from 30 seconds to 31 days) and how much grace to allow on top (up to 7 days). If no call arrives within the period plus the grace, the monitor goes down, an incident opens and your alerts go out with the reason: "No ping received within 1h 5m", for example.

When the job checks in again, the monitor comes back up and the incident resolves on its own, so a single late run doesn't leave anything to tidy up.

Three URLs for every job

• /ping/<token>: the run finished and went well.
• /ping/<token>/start: a run has started. It's recorded in the check history so you can see when each run began, and doesn't change the deadline.
• /ping/<token>/fail: the run failed. The monitor goes down straight away instead of waiting for the deadline. Add ?msg=disk%20full and the message is included in the alert.

Every URL accepts GET, POST and HEAD, so curl, wget, a language's HTTP client or a webhook from another service all work.

Example: a nightly backup

This crontab line runs a backup at 02:00 and reports success or failure:

0 2 * * * /usr/local/bin/backup.sh \
  && curl -fsS -m 10 --retry 3 https://uptimedog.makingstuffs.com/ping/YOUR-TOKEN \
  || curl -fsS -m 10 --retry 3 https://uptimedog.makingstuffs.com/ping/YOUR-TOKEN/fail

Set the monitor to expect a ping every 24 hours with a grace period that covers how long the backup can take, say 30 minutes. If the server is off, cron is broken or the script hangs, you hear about it 24 and a half hours after the last good run.

To record start times too, call https://uptimedog.makingstuffs.com/ping/YOUR-TOKEN/start as the first line of the script.

Choosing the period and grace

Set the period to the job's schedule: an hourly job expects a ping every hour. Set the grace to the longest the job might reasonably take, plus a margin for a slow network. Too little grace gives false alarms on a busy night; too much delays the alert when something really is wrong. Not sure what a cron schedule means? Paste it into the cron expression explainer.

What else heartbeats are good for

• Queue workers and consumers that should process something every few minutes.
• Data imports, exports and report generation.
• Certificate renewals, database dumps and log rotation.
• Anything behind a firewall that Uptime Dog can't reach, but that can make an outbound HTTPS request.

Heartbeat monitors count towards your monitor limit like any other: Free 20, Essentials 50, Pro 200 and Business 1,000 monitors. Alerts go to any of your alert channels or to an escalation policy.