Help & FAQ
Everything you need to get started with CronDoctor and get the most out of your monitoring.
On this page
Cron Job Basics
A cron job is a scheduled task that runs automatically at specified times on Unix-like systems. The schedule is defined by a cron expression — five fields that specify when the job runs.
Cron Expression Format
│ ┌───── hour (0-23)
│ │ ┌───── day of month (1-31)
│ │ │ ┌───── month (1-12)
│ │ │ │ ┌───── day of week (0-6, Sun=0)
│ │ │ │ │
* * * * *
Common Patterns
| Expression | Meaning |
|---|---|
| * * * * * | Every minute |
| */5 * * * * | Every 5 minutes |
| 0 * * * * | Every hour (at minute 0) |
| 0 3 * * * | Every day at 3:00 AM UTC |
| 0 0 * * 0 | Every Sunday at midnight UTC |
| 0 0 1 * * | First day of every month at midnight |
| 30 2 * * 1-5 | Weekdays at 2:30 AM UTC |
Timezones & UTC
All schedules in CronDoctor are evaluated in UTC. If your server or machine uses a different timezone, convert your local time to UTC when setting up the monitor schedule.
Example: Your Mac runs a job at 10:30 AM US Eastern (30 10 * * * in your local crontab). US Eastern is UTC−5, so set the CronDoctor monitor schedule to 30 15 * * * (15:30 UTC).
Daylight saving tip: During DST your ping arrives an hour early — that's fine. CronDoctor only alerts on missing pings, not early ones. Use the later UTC offset (standard time) so you're covered year-round.
How CronDoctor Works
CronDoctor uses a "dead man's switch" approach. Your cron job pings CronDoctor when it runs. If the ping doesn't arrive on time, CronDoctor knows something is wrong. The schedule you set on a monitor tells CronDoctor when to expect the ping — it doesn't run or trigger your job. Your existing scheduler (crontab, Task Scheduler, etc.) handles that.
Your job runs and pings CronDoctor
Add a curl command to your cron job. When the job runs, it sends a ping to your unique endpoint.
Schedule compliance checks run every 60 seconds
CronDoctor compares each monitor's expected ping time against the actual last ping. If a ping is overdue (past the grace period), the monitor state changes to "late" or "down".
Smart alerting classifies severity
Not every missed ping deserves a 2 AM wake-up call. CronDoctor classifies alerts as critical, warning, or info — and suppresses noise based on adaptive thresholds and history.
AI diagnoses the root cause
When your ping includes exit codes, stderr, or duration data, CronDoctor's AI analyzes the failure and provides an actionable diagnosis with a suggested fix.
You get notified
Alerts are sent via email, Slack, Discord, Microsoft Teams, or PagerDuty — with the diagnosis included so you can fix the problem immediately.
Integration Guide
CronDoctor supports three levels of integration. The more data you send, the better the AI diagnosis.
Simple ping
Just confirms the job ran. CronDoctor knows when it ran, but not whether it succeeded.
No exit code, duration, or error data — CronDoctor only knows the job ran.
With metadata
Quick startSends exit code and duration. CronDoctor can detect failures (non-zero exit) and performance degradation.
Exit code and duration visible, but no stderr — AI diagnosis is limited without error output.
Rich payload
Recommended — best AI diagnosisPOST with exit code, duration, and stderr. This gives the AI everything it needs to diagnose the root cause and suggest a specific fix.
sudo systemctl start postgresqlWrap it or embed it
The examples above use shell wrapper scripts, but that's not the only way. If you own the source code of your job (Python, Node, Go, etc.), you can embed the ping directly using an HTTP POST from within your code. This gives you more control — you can send specific error messages from your catch/except blocks, measure duration more precisely, and keep everything in one file.
Rule of thumb: Use a wrapper script for jobs you can't or don't want to modify (legacy scripts, third-party tools, compiled binaries).Embed the ping in jobs where you own the code.
Getting the best AI diagnosis
The AI diagnosis quality depends directly on the data you send:
- Exit code — Tells the AI whether the job failed (non-zero) and how (signal codes like 137 = OOM killed)
- Duration — Detects performance degradation. If a job usually takes 30s but suddenly takes 5 minutes, that's a signal
- stderr — The most valuable piece. Error messages like "disk full" or "connection refused" let the AI pinpoint the exact problem
- stdout — Less critical but can provide context for the AI when stderr alone isn't enough
Additional ping fields
| Field | Type | Description |
|---|---|---|
| signal | string | start, end, complete, or fail |
| exit_code | integer | Process exit code (0 = success) |
| duration | integer | Duration in milliseconds |
| stderr | string | Last 100 lines of stderr output |
| stdout | string | Last 50 lines of stdout output |
| message | string | Short custom message |
Smart Alerting & Adaptive Thresholds
Traditional monitoring sends an alert for every missed ping. CronDoctor is smarter — it learns your jobs' normal behavior and only alerts you when something is genuinely wrong.
Severity Classification
Every alert is classified into one of three levels:
- CRITICALJob is down with multiple consecutive misses, or a failure with a non-zero exit code
- WARNINGFirst missed ping, or job is running significantly slower than usual
- INFOJob recovered after being down, or minor deviation from expected behavior
Adaptive Thresholds
After 10 or more pings with duration data, CronDoctor calculates an adaptive threshold based on the P95 duration plus a 20% buffer. If a job's duration exceeds this threshold, it triggers a warning.
This means CronDoctor automatically adjusts to your job's natural variability. A backup job that normally takes 10-30 seconds won't alert at 35 seconds, but will alert at 2 minutes.
Noise Suppression
CronDoctor suppresses duplicate and low-value alerts. If a monitor is already "down" and stays down, you won't receive repeated alerts for every check cycle. Target noise reduction: 60-80% fewer alerts compared to binary monitoring tools.
Grace Period
Each monitor has a configurable grace period (default: 5 minutes). CronDoctor waits this long after the expected ping time before considering the job late. This prevents false alarms when a job runs a few seconds late due to system load, scheduling jitter, or slow network connections.
Plans & Limits
AI diagnosis and smart alerting are included on every plan, including free.
| Feature | Free | Starter ($19/mo) | Pro ($49/mo) |
|---|---|---|---|
| Monitors | 5 | 20 | 100 |
| Ping history | 7 days | 30 days | 90 days |
| Email alerts | Yes | Yes | Yes |
| Slack alerts | No | Yes | Yes |
| Discord alerts | No | No | Yes |
| Microsoft Teams alerts | No | No | Yes |
| PagerDuty alerts | No | No | Yes |
| Smart alerting | Yes | Yes | Yes |
| AI diagnosis | Yes | Yes | Yes |
Troubleshooting
My monitor is stuck on "NEW"
A monitor stays in the "new" state until it receives its first ping. Try running the curl command from your terminal to verify the endpoint works. Check that you're using the correct monitor ID in the URL.
I'm not receiving email alerts
Check your alert email address in Settings. Also check your spam folder — the first few emails from a new sender sometimes end up there. If your monitor is "up", that means pings are arriving on time and no alerts are expected.
The AI diagnosis says "insufficient data"
The AI needs failure data to diagnose problems. Upgrade to Tier 2 or Tier 3 integration by sending exit codes, duration, and stderr with your pings. Simple heartbeat pings (Tier 1) only tell CronDoctor that the job ran — not whether it succeeded.
How do I change my monitor's schedule?
Click on the monitor from the dashboard, then click the "Edit" button in the top right. You can update the name, cron expression (or heartbeat interval), and grace period.
My ping endpoint returns an error
The ping endpoint is designed to always return 200 OK. If you're seeing errors, check that the URL is correct and includes your full monitor ID. The format is:https://crondoctor.com/api/ping/YOUR_MONITOR_ID
Why am I getting alerts right after creating a monitor?
New monitors start in the "new" state and won't trigger alerts until after the first ping arrives. After the first ping, CronDoctor starts tracking based on your schedule. If the next expected ping doesn't arrive within the grace period, you'll get an alert.
Still have questions? Email us at support@crondoctor.com