Cron job monitoring

When you create a monitor for a cron job with a schedule like 4 5 * * * you will be alerted if anything goes wrong with your job, including:

  • The job does not start
  • The job runs for longer than expected
  • The job exits with a failure code

Creating your first cron job monitor

Creating a test monitor or monitoring a single cron job can usually be completed in just a few minutes.

  1. Click the button on your dashboard to create a new monitor and select Cron job monitor.
  2. Paste the schedule expression from your cron job into the schedule field:
  3. Provide your server's timezone. A default timezone can be set from the Settings page.
  4. If needed, adjust the grace period for this job. After an expected execution time Cronitor will wait the duration of the grace period for your job to start before sending an alert.
  5. Give the monitor a descriptive name like Offsite Database Backup and add optional tags or notes.
  6. After saving the monitor you'll be given a unique Ping API url. If you're just testing things out, use your browser to send a /run ping followed by a /fail ping to simulate a job that started and then exited with an error. For production usage, read the integration guide to learn more about using CronitorCLI or Curl to send pings when your job runs.

Your new monitor is created in a paused state; monitoring will not begin until the first ping is received.

Monitoring every job in your crontab

If you are monitoring cron jobs on Linux, BSD or MacOS, using cronitor discover in CronitorCLI is the easiest way to automatically create monitors for each job and keep their schedule in sync with your server.

  1. If you haven't installed CronitorCLI on your server, download and follow the installation instructions.
  2. Run cronitor discover to find cron jobs and import them into Cronitor.
    • You can use default monitor names or use the interactive prompt to create something more memorable.
    • After cron jobs are imported, you'll be prompted to save your updated crontab. If the --save option is supplied, saving will happen automatically without a prompt first.
    • Discover will always find cron jobs in your user crontab. If run with elevated privileges, jobs in the system crontab and drop-in directory are also imported.
    You can re-run discover at any time to find new cron jobs or change monitor names.

Handling job schedule changes easily

If your job schedules change frequently it can be challenging to ensure that your Cronitor monitors are in sync. Over time, this can accumulate false alarms and noisy alerts. By scheduling cronitor discover to run every hour, schedule updates will be pushed automatically to Cronitor on a regular basis. When using cronitor discover to import your crontab, this entry is added automatically.

Alerts when your job runs longer than expected

Cronitor uses past performance to notify you when your job runs significantly longer than expected. Our prediction algorithm grows more precise as we learn more about your job performance but it won't work perfectly for every job. If you are receiving has not completed when expected alerts earlier than you would like, you can increase the "grace period" for your monitor or provide a specific expected duration for the job:

  • With less data available on a new monitor we use a wider implied grace period and we will not send has not completed when expected alerts until the job has completed successfully at least once.
  • API Users: Specify fixed runtime duration by adding a custom ran_longer_than rule along with the not_on_schedule rule.

To send duration alerts, Cronitor must know when your job starts running and when it completes successfully. To report these events, you should run your job using cronitor exec or ping your /run endpoint as your job starts and /complete as it exits successfully. For more details on Ping API endpoints and where you should integrate your ping requests, see:

Frequently asked questions

  • What if my cron job starts after a random delay, like anacron?

    If you don't expect your job to start immediately at the scheduled time, expand the grace time on your monitor. Ensure your grace period exceeds any intentional or expected delay.

  • How does Cronitor handle schedules with 6 values, like Quartz?

    In some systems, cron schedules can have 6 values, meaning either seconds or year. In both cases, Cronitor attempts to ignore this additional value. We hope to expand support and handling for these more precise schedules.

  • How does Cronitor know when my job starts, completes and fails?

    For Cronitor to alert you when something goes wrong with your job a small amount of integration work is required to tell Cronitor when your job runs. The absolute easiest way to do this is to run your job using cronitor exec, but you can tell Cronitor nearly everything it needs with just a couple curl requests. See the Cronitor Integration Guide for more details.

  • How do I determine my server timezone?

    On Linux and MacOS, use timedatectl or date to determine the current timezone locale. On Windows, use tzutil /g. Timezones can be set per monitor, and an account-wide default is available on the account settings page.