CronKeeper User Guide

Cron job monitoring with dead-man switch, start/complete tracking, exit code reporting, and status badges.

1. Enable CronKeeper in the Products page

2. Navigate to cron.microgemlabs.ai (or cronkeeper.io)

3. Click + New Check to create your first monitor

4. Add a ping call to your cron job (see Integration below)

Simple

The most basic type. Your job pings the URL when it completes. If no ping arrives within the expected interval plus grace period, CronKeeper alerts.

# Add to the end of your cron job
curl -fsS https://cron.microgemlabs.ai/api/ping/YOUR_CHECK_UUID

Start/Complete

Tracks both when the job starts and when it finishes. This measures execution duration and detects hung jobs — if a /start ping arrives but /complete never comes within the expected duration, CronKeeper alerts.

# At the start of your job
curl -fsS https://cron.microgemlabs.ai/api/ping/YOUR_CHECK_UUID/start

# Your job runs here...
./backup.sh

# When complete
curl -fsS https://cron.microgemlabs.ai/api/ping/YOUR_CHECK_UUID/complete

Exit Code

Reports the job's exit code along with the ping. CronKeeper marks the check as failed if the exit code is non-zero. You can also send duration in the payload.

./my-job.sh
EXIT_CODE=$?
curl -fsS -X POST https://cron.microgemlabs.ai/api/ping/YOUR_CHECK_UUID/complete \
  -H "Content-Type: application/json" \
  -d "{\"exitCode\": $EXIT_CODE}"

For non-zero exit codes, use the /fail endpoint:

curl -fsS -X POST https://cron.microgemlabs.ai/api/ping/YOUR_CHECK_UUID/fail \
  -H "Content-Type: application/json" \
  -d "{\"exitCode\": $EXIT_CODE, \"duration\": 12340}"

Cron Expression

Standard 5-field cron format: minute hour day-of-month month day-of-week

Examples:

Simple Interval

Specify a fixed interval in minutes (e.g., every 15 minutes). Simpler than cron expressions for regular intervals.

Manual Timeout

No schedule — just "alert if no ping arrives within N minutes." Use for jobs triggered by external events rather than a fixed schedule.

cURL (simplest)

Add to the end of your crontab entry:

*/5 * * * * /path/to/job.sh && curl -fsS https://cron.microgemlabs.ai/api/ping/UUID

The -f flag makes curl exit with a non-zero code on HTTP errors. -s suppresses progress output. -S shows errors.

Shell Wrapper (recommended)

The cronkeeper-exec wrapper handles start/complete/fail pings, exit codes, and duration automatically:

# Install
curl -o /usr/local/bin/cronkeeper-exec https://cron.microgemlabs.ai/cli/cronkeeper-exec
chmod +x /usr/local/bin/cronkeeper-exec

# Use in crontab
*/5 * * * * cronkeeper-exec UUID -- /path/to/job.sh

What it does:

1. Pings /start

2. Runs your command

3. If exit code is 0: pings /complete with duration

4. If exit code is non-zero: pings /fail with exit code and duration

HTTP Libraries

For applications that make HTTP calls, ping from within your code:

await fetch('https://cron.microgemlabs.ai/api/ping/UUID')

import requests
requests.get('https://cron.microgemlabs.ai/api/ping/UUID', timeout=10)

http.Get("https://cron.microgemlabs.ai/api/ping/UUID")

{
  "exitCode": 0,
  "duration": 12340
}

All ping endpoints return 200 OK immediately. Processing happens asynchronously. If the endpoint is unreachable, pings are retried automatically by the -retry 3 flag in curl.

Embed a live status badge in your README, wiki, or documentation:

![Backup Status](https://cron.microgemlabs.ai/api/badge/UUID.svg)

• ?style=flat (default)
• ?style=flat-square
• ?style=for-the-badge

• ?label=Nightly%20Backup

The badge shows the check name, current status (up/late/down/paused), and 30-day uptime percentage. It refreshes every 30 seconds (10 seconds during incidents).

For Start/Complete and Exit Code checks, MicroGemAI extrapolates duration trends over 48 hours of data. Example: "Backup job duration increasing at 2min/day. At this rate, it will exceed the grace period in 5 days." Enable in Anomalies → Detection Settings → toggle Prediction on. Only generates predictions when the trend is reliable (R² > 0.3) and degrading.

Define automated responses to missed pings (Skills → Runbook (/agent/skills?type=runbook)). Example: create a "Restart Backup Service" template that POSTs to your orchestration API when CronKeeper detects the backup cron has missed 3 consecutive pings. Set the trigger pattern to match specific check names or error messages. Three trust levels: manual (suggestion only), auto-approval (AI triggers, human approves), full auto (AI handles everything).

When cron incidents resolve (lasting 5+ minutes), MicroGemAI auto-generates a postmortem with timeline of missed pings, duration trends leading up to the failure, cross-product correlation (e.g., was the server overloaded?), and prioritized action items. Review, edit, and publish at Ops → Postmortems.

When a check transitions to DOWN, CronKeeper creates an incident and routes it through your team's escalation policy — the same on-call engine used by all MicroGemLabs products. Configure on-call at microgemlabs.ai/oncall.

For checks using Start/Complete or Exit Code tracking, MicroGemAI monitors execution duration trends. If a cron job starts taking significantly longer than its 7-day baseline, an anomaly alert fires — even if the job is still completing within the grace period. This catches problems like growing database tables or degrading network connections before they cause missed pings.

Configure sensitivity from the Anomalies page (Ops → Anomalies).

Suppress CronKeeper alerts during planned maintenance by creating a maintenance window (Ops → Maintenance). Pings are still accepted and recorded, but missed-ping detection won't fire incidents or trigger on-call. Scope suppression globally, to CronKeeper only, or to a specific check.