Check-Ins

SDKs MUST generate a unique check_in_id (UUID v4) when a job execution starts and send a check-in with status in_progress.

When the job completes, SDKs MUST send a second check-in with the same check_in_id and status ok (success) or error (failure).

SDKs SHOULD compute the duration field for terminal check-ins (ok or error) by measuring the elapsed time since the in_progress check-in was sent.

SDKs SHOULD include a contexts.trace object with a trace_id field to link the check-in to associated errors and traces.

If the job execution is part of an active trace, the SDK SHOULD use that trace's trace_id. Otherwise, the SDK MAY generate a new trace_id for correlation purposes.

SDKs MAY send a check-in with check_in_id set to an empty UUID (128-bit zero value, 00000000000000000000000000000000) to indicate that Sentry SHOULD update the most recent in_progress check-in for the given monitor.

If no in_progress check-in exists, Sentry creates a new one.

This is useful for fire-and-forget patterns where the SDK does not retain the original check_in_id.

SDKs MAY include a monitor_config object in the check-in payload. When present, Sentry creates the monitor if it does not exist, or updates its configuration if it does.

SDKs SHOULD only send monitor_config on the first check-in of a job execution (the in_progress check-in), not on every check-in.

SDKs MAY provide integrations that automatically instrument popular scheduling libraries. When available, these integrations SHOULD:

1. Automatically discover scheduled jobs and derive monitor_slug values.
2. Send in_progress and terminal check-ins for each job execution.
3. Upsert monitor configuration based on the library's schedule definition.

Known integrations include Celery Beat (Python), node-cron / cron / node-schedule (JavaScript), Sidekiq-Cron (Ruby), and Oban/Quantum (Elixir).

A check-in is sent as a check_in envelope item containing a JSON object.

{
  "check_in_id": "83a7c03ed0a04e1b97e2e3b18d38f244",
  "monitor_slug": "my-monitor",
  "status": "in_progress",
  "duration": 10.0,
  "release": "1.0.0",
  "environment": "production",
  "contexts": {
    "trace": {
      "trace_id": "8f431b7aa08441bbbd5a0100fd91f9fe"
    }
  }
}

Envelope constraints:

• A check_in item MUST occur at most once per envelope.
• This item can either be included in an Envelope with other items, or it MAY be sent by itself.
• Maximum item size: 100 KiB.

Envelope Headers: None

Additional Item Headers: None

When included, the monitor_config object supports the following fields:

{
  "monitor_config": {
    "schedule": {
      "type": "crontab",
      "value": "0 * * * *"
    },
    "checkin_margin": 5,
    "max_runtime": 30,
    "failure_issue_threshold": 2,
    "recovery_threshold": 2,
    "timezone": "America/Los_Angeles",
    "owner": "user:john@example.com"
  }
}

The schedule object MUST contain a type field set to either crontab or interval.

Crontab schedule:

Interval schedule:

SDKs MUST expose a top-level function to send a check-in:

captureCheckIn(checkIn, monitorConfig?) -> checkInId

Parameters:

• checkIn — Object containing at minimum monitorSlug and status. For terminal check-ins, also includes checkInId (from the initial in_progress call) and optionally duration.
• monitorConfig — OPTIONAL. Monitor configuration for upsert (schedule, margins, thresholds).

Returns: The checkInId (string), so callers can correlate the in_progress and terminal check-ins.

Naming SHOULD follow the SDK's language conventions:

• captureCheckIn (JavaScript, Java)
• capture_check_in (Python, Ruby, Elixir)
• CaptureCheckIn (Go, .NET)

SDKs SHOULD expose a higher-level wrapper that automatically sends in_progress and ok/error check-ins around a callback:

withMonitor(monitorSlug, callback, monitorConfig?) -> callbackResult

The wrapper MUST:

1. Send an in_progress check-in before invoking the callback.
2. Send an ok check-in if the callback completes without error.
3. Send an error check-in if the callback throws or returns a failure.
4. Compute and include duration in the terminal check-in.

SDKs MAY additionally provide language-idiomatic alternatives:

• Decorators (Python): @monitor(monitor_slug='slug')
• Context managers (Python): with monitor(monitor_slug='slug'):
• Mixins (Ruby): include Sentry::Cron::MonitorCheckIns
• Annotations (Java/Kotlin): framework-specific annotations

Check-in events MUST NOT go through the beforeSend hook. The beforeSend hook is reserved for error events.

SDKs MAY implement a dedicated beforeSendCheckIn hook that applies only to check-in events.