Set Up Crons

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

• Use our getting started guide to install and configure the Sentry Ruby SDK (min v5.12.0) for your recurring job.
• Create and configure your first Monitor.

Job Monitoring

If you're using sidekiq-cron or sidekiq-scheduler, Sentry can automatically capture check-ins for all jobs that are scheduled to run periodically. To achieve this, you need to enable the corresponding Sentry plugin:

Sentry.init do |config|
  config.enabled_patches += [:sidekiq_cron]
  # or, for sidekiq-scheduler:
  config.enabled_patches += [:sidekiq_scheduler]
end

More generally, popular job frameworks such as ActiveJob and Sidekiq with a perform method can use the Sentry::Cron::MonitorCheckIns mixin module to automatically capture check-ins.

class ExampleJob < ApplicationJob
  include Sentry::Cron::MonitorCheckIns

  sentry_monitor_check_ins

  def perform(*args)
    # do stuff
  end
end

You can pass in optional attributes to sentry_monitor_check_ins as follows.

# slug defaults to the job class name
sentry_monitor_check_ins slug: 'custom_slug'

# define the monitor config with an interval
# the units supported are :year, :month, :week, :day, :hour, :minute
sentry_monitor_check_ins monitor_config: Sentry::Cron::MonitorConfig.from_interval(1, :minute)

# define the monitor config with a crontab
sentry_monitor_check_ins monitor_config: Sentry::Cron::MonitorConfig.from_crontab('5 * * * *')

Manual Setup

If you're using Clockwork or Whenever, you'll need to instrument your jobs manually.

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

check_in_id = Sentry.capture_check_in('<monitor-slug>', :in_progress)
# Execute your scheduled task here...
Sentry.capture_check_in('<monitor-slug>', :ok, check_in_id: check_in_id)

If your job execution fails, you can notify Sentry about the failure:

Sentry.capture_check_in('<monitor-slug>', :error, check_in_id: check_in_id)

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.

Sentry.capture_check_in('<monitor-slug>', :ok)

If your job execution fails, you can notify Sentry about the failure:

Sentry.capture_check_in('<monitor-slug>', :error)

Upserting Cron Monitors

You can create and update your Monitors programmatically with code rather than creating and configuring them in Sentry.io.

First create a config object from either a crontab or an interval.

# Create a config from a crontab schedule (every 10 minutes)
monitor_config = Sentry::Cron::MonitorConfig.from_crontab(
  '5 * * * *',
  checkin_margin: 5, # Optional check-in margin in minutes
  max_runtime: 15, # Optional max runtime in minutes
  timezone: 'Europe/Vienna', # Optional timezone
)

# Create a config from an interval schedule (every 10 minutes)
monitor_config = Sentry::Cron::MonitorConfig.from_interval(
  10,
  :minute,
  checkin_margin: 5, # Optional check-in margin in minutes
  max_runtime: 15, # Optional max runtime in minutes
  timezone: 'Europe/Vienna', # Optional timezone
)

Then, use that config object during your check-ins.

# 🟡 Notify Sentry your job is running:
check_in_id = Sentry.capture_check_in(
  '<monitor-slug>',
  :in_progress,
  monitor_config: monitor_config
)

# Execute your scheduled task here...

# 🟢 Notify Sentry your job has completed successfully:
Sentry.capture_check_in(
  '<monitor-slug>',
  :ok,
  check_in_id: check_in_id,
  monitor_config: monitor_config
)`

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.