cron-monitor

name

cron-monitor

description

Send heartbeat pings to cron-monitor after cron job completion, check job status, and register new jobs. Use when you need to confirm a scheduled task ran successfully, check if a cron job is healthy, or add monitoring to a new cron script. Triggers include "ping cron-monitor", "check job status", "register cron job", "heartbeat", "cron health check", or any task involving scheduled job monitoring.

cron-monitor

Send heartbeat pings and check scheduled job health.

When to use

• After a cron job runs successfully (send a ping to confirm completion)
• Checking whether a scheduled job is healthy or has missed its window
• Registering a new job to be monitored
• Investigating why an alert fired

Prerequisites

1. A running cron-monitor server
2. An API key (cm_...) from the server admin
3. The cm CLI installed, or use curl directly

Quick Start (CLI)

# Install CLI globally
npm install -g @cron-monitor/cli

# Configure
cm config set server https://monitor.example.com
cm config set key cm_...

# Send a ping after your cron job succeeds
/path/to/script.sh && cm ping daily-backup

Sending pings via curl (no CLI required)

# Simple success ping
curl -s "https://monitor.example.com/api/ping/daily-backup?key=cm_..."

# Ping with duration (milliseconds)
curl -s -X POST "https://monitor.example.com/api/ping/daily-backup?key=cm_..." \
  -H "Content-Type: application/json" \
  -d '{ "durationMs": 4250, "exitCode": 0 }'

# Failure ping
curl -s -X POST "https://monitor.example.com/api/ping/daily-backup?key=cm_..." \
  -H "Content-Type: application/json" \
  -d '{ "status": "failure", "exitCode": 1, "output": "Connection timeout" }'

Checking job status

# List all jobs
cm list

# List only failing/missed jobs
cm list --status failing
cm list --status missed

# JSON output (for scripting)
cm list --json | jq '.[] | select(.status != "healthy")'

Registering a new job

cm register \
  --name "Daily Backup" \
  --schedule "0 3 * * *" \
  --grace 5

# With timezone
cm register --name "Morning Report" --schedule "0 9 * * 1" --tz "America/New_York"

CLI Reference

Command	Description
cm ping <slug>	Send success ping
cm ping <slug> --fail	Send failure ping
cm ping <slug> --duration <ms>	Ping with execution duration
cm ping <slug> --exit-code <n>	Ping with exit code
cm list	List all jobs with status
cm list --status <status>	Filter by status: healthy, missed, failing, paused
cm register	Register a new job
cm config set server <url>	Set server URL
cm config set key <cm_...>	Set API key
cm config show	Show current config

Adding monitoring to a cron script

#!/bin/bash
# /etc/cron.d/daily-backup

set -euo pipefail
START=$(date +%s%3N)

# Your backup command
/usr/local/bin/backup.sh

# Send success ping with duration
DURATION=$(( $(date +%s%3N) - START ))
curl -sf "https://monitor.example.com/api/ping/daily-backup?key=cm_..." \
  -d "{\"durationMs\": $DURATION}" -H "Content-Type: application/json"

Environment Variables

Variable	Description
CM_SERVER	Server URL (overrides config file)
CM_KEY	API key (overrides config file)

Troubleshooting

"404 Not Found" on ping URL

The job slug does not exist. Register the job first with cm register or in the dashboard.

"401 Unauthorized"

API key is invalid or revoked. Check with cm config show and verify with the server admin.

Job shows as "missed" but the script ran

The ping URL was not called after the job, or the ping failed silently. Check that the curl/cm command in your script has no silent failure (|| true) masking errors.