Cron Heartbeat

Cron Heartbeat monitors your scheduled jobs by expecting periodic “heartbeat” pings. If a job fails to report in within its expected window, CheckOps alerts you before the consequences cascade.

Plan requirement: OPS and above.

HOW IT WORKS

Unlike traditional monitors that actively check an endpoint, Cron Heartbeat works passively:

1. Create a heartbeat monitor — Define the expected schedule (e.g., every 5 minutes, daily at 02:00)
2. Get a unique endpoint — CheckOps provides a unique URL for the job to ping
3. Instrument your job — Add a ping at the end of your job’s execution
4. Alert on miss — If CheckOps does not receive a ping within the grace period, an alert fires

CREATING A HEARTBEAT MONITOR

Field	Description	Example
name	Job description	Database backup
schedule	Cron expression or interval	0 2 * * * or every 5m
grace_period	Time after expected execution before alerting	300 (seconds)
timezone	IANA timezone for cron expression	Europe/Paris

SUPPORTED SCHEDULE FORMATS

Cron expressions:

0 2 * * *        → Daily at 02:00
*/5 * * * *      → Every 5 minutes
0 0 * * 1        → Every Monday at midnight
0 */6 * * *      → Every 6 hours

Interval shorthand:

every 1m         → Every minute
every 5m         → Every 5 minutes
every 1h         → Every hour
every 12h        → Every 12 hours
every 1d         → Every day

INSTRUMENTING YOUR JOBS

After creating a heartbeat monitor, you receive a unique endpoint:

https://api.checkops.eu/api/toolbox/cron/{monitor_id}/ping

BASH / SHELL

backup.sh

#!/bin/bash
pg_dump mydb > /backups/mydb_$(date +%Y%m%d).sql

# Ping CheckOps on success
curl -fsS --max-time 10 \
  https://api.checkops.eu/api/toolbox/cron/abc123/ping

PYTHON

import requests

def run_job():
    # ... your job logic ...
    pass

if __name__ == "__main__":
    run_job()
    requests.get("https://api.checkops.eu/api/toolbox/cron/abc123/ping", timeout=10)

KUBERNETES CRONJOB

apiVersion: batch/v1
kind: CronJob
metadata:
  name: db-backup
spec:
  schedule: "0 2 * * *"
  jobTemplate:
    spec:
      template:
        spec:
          containers:
            - name: backup
              image: postgres:16
              command:
                - /bin/sh
                - -c
                - |
                  pg_dump $DATABASE_URL > /backups/dump.sql && \
                  curl -fsS https://api.checkops.eu/api/toolbox/cron/abc123/ping
          restartPolicy: OnFailure

PING STATUS REPORTING

You can report the job outcome in the ping:

# Report success
curl https://api.checkops.eu/api/toolbox/cron/abc123/ping?status=ok

# Report failure (still counts as "alive" but logs the failure)
curl https://api.checkops.eu/api/toolbox/cron/abc123/ping?status=fail

# Report with duration
curl https://api.checkops.eu/api/toolbox/cron/abc123/ping?status=ok&duration=42s

ALERT BEHAVIOR

Scenario	Result
Ping received on time	Status: UP
Ping received late (within grace)	Status: UP (with warning)
No ping within schedule + grace	Status: DOWN, alert fires
Ping with status=fail	Status: DEGRADED, alert fires