Sentry Php Sdk

# Crons — Sentry PHP SDK

> Minimum SDK versions: `sentry/sentry` ≥ 3.16.0 · `sentry/sentry-laravel` ≥ 3.3.1

## Overview

Sentry Crons monitors scheduled jobs by receiving check-ins at job start, success, and failure. Three approaches:

| Approach | Use when |
|----------|---------|
| `withMonitor()` wrapper | Simple wrapping of any callable |
| `captureCheckIn()` manually | Need control over timing, status, or heartbeats |
| `sentryMonitor()` macro (Laravel) | Laravel scheduled tasks — minimal boilerplate |

## Code Examples

### `withMonitor()` wrapper (simplest)

```php
\Sentry\withMonitor(
    slug: 'my-cron-job',
    callback: fn() => doSomething(),
);
// Sends IN_PROGRESS before, OK on success, ERROR on exception
```

### Manual check-ins with `captureCheckIn()`

```php
use Sentry\CheckInStatus;

// 1. Signal job started
$checkInId = \Sentry\captureCheckIn(
    slug: 'my-cron-job',
    status: CheckInStatus::inProgress(),
);

try {
    // 2. Do work
    runScheduledTask();

    // 3a. Signal success
    \Sentry\captureCheckIn(
        slug: 'my-cron-job',
        status: CheckInStatus::ok(),
        checkInId: $checkInId,
    );
} catch (\Throwable $e) {
    // 3b. Signal failure
    \Sentry\captureCheckIn(
        slug: 'my-cron-job',
        status: CheckInStatus::error(),
        checkInId: $checkInId,
    );
    throw $e;
}
```

### Heartbeat (single check-in)

Only notifies if the job **didn't start** when expected (missed). Does not detect max runtime exceeded.

```php
// Success
\Sentry\captureCheckIn(
    slug: 'my-cron-job',
    status: CheckInStatus::ok(),
    duration: 10, // optional: seconds
);

// Failure
\Sentry\captureCheckIn(
    slug: 'my-cron-job',
    status: CheckInStatus::error(),
);
```

### Upsert monitor config programmatically

Define monitor settings in code so Sentry creates/updates the monitor automatically on first check-in:

```php
use Sentry\CheckInStatus;
use Sentry\MonitorConfig;
use Sentry\MonitorSchedule;
use Sentry\MonitorScheduleUnit;

// Crontab schedule
$monitorConfig = new MonitorConfig(
    MonitorSchedule::crontab('0 2 * * *'),  // every day at 2 AM
    checkinMargin: 5,                        // minutes late before MISSED alert
    maxRuntime: 15,                          // minutes before TIMEOUT alert
    timezone: 'Europe/Vienna',
    failureIssueThreshold: 2,               // consecutive failures before issue
    recoveryThreshold: 5,                   // consecutive successes to resolve
);

$checkInId = \Sentry\captureCheckIn(
    slug: 'daily-backup',
    status: CheckInStatus::inProgress(),
    monitorConfig: $monitorConfig,
);

runBackup();

\Sentry\captureCheckIn(
    slug: 'daily-backup',
    status: CheckInStatus::ok(),
    checkInId: $checkInId,
);
```

```php
// Interval schedule
$monitorConfig = new MonitorConfig(
    MonitorSchedule::interval(10, MonitorScheduleUnit::minute()),
    checkinMargin: 5,
    maxRuntime: 8,
);
```

### Laravel — `sentryMonitor()` macro

Add `sentryMonitor()` to any scheduled task in `routes/console.php`:

```php
use Illuminate\Support\Facades\Schedule;

Schedule::command(SendEmailsCommand::class)
    ->everyHour()
    ->sentryMonitor(); // that's it
```

With full configuration:

```php
Schedule::command(SendEmailsCommand::class)
    ->everyHour()
    ->sentryMonitor(
        monitorSlug: null,              // auto-generated if null
        checkInMargin: 5,              // minutes before MISSED alert
        maxRuntime: 15,                // minutes before TIMEOUT alert
        failureIssueThreshold: 1,      // consecutive failures before issue
        recoveryThreshold: 1,          // consecutive successes to resolve
        updateMonitorConfig: true,     // set false to manage config in UI only
    );
```

> **Limitation:** Tasks using `between`, `unlessBetween`, `when`, or `skip` are not supported. Use Laravel's `cron()` method for schedule frequency in those cases.

### Symfony — same as base PHP SDK

The Symfony bundle has no de