Heartbeat Monitoring

Overview

Heartbeat monitoring works differently from other health check types. Instead of upti.my reaching out to check your service (pull-based), your service sends periodic signals to upti.my (push-based). If an expected heartbeat is not received within the configured window, upti.my 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

upti.my supports two ways to use Heartbeats depending on how much visibility your job needs.

How It Works

1. Create a heartbeat check in upti.my 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. upti.my 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:

https://heartbeats.upti.my/v1/monitors/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 upti.my 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. Any HTTP method works, but GET and POST are most common.

Using curl

# Simple heartbeat ping
curl -s https://heartbeats.upti.my/v1/monitors/your-token

# Heartbeat with custom body (e.g., job result)
curl -s -X POST \
  -H "Content-Type: application/json" \
  -d '{"status":"completed","records_processed":1500}' \
  https://heartbeats.upti.my/v1/monitors/your-token

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://heartbeats.upti.my/v1/monitors/your-token

In Application Code

import requests

def run_scheduled_task():
    # Your task logic here
    process_data()

    # Send heartbeat on completion
    requests.get(
        "https://heartbeats.upti.my/v1/monitors/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://heartbeats.upti.my/v1/monitors/your-token?stepKey=backup_started"

# Step 2: files uploaded
curl -s "https://heartbeats.upti.my/v1/monitors/your-token?stepKey=upload_complete"

# Step 3: verification finished
curl -s "https://heartbeats.upti.my/v1/monitors/your-token?stepKey=verification_complete"

Validation Rules

Each job-chain step can validate incoming data before accepting the heartbeat as successful. Rules can inspect query parameters, headers, or request bodies.

Supported operators include equals, not_equals, contains, regex, exists, greater_than, and less_than. Rules can be marked required when they must pass for the step to be accepted.

curl -s -X POST \
  -H "Content-Type: application/json" \
  -d '{"status":"ok","records_processed":1500}' \
  "https://heartbeats.upti.my/v1/monitors/your-token?stepKey=verification_complete&exit_code=0"

Timing and Thresholds

Heartbeats are schedule-aware. Beyond the base period, you can tune how forgiving the monitor should be and how quickly it changes state.

Response Data

Each received heartbeat is recorded with comprehensive metadata:

Activity Snapshot

In the heartbeat activity view, upti.my 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

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