Heartbeat monitoring detects scheduled work that stops reporting success. Instead of requesting a public webpage, the monitoring service waits for a signal from a job. If the expected signal does not arrive before its deadline, it can alert the person responsible.
This is useful for cron jobs, database backups, scheduled reports, data imports and background maintenance. These tasks can fail quietly while the main website continues responding normally. A healthy homepage does not prove that last night’s backup exists.
The key is to make the heartbeat represent something meaningful: successful completion of the work you care about, not merely the launch of a command.
Why ordinary uptime checks miss scheduled-job failures
Website monitoring checks a reachable endpoint. A scheduled task may have no public endpoint at all. It can also depend on a scheduler, environment variables, storage permissions and external services that are unrelated to the homepage.
A backup can fail because its destination is full while the application keeps serving cached pages. A report can stop arriving because a deployment removed its scheduler entry. An import can run but produce no usable output.
Host monitoring and application logs help investigate those problems, but neither automatically proves that the task completed. A heartbeat adds a direct signal about the job’s expected outcome.
How heartbeat monitoring works
The basic workflow has four parts:
- Create a monitor for one identifiable task.
- Define when its completion signal should arrive.
- Send the heartbeat after the task meets its success criteria.
- Alert when the completion deadline is missed.
Some monitoring systems support additional start and failure signals, execution-duration tracking or calendar schedules. Others use an interval measured from the most recent heartbeat. Check your monitor’s documented behavior before choosing deadlines.
The heartbeat monitoring guide explains the use case, while the setup documentation describes configuration for Upty.
Decide what “successful” means before adding a ping
For a simple cleanup job, a zero exit code may be an acceptable starting signal. For a backup, the definition should be stronger. Consider whether the backup artifact was created, whether it reached the intended storage and whether basic verification passed.
A command can finish successfully while doing the wrong thing. A script that catches an error and then exits zero will make a completion ping look healthy. Review error handling and verify that failures propagate to the wrapper or scheduler.
For an asynchronous backup service, a successful request may only mean the provider accepted the job. If completion matters, send the heartbeat after the provider confirms the backup finished, not immediately after submission.
Keep restore testing separate. A completion heartbeat is evidence that the instrumented workflow reached its success condition; it does not prove that a backup can restore an application. Perform periodic restores into an appropriate test environment and monitor that verification process too.
Send the heartbeat after completion
Place the signal in the same execution path as the job’s final success check. The following shell example illustrates the structure; the heartbeat address must come from your own monitor’s configuration:
#!/bin/sh
set -eu
: "${UPTY_HEARTBEAT_URL:?Set the URL from your monitor}"
/usr/local/bin/run-backup-and-verify
curl --fail --silent --show-error \
--connect-timeout 5 --max-time 15 \
"$UPTY_HEARTBEAT_URL"
Here, the backup-and-verification command must return a nonzero exit status when it fails. Because the script stops on that failure, the completion signal is not sent. The command name is an example: replace it with your actual backup workflow.
A network error during the heartbeat request is a different failure. The backup may have succeeded even though the monitor never received the signal. Inspect backup output and delivery logs when investigating a missed heartbeat rather than immediately assume data was lost.
Treat a unique heartbeat address as a secret. Someone who can submit a success signal may be able to make a failed job appear healthy. Keep the address out of source control, shared screenshots and public logs, and use the credential-management practices appropriate to your environment.
Choose a deadline that matches the schedule
A task that runs every five minutes needs different expectations from a nightly backup. Include normal runtime and a reasonable allowance for scheduling or delivery delays. Avoid choosing a grace period so long that a missed daily job remains unnoticed until the following day.
For example, a nightly backup begins at 02:00 and normally finishes by 02:20. A calendar-aware monitor could expect completion by a later deadline such as 02:40. This is an illustrative schedule, not a universal recommendation. Set the allowance using observed runtime and the time your team needs to respond.
If the monitor measures time since the last ping, calculate the interval with care. An unusually early completion can change when the next deadline falls. Confirm how weekends, skipped runs, retries and manual executions affect the monitor.
Specify the scheduler’s timezone and keep it aligned with monitoring expectations. Cron implementations can differ, especially around daylight-saving transitions. Consult your platform’s documentation; the Linux crontab manual describes scheduling behavior for its implementation.
Test both success and failure
A useful setup test does more than send a manual ping:
- Run the real task and verify that successful completion updates the monitor.
- In a controlled test, make the job fail before its success condition.
- Confirm that no completion heartbeat is sent for that failed run.
- Let a test deadline pass and verify alert delivery.
- Restore the task and confirm that recovery is recorded as expected.
Use disposable test data or a separate test task rather than interrupt a production backup just to validate monitoring. Document how to distinguish a task failure from a notification-delivery failure.
Follow the alert configuration guide to route missed-run notifications to someone who can investigate. Give each monitor a descriptive name, an owner and instructions for finding the scheduler, logs and backup artifacts.
Common mistakes that hide failures
Pinging at startup only. A startup signal proves the scheduler launched something. It does not establish that the task finished. Use completion signals for completion monitoring.
Sharing one heartbeat between unrelated jobs. A healthy task can keep resetting the timer while another task fails. Give independent workflows independent monitors.
Using an unconditional final ping. Error traps or cleanup blocks may run after failure. Ensure the success signal is conditional on the actual success criteria.
Letting manual runs hide missed scheduled runs. An ad hoc execution can reset an interval-based monitor. Decide whether manual verification needs a separate monitor or a documented interpretation.
Ignoring overlapping executions. A new run may start before the previous one ends. Use scheduler or application controls appropriate to the job, and inspect whether an old run’s late heartbeat can obscure a newer problem.
A practical starting point
Choose one critical task, define a measurable success condition and add a completion heartbeat with a realistic deadline. Test failure detection before adding more monitors. Use the monitoring directory to pair that job signal with website, host and log checks where they add context.
For the broader distinction between external checks and service availability, read what uptime monitoring measures.
Frequently asked questions
Does a heartbeat prove my backup is restorable?
No. It proves only that your configured success path sent a signal. Add backup verification and periodic restore tests to assess whether the data is usable.
What if the job succeeds but the heartbeat cannot be delivered?
The monitor may report a missed run. Check the task’s output and the network request separately. Bound retries and request timeouts so notification delivery cannot leave a job hanging indefinitely.
Can I monitor a task without exposing my server publicly?
A job can send an outbound heartbeat without offering an inbound public endpoint. It still needs network access to the monitoring service and secure handling of its heartbeat address.