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.

ModeBest ForBehavior
Single pingSimple cron jobs and one-step scheduled tasksOne ping per run. If the expected ping does not arrive within the configured period plus grace window, the heartbeat becomes unhealthy.
Job chainMulti-stage jobs, imports, pipelines, and long-running tasksEach 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

  1. Create a heartbeat check in Uptimy and receive a unique ping URL
  2. Configure your cron job or scheduled task to send an HTTP request to the ping URL after each successful run
  3. Uptimy records each heartbeat and tracks whether they arrive on time
  4. 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:

Heartbeat Ping URL
https://ping.upti.my/your-token

Replace 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

Curl Example
# 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

Crontab Entry
# 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-token

Ping 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

Python Example
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.

Job Chain Example
# 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.

SourceWhat the rule reads
QueryA query parameter in the ping URL, such as exit_code or duration. The name must match exactly, including case.
X- headerA 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.

Validation Example
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.

SettingDescription
ScheduleEvery: 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.
PeriodThe expected time between pings, with Every
Grace periodExtra time before a ping counts as missed. With Cron, how late a run may be after its scheduled time.
Max run timeFor 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 thresholdHow many missed or failed runs in a row mark the heartbeat Down (default 1)
Recovery thresholdHow 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.
PauseTemporarily 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.

FieldDescription
ResultSucceeded or Failed. A missed run counts as failed.
TimingWhen 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.
StepsFor a job chain: each step, when it arrived, which required steps are missing, and the result of each validation rule
Source IPThe address the ping came from
MethodGET, POST or HEAD
User-AgentThe ping's User-Agent header
Custom headersThe ping's X- headers, except the proxy and credential ones listed under Validation Rules
Query parametersThe 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.