cron-monitor

# 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)

```bash
# 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)

```bash
# 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

```bash
# 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

```bash
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

```bash
#!/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.