Heartbeat Monitoring

Monitor your cron jobs, scheduled tasks, and background processes with heartbeat pings.

Heartbeat monitoring ensures that your cron jobs, scheduled tasks, and background processes are running as expected. Instead of checking if your services are up, heartbeats wait for your jobs to "ping" them when they run, start, or complete.

How Heartbeats Work

Creating Your First Heartbeat

In your dashboard, go to Heartbeats and click "Create Heartbeat". Fill in:

• Heartbeat Name — Descriptive name (e.g., "Daily Database Backup")
• Project — Select the project this heartbeat belongs to
• Cron Schedule — When your job is expected to run (e.g., 0 2 * * *)
• Grace Period — How long to wait before alerting (60–86400 seconds)

Cron Schedules

Heartbeats use standard cron expression format: minute hour day month weekday

* * * * *        # Every minute
30 * * * *       # Every hour at :30
30 2 * * *       # Daily at 2:30 AM
0 0 * * 0        # Weekly on Sunday at midnight
0 3 1 * *        # Monthly on the 1st at 3 AM
0 0 1 1 *        # Yearly on January 1st

Fields

Special Characters

• * — Any value (wildcard)
• , — Multiple values (e.g., 1,15)
• - — Range (e.g., 1-5 for Mon–Fri)
• / — Step values (e.g., */5 for every 5 units)

Grace Periods

The grace period determines how long Upcron.io waits after the expected ping time before creating an incident.

Heartbeat URLs

Each heartbeat provides three unique URLs:

Implementation Examples

Bash

#!/bin/bash

# Start ping (optional)
curl -m 10 --retry 5 https://ping.upcron.io/heartbeat/YOUR-UUID/start

# Your actual job
if backup_database.sh; then
    curl -m 10 --retry 5 https://ping.upcron.io/heartbeat/YOUR-UUID
else
    curl -m 10 --retry 5 https://ping.upcron.io/heartbeat/YOUR-UUID/fail
fi

Python

import requests, sys

HEARTBEAT_URL = "https://ping.upcron.io/heartbeat/YOUR-UUID"

try:
    requests.get(f"{HEARTBEAT_URL}/start", timeout=10)
    result = run_backup_job()

    if result.success:
        requests.get(HEARTBEAT_URL, timeout=10)
    else:
        requests.get(f"{HEARTBEAT_URL}/fail", timeout=10)
except Exception:
    requests.get(f"{HEARTBEAT_URL}/fail", timeout=10)
    sys.exit(1)

Node.js

const HEARTBEAT_URL = 'https://ping.upcron.io/heartbeat/YOUR-UUID';

async function runJob() {
    try {
        await fetch(`${HEARTBEAT_URL}/start`);
        const result = await performBackup();
        await fetch(result.success ? HEARTBEAT_URL : `${HEARTBEAT_URL}/fail`);
    } catch (error) {
        await fetch(`${HEARTBEAT_URL}/fail`);
        process.exit(1);
    }
}

runJob();

PHP

<?php

$url = "https://ping.upcron.io/heartbeat/YOUR-UUID";
$ctx = stream_context_create(['http' => ['timeout' => 10]]);

try {
    file_get_contents("$url/start", false, $ctx);
    $result = performBackup();
    file_get_contents($result['success'] ? $url : "$url/fail", false, $ctx);
} catch (Exception $e) {
    file_get_contents("$url/fail", false, $ctx);
    exit(1);
}

Best Practices

Always Handle Failures

#!/bin/bash
set -e
trap 'curl https://ping.upcron.io/heartbeat/YOUR-UUID/fail' ERR

perform_backup.sh
generate_report.py

curl https://ping.upcron.io/heartbeat/YOUR-UUID

Use Descriptive Names

Choose clear names: "Daily Customer Database Backup", "Hourly Log Processing Job" — not "Backup Job" or "Script 1".

Troubleshooting