Guides

Job Monitoring


It's easy to monitor any kind of cron job with Cronitor. You will be alerted if anything goes wrong with your job, including:

  • The job does not start on schedule
  • The job fails or crashes unexpectedly
  • The job runs longer than expected

In this guide:

How to Create a Cron Monitor

There are three common ways to create cron monitors.

  1. Install the CronitorCLI to automatically add monitoring to your crontab files.

    If you are monitoring cron jobs on Linux, BSD or MacOS our CLI will detect the crontabs on your system, and will walk you through adding monitoring as desired. It will automatically create the monitors and make the required modifications to your crontab files.

  2. Use the web dashboard to create individual monitors.

    Our web dashboard is an easy to use interface, and creating new monitors can be done quickly by anyone with a Cronitor account.

  3. Integrate with our Monitor API to programatically create monitors.

    For more advanced use cases, such as adding Cronitor to provisioning or deployment scripts, we offer an easy to use REST API as well as open-source API clients for many popular languages.

  1. Install CronitorCLI  (it's easy, promise).
  2. Run cronitor discover to find cron jobs and import them into Cronitor.
    • Use the auto-generated cron job names or use the interactive prompt to create something more memorable.
    • 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.

    Tip:You can re-run discover at any time to find new cron jobs or change names.

  3. You're done! All of the monitors will appear in a pending state on your account dashboard. As your jobs run the corresponding monitors will become active, and start reporting activity.

  1. From the Cronitor dashboard, click the button to create a new monitor, and select the monitor type that bests matches your system cron.

    Tip:This is important because standard cron uses a 5 digit syntax, e.g. * * * * *, while some systems like Java Cron (Quartz/Spring) and AWS Scheduled Events support 6 digit cron expressions. In Java the extra * represents seconds, while on AWS it is years!

  2. Paste the schedule expression of your cron job into the 'Cron expression' field, and select the timezone of your server.

    If needed, adjust the grace period for this job. If your job fails to start or complete, Cronitor will wait the duration of the grace period before sending an alert.

    Tip:Server Timezone can be configured account-wide from the settings page.

  3. Give the monitor a descriptive name like Offsite Database Backup. You can optionally add tags to help you organize your monitors.

  4. You're done! Your monitor will be assigned a unique ping url and be placed in a pending state. Monitoring will begin when the first ping is received.

    For production usage, read the integration guide to learn more about using CronitorCLI, one of our language SDKs or just plain old curl to send pings when your job runs.

    To test things out, enter the ping url in your browser (replace d3x0c1 with your code), and ping https://cronitor.link/d3x0c1/run followed by https://cronitor.link/d3x0c1/fail to simulate a job that started and then exited with an error.

  1. Copy your API key from your settings page.

  2. Use cURL or one of our open-source API clients to make a POST request.

    curl -X POST https://cronitor.io/api/monitors \
    -u <API-KEY>: \
    -H "Content-Type: application/json" \
    -d '{
        "key": "database-backup",
        "type": "job",
        "schedule": "0 */3 * * 1-5"
    }'

    Tip: Complete documenation for our Monitor API can be found here.

  3. You're done! Your monitor will be assigned a unique ping url and be placed in a pending state. Monitoring will begin when the first ping is received.

    For production usage, read the integration guide to learn more about using CronitorCLI, one of our language SDKs or just plain old curl to send pings when your job runs.

    To test things out, enter the monitor's ping url in your browser, and ping https://cronitor.link/d3x0c1/run followed by https://cronitor.link/d3x0c1/fail to simulate a job that started and then exited with an error (replace d3x0c1 with your code).

Adding Cronitor to Your Cron Jobs

A small amount of integration work is required to tell Cronitor when your cron job runs (starts), completes, or fails.

If you are monitoring traditional cron jobs the easiest way to do this the CronitorCLI. Running the cronitor discover will add the integration for you automatically.

If you do not want to install the CLI, or you are not using crontab, you can integrate with Cronitor by using one of our open-source SDKs, or by instrumenting your own calls to the Telemetry Events API. 

# Install CronitorCLI
curl -sOL https://cronitor.io/dl/linux_amd64.tar.gz
sudo tar xvf linux_amd64.tar.gz -C /usr/bin/
sudo cronitor configure --api-key <API-KEY>
# With CronitorCLI (recommended)
# m h dom mon dow   command
0 0 * * * cronitor exec nightly-job /path/to/executable

# Or without software
0 0 * * * curl https://cronitor.link/p/<API-KEY>/nightly-job?state=run -m 5 ; /path/to/executable && curl https://cronitor.link/p/<API-KEY>/nightly-job?state=complete
View on Github

CronitorCLI is the easiest way to monitor a crontab file.

pip install cronitor

import cronitor
cronitor.api_key = '<API-KEY>'

# monitor any function
@cronitor.job('nightly-job')
def nightly_background_job(args):
    ...
# Or embed telemetry events in your application
monitor = cronitor.Monitor('nightly-job')
# send a run event (a job/process has started)
monitor.ping(state='run')
# send a complete event (a job/process has completed successfully)
monitor.ping(state='complete')
# send a failure event
monitor.ping(state='fail')
View on Github 
npm install --save cronitor
// monitor any node cron job
const cron = require('cronitor')('<API-KEY>');
cron.wraps(require('node-cron')); // also works with require('cron');

cron.schedule('SendWelcomeEmail', '*/5 * * * *', function() {
    console.log('Sending welcome email to new sign ups every five minutes.');
});

