HTTP

Sentry Crons allows you to monitor the uptime and performance of any scheduled, recurring job. Once implemented, it'll allow you to get alerts and metrics to help you solve errors, detect timeouts, and prevent disruptions to your service.

Requirements

To begin monitoring your recurring, scheduled job:

1. Create a new monitor in Sentry.
2. Configure check-ins or a heartbeat for your job.

Optionally, you can skip the first step and create or update (upsert) a monitor through a check-in. See more below.

Check-Ins (Recommended)

Check-in monitoring allows you to track a job's progress by completing two check-ins: one at the start of your job and another at the end of your job. This two-step process allows Sentry to notify you if your job didn't start when expected (missed) or if it exceeded its maximum runtime (failed).

# 🟡 Notify Sentry your job is running:
curl -X POST \
    'https://sentry.io/api/0/organizations/example-org/monitors/<monitor_slug>/checkins/' \
    --header 'Authorization: DSN https://examplePublicKey@o0.ingest.sentry.io/0' \
    --header 'Content-Type: application/json' \
    --data-raw '{"status": "in_progress"}'

# Execute your scheduled task here...

# 🟢 Notify Sentry your job has completed successfully:
curl -X PUT \
    'https://sentry.io/api/0/organizations/example-org/monitors/<monitor_slug>/checkins/latest/' \
    --header 'Authorization: DSN https://examplePublicKey@o0.ingest.sentry.io/0' \
    --header 'Content-Type: application/json' \
    --data-raw '{"status": "ok"}'

If your job execution fails:

# 🔴 Notify Sentry your job has failed:
curl -X PUT \
    'https://sentry.io/api/0/organizations/example-org/monitors/<monitor_slug>/checkins/latest/' \
    --header 'Authorization: DSN https://examplePublicKey@o0.ingest.sentry.io/0' \
    --header 'Content-Type: application/json' \
    --data-raw '{"status": "error"}'

Specifying monitor environments (Optional)

When sending check-ins to your monitor you may specify the environment of the check-in. This allows you to monitor a single schedule across multiple environments.

If you don't specify an environment with your check-ins the default is production.

# 🟡 Notify Sentry your job is running in the dev environment:
curl -X POST \
    'https://sentry.io/api/0/organizations/example-org/monitors/<monitor_slug>/checkins/' \
    --header 'Authorization: DSN https://examplePublicKey@o0.ingest.sentry.io/0' \
    --header 'Content-Type: application/json' \
    --data-raw '{"status": "in_progress", "environment": "dev"}'

# Execute your scheduled task here...

# 🟢 Notify Sentry your dev environment job has completed successfully:
curl -X PUT \
    'https://sentry.io/api/0/organizations/example-org/monitors/<monitor_slug>/checkins/latest/' \
    --header 'Authorization: DSN https://examplePublicKey@o0.ingest.sentry.io/0' \
    --header 'Content-Type: application/json' \
    --data-raw '{"status": "ok", "environment": "dev"}'

Creating or Updating a Monitor Through a Check-In (Optional)

Sentry enables the automatic creation or update of a monitor (upsert) through the check-in payload. This can be useful if you have many scheduled tasks or need to create them dynamically.

# Upsert monitor with a check-in
curl -X POST \
    'https://sentry.io/api/0/organizations/example-org/monitors/<monitor_slug>/checkins/' \
    --header 'Authorization: DSN https://examplePublicKey@o0.ingest.sentry.io/0' \
    --header 'Content-Type: application/json' \
    --data-raw '{"monitor_config": {"schedule": "0 * * * *", "schedule_type": "crontab"}, "status": "in_progress"}'

Monitor monitor_config parameters:

schedule_type:

The schedule representation for your monitor, either crontab or interval.

schedule:

The job's schedule based on the schedule_type:

• crontab: a string crontab expression with five fields, such as "0 * * * *".
• interval: a tuple for your interval such as [2, "hour"].

checkin_margin:

The amount of time (in minutes) Sentry should wait for your check-in before it's considered missed ("grace period"). Optional.

max_runtime:

The amount of time (in minutes) your job is allowed to run before it's considered failed. Optional.

