How to monitor a cron job with a heartbeat: a step-by-step example

A cron job runs without anyone watching it. If it stops working, you usually find out when a client asks why last night's backup is missing. A heartbeat monitor reverses that. Your job checks in with AperioFlow each time it succeeds. If the check-in does not arrive on time, the monitor raises an alert.

This walkthrough uses a nightly backup script that runs at 02:00. The same steps work for any scheduled job.

Create the heartbeat and copy the ping URL

In AperioFlow, create a heartbeat. Give it a name that says which job it watches, such as nightly-db-backup. A clear name matters when the alert arrives at an odd hour.

Set the expected interval to match the schedule. For a job that runs once a day, use 24 hours. Add a grace period for runs that take longer than usual. For a 02:00 job, 30 minutes is a sensible start.

When you save, the heartbeat shows a ping URL. Copy it. Anyone with that URL can send a check-in, so keep it out of public repositories and shared documents.

On the server, add the URL to the top of your crontab as a variable:

PING_URL=paste-your-ping-url-here

Keeping the URL in a variable means you change it in one place if you ever replace the heartbeat.

Add a curl call to the end of the crontab line

Your current entry probably looks like this:

0 2 * * * /usr/local/bin/backup.sh

Add a curl call after the script:

0 2 * * * /usr/local/bin/backup.sh && curl -fsS -m 10 --retry 3 $PING_URL > /dev/null

The flags do the following:

• -f makes curl fail on an HTTP error, so a rejected ping shows up as a failure.
• -sS hides the progress bar but still prints errors.
• -m 10 gives up after 10 seconds, so a slow network cannot hold the job open.
• --retry 3 tries again three times before giving up.
• > /dev/null discards the response body, so cron does not email you a copy.

If your crontab line contains a percent sign, escape it as \%. Cron treats an unescaped percent sign as a newline.

Only ping on success

The && in the line above is the important part. The curl call runs only if the script exits with status 0. Compare the two forms:

backup.sh ; curl ...    # pings even when the backup fails
backup.sh && curl ...   # pings only when the backup succeeds

The first form hides failures. The monitor stays green because the ping arrives regardless of what the backup did. The second form is what you want.

Your script also needs to exit with a non-zero status when something goes wrong. Many scripts do not do this by default. Add this near the top of the script:

set -e

With set -e, the script stops at the first failing command and reports the failure to cron. Without it, a script can print an error, carry on, and still exit with status 0.

A job that hangs will not ping either. That is the behaviour you want. The grace period gives slow runs some room before the alert fires.

Test it by stopping the job on purpose

Do not wait for a real failure to find out whether the monitor works. Break the job on purpose.

First, add a line near the top of backup.sh that forces a failure:

exit 1

Run the script by hand and check its exit status:

/usr/local/bin/backup.sh; echo $?

You should see 1. The curl call should not run, so the heartbeat should not record a check-in.

Next, confirm the ping path works on its own. Run this from the server:

PING_URL=paste-your-ping-url-here
curl -fsS -m 10 $PING_URL > /dev/null && echo ok

You should see ok, and the heartbeat should record a check-in. Then remove the exit 1 line and run the script again. It should exit with 0 and check in.

To test the alert itself, make a second heartbeat with a short interval, such as two minutes, and a short grace period. Send one check-in, then wait without sending another. When the window closes, the alert should fire. Delete the test heartbeat afterwards.

Read the alert when it fires

When the monitor raises an alert, it tells you which heartbeat missed its check-in and when it last checked in. Read those two facts first. They tell you how long the job has been silent.

Then work through the problem in this order:

1. Check the job's own log. Look for an error message from the script.
2. Check the cron log on the server to confirm the job actually started at the scheduled time.
3. Check the machine itself. A full disk, a stopped service or a server that was rebooted can stop the job before the script runs.
4. Fix the cause, then run the job by hand.
5. Confirm the heartbeat records a new check-in and returns to its normal state.

Alert emails go only to people in your organisation. Before you rely on a heartbeat, add the people who should receive alerts for that job, and check that they can see the organisation's monitors.

A heartbeat does not tell you why a job stopped. It tells you that it stopped, and when. For a small team, that is often enough to act on quickly, before a client notices.

Start free at https://app.aperioflow.co.uk/#/signup and add a heartbeat for one job in a few minutes. The free plan includes 10 monitors, so you can start with the job that would hurt most if it failed silently.