// Or embed telemetry events in your application
const cronitor = require('cronitor')('<API-KEY>')
const monitor = new cronitor.Monitor('nightly-background-job');
// send a run event (a job/process has started)
monitor.ping({state: 'run'});
// send a complete event (a job/process has completed successfully)
monitor.ping({state: 'complete'});
// send a failure event
monitor.ping({state: 'fail'});
View on Github 
gem install cronitor
require 'cronitor'
Cronitor.api_key = '<API-KEY>'

# monitor any function/code block
Cronitor.job 'nightly-job' do
  nightly_background_job()
end

# Or, embed telemetry events in your application
monitor = Cronitor.Monitor.new('nightly-job')
# send a run event (a job/process has started)
monitor.ping(state: 'run')
# send a complete event (a job/process has completed successfully)
monitor.ping(state: 'complete')
# send a failure event
monitor.ping(state: 'fail')
View on Github 
// Maven
<dependency>
    <groupId>io.cronitor</groupId>
    <artifactId>client</artifactId>
    <version>1.4.0</version>
</dependency>

// Gradle
compile "io.cronitor:client:1.4.0
// Embed telemetry events in your application
CronitorClient cronitorClient = new CronitorClient('<API-KEY>');

// send a run event (a job/process has started)
cronitorClient.run('nightly-job');
// send a complete event (a job/process has completed successfully)
cronitorClient.complete('nightly-job');
// send a failure event
cronitorClient.fail('nightly-job');
View on Github 
composer require cronitor/cronitor-php
$cronitor = new Cronitor\Client('<API-KEY>');

# monitor any function/code block
$cronitor->job('nightly-job', function() {
  $nightlyBackgroundJob();
});

# Or, embed telemetry events in your application
$monitor = $cronitor->monitor('nightly-job')
# send a run event (a job/process has started)
$monitor->ping(['state' => 'run'])
# send a complete event (a job/process has completed successfully)
$monitor->ping(['state' => 'complete'])
# send a failure event
$monitor->ping(['state' => 'fail'])
View on Github 
# send an event
curl https://cronitor.link/p/<API-KEY>/nightly-job
# send a run event (a job/process has started)
curl https://cronitor.link/p/<API-KEY>/nightly-job?state=run
# send a complete event (a job/process has completed successfully)
curl https://cronitor.link/p/<API-KEY>/nightly-job?state=complete
# send a failure event
curl https://cronitor.link/p/<API-KEY>/nightly-job?state=fail

How to Configure Alert Recipients

Cronitor can send alerts via many different channels, including: Email, Slack, PagerDuty, Microsoft Teams, SMS, webhooks and more.

Notification lists are configurable sets of channels that are attached to your monitors. When a monitor fails or recovers, an alert will be sent to every channel/recipient on the attached list. You can create or modify a list from the Notification Lists section of your settings page.

In the monitor's edit form locate the Alert Receipients panel. You may choose to add a notification list or add channels/recipients directly (or both).

Specify alert recipients adding a notify array to your monitor JSON as shown below. Notification lists are attached using the template key. For complete list of options see our API docs.

curl -X POST https://cronitor.io/api/monitors \
-u <API-KEY>: \
-H "Content-Type: application/json"
-d '{
    "key": "Database Backup",
    "type": "job",
    "schedule": "0 */3 * * 1-5",
    "notify": ['devops-emergency']
}'

Tip: When your Cronitor account is created a list named "Default" will automatically be created, and your email address will be added to it. When no list is specified the default list will be used.

How to Customize Duration Alerts

Cronitor uses the performance history of your job to detect anomalies in runtime. 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 Running longer than expected alerts earlier than you would like, you can set a threshold duration for the job:

In the monitor's edit form locate the Alert Preferences panel and select Alert if this job runs longer than.

Specify a duration alert threshold by adding a metric.duration assertion. In the example below, an alert would be sent if the job ran for longer than 5 minutes.

curl -X POST https://cronitor.io/api/monitors \
-u <API-KEY>: \
-H "Content-Type: application/json"
-d '{
    "key": "Database Backup",
    "type": "job",
    "schedule": "0 */3 * * 1-5",
    "assertions": ['metric.duration < 5 minutes']
}'

Nota Bene: With less data available on a new monitor we use a wider implied grace period and we will not send Running longer than expected alerts until the job has completed successfully at least once.

How to Customize Failure Tolerance Alerts

By default Cronitor will alert you every time we detect a problem. If you can tolerate a few failures, and do not wish be alerted each time, you can set the failure tolerance threshold of your monitor. You will be sent an alert when the number of consecutive failures exceededs the threshold.

In the monitor's edit form locate the Alert Preferences panel and select Failure Tolerance. Choose "Only send an alert if there is a persistent problem". Set the failure tolerance as desired.

Specify failure tolerance by adding the key tolerated_failures to your monitor's JSON object. The value is the threhold number.

curl -X POST https://cronitor.io/api/monitors \
-u <API-KEY>: \
-H "Content-Type: application/json"
-d '{
    "key": "Database Backup",
    "type": "job",
    "schedule": "0 */3 * * 1-5",
    "tolerated_failures": 5
}'

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 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.

  • Can I monitor Kubernetes Cron Jobs?

    Yes! Cronitor makes it easy to monitor any cron job, including Kubernetes Cron Jobs. The easiest way to get started is to install our CLI in your base container.