timezone

The tz where your job is running. This is usually your server's timezone, (such as America/Los_Angeles). See list of tz database time zones. Optional.

Check-in Attachment (Optional)

Sentry Crons can help you better understand your job check-ins by storing a file, such as a log output. You'll be able to use this to debug check-in failures or track job statuses. To upload your attachment, execute the following HTTP POST (multipart/form-data) request:

# Perform a POST request to attach a file to a check-in
curl -X POST \
  'https://sentry.io/api/0/organizations/example-org/monitors/<monitor_slug>/checkins/latest/attachment/' \
  --header 'Authorization: DSN https://examplePublicKey@o0.ingest.sentry.io/0' \
  --form 'file=<file_path>'

Attachments can be downloaded in each corresponding check-in on your “Monitor Details” page.

Current attachment limitations:

1. Each job is limited to one attachment.
2. The maximum file size is 100kb.
3. Attachments aren't currently supported by our CLI or SDKs.

Overlapping Jobs (Optional)

A job execution that begins before the previous job execution has been completed is called an overlapping job. This happens if you have a job with a runtime duration longer than your job's interval schedule.

A simple example is if you have a job that runs every minute (1), but takes five (5) minutes to complete each execution.

If this happens, you have to provide a check-in ID with the second check-in request to prevent unintended consequences. The check-in ID will be returned upon your first check-in and can be provided to the second check-in request.

Usage example:

# 🟡 Notify Sentry your job is running:
curl -X POST \
    'https://sentry.io/api/0/organizations/example-org/monitors/<monitor_slug>/checkins/' \
    --header 'Authorization: DSN https://examplePublicKey@o0.ingest.sentry.io/0' \
    --header 'Content-Type: application/json' \
    --data-raw '{"status": "in_progress"}'
# Response { "id": "2bc1a871-a1b7-4577-82fc-fa6d2468aabc" }

# Execute your scheduled task here...

# 🟢 Notify Sentry your job has completed successfully using the returned ID:
curl -X PUT \
    'https://sentry.io/api/0/organizations/example-org/monitors/<monitor_slug>/checkins/2bc1a871-a1b7-4577-82fc-fa6d2468aabc/' \
    --header 'Authorization: DSN https://examplePublicKey@o0.ingest.sentry.io/0' \
    --header 'Content-Type: application/json' \
    --data-raw '{"status": "ok"}'

Heartbeat

Heartbeat monitoring notifies Sentry of a job's status through one check-in. This setup will only notify you if your job didn't start when expected (missed). If you need to track a job to see if it exceeded its maximum runtime (failed), use check-ins instead.

# 🟢 Notify Sentry your job has completed successfully:
curl -X POST \
    'https://sentry.io/api/0/organizations/example-org/monitors/<monitor_slug>/checkins/' \
    --header 'Authorization: DSN https://examplePublicKey@o0.ingest.sentry.io/0' \
    --header 'Content-Type: application/json' \
    --data-raw '{"status": "ok"}'

If your job execution fails:

# 🔴 Notify Sentry your job has failed:
curl -X POST \
    'https://sentry.io/api/0/organizations/example-org/monitors/<monitor_slug>/checkins/' \
    --header 'Authorization: DSN https://examplePublicKey@o0.ingest.sentry.io/0' \
    --header 'Content-Type: application/json' \
    --data-raw '{"status": "error"}'

Connecting Errors to Cron Monitors

If you're capturing Sentry errors, you can link them to a Cron Monitor by using context.

sentry_sdk.set_context("monitor", {
    "slug": "<monitor_slug>",
})

See additional context examples for your platform.

Alerts

When your recurring job fails to check in (missed), runs beyond its configured maximum runtime (failed), or manually reports a failure, Sentry will create an error event with a tag to your monitor.

To receive alerts about these events:

1. Navigate to Alerts in the sidebar.
2. Create a new alert and select "Issues" under "Errors" as the alert type.
3. Configure your alert and define a filter match to use: The event's tags match {key} {match} {value}.

Example: The event's tags match monitor.slug equals my-monitor-slug-here

Learn more in Issue Alert Configuration.