Monitoring Cron Jobs with Maintenant: A Practical Guide

Cron jobs are the most silently dangerous services in your infrastructure. When a backup job fails, nothing alerts you – until the day you actually need that backup.

Maintenant includes a heartbeat system designed to solve exactly this problem.

The heartbeat principle

The idea is simple: after each successful run, your cron job sends a “ping” to a unique URL. Maintenant knows how often that ping should arrive. If the ping doesn’t come within the expected window, you get alerted.

Configuration in Maintenant

Create a heartbeat monitor via the API:

curl -X POST http://localhost:8080/api/v1/heartbeats \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Backup PostgreSQL",
    "interval_seconds": 86400,
    "grace_seconds": 3600
  }'

Maintenant returns a unique UUID. Use it in your scripts:

Heartbeat monitoring: cron jobs, durations, exit codes

# backup.sh
#!/bin/bash
set -o pipefail

# Notify job start
curl -fsS -o /dev/null http://localhost:8080/ping/${UUID}/start

# Run the backup, keeping the exit code
rc=0
pg_dump -h postgres -U app mydb | gzip > /backups/mydb-$(date +%Y%m%d).sql.gz || rc=$?

# Notify completion with exit code
curl -fsS -o /dev/null http://localhost:8080/ping/${UUID}/$rc
exit $rc

Start/end signals

The /start signal is optional but powerful. It allows Maintenant to:

Measure the duration of each run
Detect jobs that start but never finish (timeout, deadlock)
Track duration trends over time

Exit codes

By appending the exit code (/$rc above) to the ping URL, you pass the result of the job. A non-zero code is recorded as a failure, even if the ping arrives on time.

Docker integration

For cron jobs running inside Docker containers:

services:
  backup:
    image: postgres:16
    entrypoint: /bin/bash
    command: >
      -c "set -o pipefail;
          pg_dump -h postgres -U app mydb | gzip > /backups/daily.sql.gz;
          wget -qO- http://maintenant:8080/ping/YOUR-UUID/$$?"

Best practices

One heartbeat per critical job – backup, cleanup, certificate renewal, sync
Generous grace period – if your backup usually takes 5 minutes, set a 30-minute grace period
Use start/end signals – to detect stuck jobs
Pass the exit code – a job that “succeeds” with an error code is not a success

Install Maintenant –> · Compare editions →