Set Up Crons

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 PHP SDK (min v3.16.0) for your recurring job.
• Create and configure your first Monitor.

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:
$checkInId = \Sentry\captureCheckIn(
    slug: '<monitor-slug>',
    status: CheckInStatus::inProgress()
);

// Execute your scheduled task here...

// 🟢 Notify Sentry your job has completed successfully:
\Sentry\captureCheckIn(
    slug: '<monitor-slug>',
    status: CheckInStatus::ok(),
    checkInId: $checkInId,
);

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

// 🔴 Notify Sentry your job has failed:
\Sentry\captureCheckIn(
    slug: '<monitor-slug>',
    status: CheckInStatus::error(),
    checkInId: $checkInId,
);

Alternatively, you can use withMonitor() to monitor a callback.

\Sentry\withMonitor(
    slug: '<monitor-slug>',
    callback: fn () => doSomething(),
);

This will create an in-progress check-in and either an ok or error check-in, depending on if your provided callback threw an exception.

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.

// Execute your scheduled task...

// 🟢 Notify Sentry your job completed successfully:
\Sentry\captureCheckIn(
    slug: '<monitor-slug>',
    status: CheckInStatus::ok(),
    duration: 10, // Optional duration in seconds
);

If your job execution fails, you can:

// 🔴 Notify Sentry your job has failed:
\Sentry\captureCheckIn(
    slug: '<monitor-slug>',
    status: CheckInStatus::error(),
    duration: 10, // Optional duration in seconds
);

Upserting Cron Monitors

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

// Create a crontab schedule object (every 10 minutes)
$monitorSchedule = \Sentry\MonitorSchedule::crontab('*/10 * * * *');

// Or create an interval schedule object (every 10 minutes)
$monitorSchedule = \Sentry\MonitorSchedule::interval(10, MonitorScheduleUnit::minute());

Supported units are:

• MonitorScheduleUnit::minute()
• MonitorScheduleUnit::hour()
• MonitorScheduleUnit::day()
• MonitorScheduleUnit::week()
• MonitorScheduleUnit::month()
• MonitorScheduleUnit::year()

// Create a config object
$monitorConfig = new \Sentry\MonitorConfig(
    $monitorSchedule,
    checkinMargin: 5, // Optional check-in margin in minutes
    maxRuntime: 15, // Optional max runtime in minutes
    timezone: 'Europe/Vienna', // Optional timezone
    failureIssueThreshold: 2 //Optional failure issue threshold
    recoveryThreshold: 5 // Optional recovery threshold
);

// 🟡 Notify Sentry your job is running:
$checkInId = \Sentry\captureCheckIn(
    slug: '<monitor-slug>',
    status: CheckInStatus::inProgress(),
    monitorConfig: $monitorConfig,
);

// Execute your scheduled task here...

// 🟢 Notify Sentry your job has completed successfully:
\Sentry\captureCheckIn(
    slug: '<monitor-slug>',
    status: CheckInStatus::ok(),
    checkInId: $checkInId,
);

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.

Rate Limits

Crons imposes a rate limit on check-ins to prevent abuse and resource overuse. Specifically, you can only send a maximum of 6 check-ins per minute per existing monitor environment. This limit is enforced on a per-project basis, meaning that the rate limit applies collectively to all monitor environments within a given project. You can check if any of your check-ins are being dropped in the Usage Stats page.

To avoid dropped check-ins, it is crucial to manage and distribute your check-ins efficiently within the rate limits. This will help maintain accurate monitoring and ensure that all critical check-ins are captured and processed.