Skip to main content
Sentry Cron Monitors let you verify that your scheduled jobs — cron jobs, background workers, data pipelines, and any other periodic task — execute on time and successfully. If a job misses its schedule, runs too long, or exits with an error, Sentry creates an issue and alerts the team.

​
How it works

Your job sends check-in signals to Sentry at the start and end of each execution. Sentry compares these signals against the configured schedule and raises an incident if:
  • The job does not check in within the expected window (missed)
  • The job checks in as in_progress but does not complete within the max runtime (timed out)
  • The job checks in with error status (failed)

​
Check-in protocol

A job communicates its status via three check-in states:
StatusMeaning
in_progressThe job has started. Sentry starts the timeout clock.
okThe job completed successfully. Resets the monitor to healthy.
errorThe job completed with an error. Creates or updates an incident.

​
Instrumenting a cron job

import sentry_sdk
from sentry_sdk.crons import monitor

sentry_sdk.init(dsn="...")

# Option 1: decorator
@monitor(monitor_slug="my-daily-job")
def daily_job():
    # your job logic here
    process_reports()

# Option 2: context manager
def daily_job():
    with sentry_sdk.monitor(monitor_slug="my-daily-job"):
        process_reports()

# Option 3: manual check-ins
def daily_job():
    check_in_id = sentry_sdk.capture_checkin(
        monitor_slug="my-daily-job",
        status=sentry_sdk.crons.MonitorStatus.IN_PROGRESS,
    )
    try:
        process_reports()
        sentry_sdk.capture_checkin(
            monitor_slug="my-daily-job",
            check_in_id=check_in_id,
            status=sentry_sdk.crons.MonitorStatus.OK,
            duration=elapsed_seconds,
        )
    except Exception:
        sentry_sdk.capture_checkin(
            monitor_slug="my-daily-job",
            check_in_id=check_in_id,
            status=sentry_sdk.crons.MonitorStatus.ERROR,
        )
        raise

​
Schedule types

Sentry supports two schedule formats:

Crontab

Standard Unix cron expression. For example, 0 9 * * 1-5 runs at 9 AM Monday through Friday.
{
  "schedule_type": "crontab",
  "schedule": "0 9 * * 1-5",
  "timezone": "America/New_York"
}

Interval

Simple interval expressed as a count and unit (minute, hour, day, week, month).
{
  "schedule_type": "interval",
  "schedule": [30, "minute"]
}

​
Monitor configuration

When creating or updating a monitor, you can configure:
SettingDescription
checkin_marginMinutes after the expected check-in time before declaring a miss (minimum: 1 minute)
max_runtimeMaximum minutes an in_progress check-in can run before being marked as timed out (default: 30 minutes, maximum: 28 days)
timezoneIANA timezone for interpreting the crontab schedule
failure_issue_thresholdNumber of consecutive failures before creating an issue (default: 1)
recovery_thresholdNumber of consecutive successes before resolving an incident (default: 1)

​
Monitor statuses

StatusDescription
okAll check-ins are arriving on schedule and completing successfully
errorThe monitor is in an active incident state
missedA check-in was not received within the expected window
timed_outA check-in was started but did not complete within max_runtime
disabledThe monitor has been manually disabled

​
Alerts

You can attach an issue alert rule to a cron monitor to control how incidents are routed. By default, Sentry uses the project’s default alert rule. You can customize the alert to notify specific teams or channels when the monitor fails.
Each organization has a maximum number of monitors. Monitors also have a per-organization environment limit. If you hit these limits, Sentry will raise a MonitorLimitsExceeded error and reject new monitor creation.

Build docs developers (and LLMs) love

Get started for freeTalk to us