Monitoring
Heartbeat Monitoring
Push-based monitoring for cron jobs, batch processes, and scheduled tasks. Get alerted when expected heartbeats are missed.
Overview
Heartbeat monitoring works differently from other health check types. Instead of Uptimy reaching out to check your service (pull-based), your service sends periodic signals to Uptimy (push-based). If an expected heartbeat is not received within the configured window, Uptimy triggers an alert.
This is the ideal monitoring approach for cron jobs, batch processes, scheduled tasks, background workers, data pipelines, and any process that runs on a schedule. These workloads cannot be effectively monitored with pull-based checks because there is no persistent endpoint to probe.
Heartbeat Modes
Uptimy supports two ways to use Heartbeats depending on how much visibility your job needs.
| Mode | Best For | Behavior |
|---|---|---|
| Single ping | Simple cron jobs and one-step scheduled tasks | One ping per run. If the expected ping does not arrive within the configured period plus grace window, the heartbeat becomes unhealthy. |
| Job chain | Multi-stage jobs, imports, pipelines, and long-running tasks | Each run can send named steps, optionally enforce step order, and check the query parameters or X- headers each step sends before the monitor marks the run successful. |
How It Works
- Create a heartbeat check in Uptimy and receive a unique ping URL
- Configure your cron job or scheduled task to send an HTTP request to the ping URL after each successful run
- Uptimy records each heartbeat and tracks whether they arrive on time
- If a heartbeat is missed (not received within the expected interval), an alert is triggered
Ping URL
Each heartbeat check has a unique URL that your service pings:
https://ping.upti.my/your-tokenReplace your-token with the unique token assigned to your heartbeat check. You can find this token in your check's configuration page in the Uptimy dashboard.
The ingest endpoint accepts GET, POST, and HEAD requests, so you can integrate it from shell scripts, app code, workers, and third-party schedulers.
Sending Heartbeats
Sending a heartbeat is as simple as making an HTTP request to your ping URL. Only GET, POST, and HEAD requests are accepted, with GET and POST being the most common.
Using curl
# Simple heartbeat ping
curl -s https://ping.upti.my/your-token
# Heartbeat with extra context for the run
curl -s "https://ping.upti.my/your-token?records_processed=1500&duration=42"Query parameters and X- headers are recorded with the run. Uptimy never reads or stores the request body, so put extra context, such as records processed or how long the job took, in query parameters.
In a Cron Job
# Run backup script every day at 2 AM, then ping heartbeat
0 2 * * * /usr/local/bin/backup.sh && curl -s https://ping.upti.my/your-tokenPing on Success Only
Use && in your cron command to only send the heartbeat if the preceding command succeeds. This way, a failed job will also result in a missed heartbeat, triggering an alert for both job failures and jobs that did not run at all.
In Application Code
import requests
def run_scheduled_task():
# Your task logic here
process_data()
# Send heartbeat on completion
requests.get(
"https://ping.upti.my/your-token",
timeout=10
)Job Chain Steps
When a heartbeat is configured as a job chain, each request can identify which step is being reported by including a step key in the query string.
# Step 1: backup started
curl -s "https://ping.upti.my/your-token?stepKey=backup_started"
# Step 2: files uploaded
curl -s "https://ping.upti.my/your-token?stepKey=upload_complete"
# Step 3: verification finished
curl -s "https://ping.upti.my/your-token?stepKey=verification_complete"Enforce Step Order
For multi-stage jobs, you can require steps to arrive in sequence. This prevents a run from looking healthy when downstream events arrive before required earlier stages.
Validation Rules
Each job-chain step can have Validation rules. A rule checks one value in the ping that reports the step, from the query string or from the ping's X- headers.
| Source | What the rule reads |
|---|---|
| Query | A query parameter in the ping URL, such as exit_code or duration. The name must match exactly, including case. |
| X- header | A request header whose name starts with X-, such as X-Exit-Code. Enter the full header name; its case doesn't matter. |
Proxy and credential headers are never kept, so a rule can't read them: X-Forwarded-For, X-Forwarded-Proto, X-Forwarded-Host, X-Forwarded-Port, X-Forwarded-Scheme, X-Real-IP, X-Request-ID, X-Scheme, X-Requested-With and X-Api-Key.
The operators are Equals, Not equals, Contains, Regex, Exists, Greater than and Less than. Greater than and Less than compare numbers, and fail for a value that isn't one. A rule fails when its field is missing, except Exists, which checks just that.
Turn on Required for a rule that must pass. When a required rule fails, the whole run fails and counts toward the Failure threshold. A rule that isn't required only shows its result on the run.
curl -s -H "X-Environment: production" \
"https://ping.upti.my/your-token?stepKey=verification_complete&exit_code=0"Timing and Thresholds
Heartbeats are schedule-aware. These settings are under Timing on the heartbeat's Configuration tab.
| Setting | Description |
|---|---|
| Schedule | Every: a fixed period between pings. Cron: set times from a cron expression, in the time zone you pick. No schedule: for jobs that run on demand. Runs are recorded whenever they come and failed runs change the status, but nothing alerts if the job stops running. |
| Period | The expected time between pings, with Every |
| Grace period | Extra time before a ping counts as missed. With Cron, how late a run may be after its scheduled time. |
| Max run time | For a job chain with No schedule: fail a run that hasn't reached its last step this long after its first. A run that starts while another is unfinished always fails the unfinished one. |
| Failure threshold | How many missed or failed runs in a row mark the heartbeat Down (default 1) |
| Recovery threshold | How many successful runs in a row a Down heartbeat needs before it's healthy again (default 1). A failed run in between starts the count again. |
| Pause | Temporarily disables monitoring without deleting configuration or history |
Response Data
Every run is listed under Runs on the heartbeat's Overview tab. Open one to see what was recorded. Source IP, Method, User-Agent, Custom headers and Query parameters come from the ping that ended the run, so a missed run has none of them.
| Field | Description |
|---|---|
| Result | Succeeded or Failed. A missed run counts as failed. |
| Timing | When the ping was received. For a job chain, when the run started and ended, and its duration from the first step's ping to the last. |
| Steps | For a job chain: each step, when it arrived, which required steps are missing, and the result of each validation rule |
| Source IP | The address the ping came from |
| Method | GET, POST or HEAD |
| User-Agent | The ping's User-Agent header |
| Custom headers | The ping's X- headers, except the proxy and credential ones listed under Validation Rules |
| Query parameters | The ping URL's query parameters, except stepKey |
Activity Snapshot
On the heartbeat's Overview tab, Uptimy summarizes the current monitor state so you can quickly see what happened most recently.
- Last ping time
- Next deadline
- Last success and last failure
- Current step when the heartbeat uses a job chain
- Status transitions such as healthy, at risk, down, or paused
Tags
Tag heartbeats like healthchecks, under Details on the heartbeat's Configuration tab. Tags filter the heartbeats list, route alerts in workflow Filter nodes, and scope reports: a report for a tag includes every heartbeat and healthcheck carrying it, including ones you tag later. Heartbeats run by the Uptimy Agent can be tagged too; their tags save as you change them.
On Status Pages
Add a heartbeat to a status page next to your services to show customers that scheduled work runs. Each day's bar is the share of runs on time, and the page shows only the heartbeat's name, status and bars.
Common Use Cases
- Cron Jobs — Monitor database backups, log rotation, report generation, and cleanup scripts
- Batch Processes — Track ETL pipelines, data imports, and batch computations
- Scheduled Tasks — Verify that Windows Task Scheduler or systemd timers run on time
- Background Workers — Monitor queue consumers, email senders, and async processors
- Renewal Jobs — Ensure certificate renewals, token rotations, and license checks execute
Network Reliability
If the heartbeat request fails due to a transient network issue, the heartbeat is missed and may trigger a false alert. Consider adding retry logic to your heartbeat pings, especially for critical jobs. A simple retry with a short delay can prevent most false positives.
Recommended Setup Pattern
Use a single heartbeat for short, one-step jobs. Use job chains for any workflow where stage order, completion evidence, or validating the values each step sends matters.