Heartbeat patterns: start, complete, and grace periods that work

Heartbeat monitoring flips the usual model: instead of Spectra reaching out to check your service, your job reaches in to say “I ran.” It’s the only reliable way to catch a scheduled task that fails to fire at all — but a naive setup either misses failures or cries wolf. Here are the patterns that get it right.

Ping on success, not just at the end

The simplest heartbeat pings a URL when the job finishes. That catches a job that didn’t run — but not a job that ran and failed. Better is a start/complete pattern:

• Ping ?status=start when the job begins.
• Ping ?status=complete when it finishes successfully.
• Ping ?status=fail (or skip the complete) when it errors.

Now you can tell apart three states: never ran, still running, and ran-but-failed — each of which deserves a different response.

Set the grace period to match reality

A nightly backup scheduled for 02:00 never runs at exactly 02:00, and its duration varies. The grace period is how long after the expected time Spectra waits before declaring the beat missed. Too short and normal variance pages you; too long and you learn about a failure hours late. Size it to the job’s real-world jitter — a backup that usually takes 20 minutes and sometimes 40 wants a grace period comfortably past the worst case, not a tight five minutes.

Catch the job that runs forever

A job that hangs is as broken as one that dies — and start/complete catches it. If you see a start with no complete within the max expected duration, alert. A sync that normally finishes in ten minutes and has been “running” for two hours is stuck, and you want to know before the next run piles on top of it.

Keep the ping honest

• Put the ping at the very end of the success path, after the work is actually done — not at the top of the script, or you’ll report success for a job that crashed halfway.
• Use curl -fsS (fail on HTTP errors, silent, show errors) so a failed ping doesn’t hide in the logs.
• The unique URL is the secret — no extra auth needed — so keep it out of public repos.

The bottom line

Good heartbeat monitoring is about modeling the job honestly: signal start and completion so you can distinguish failure modes, set a grace period to the job’s real variance, and alert on jobs that run too long. Do that and silent cron failures stop being the outage you find out about from a customer.

Add a heartbeat to any job. Explore heartbeat monitoring →