Sentry Android Sdk

# Crons / Monitors — Sentry Android SDK

> **Minimum SDK:** `io.sentry:sentry-android` (any version — uses core Java SDK APIs)  
> **Status:** Stable (`Sentry.captureCheckIn()`); `CheckInUtils` is `@ApiStatus.Experimental`  
> **Docs:** https://docs.sentry.io/platforms/java/crons/ (Android-specific page returns 404)

---

## Overview

Sentry Crons lets you monitor scheduled jobs, background sync workers, and periodic tasks. A **check-in** signals to Sentry that a job started (`IN_PROGRESS`) and completed (`OK`) or failed (`ERROR`). If a check-in is missed or overdue, Sentry fires an alert.

**Key facts for Android:**

- Uses the core Java SDK — no Android-specific integration or module exists
- No `SentryWorker`, no WorkManager adapter, no AlarmManager wrapper — all wiring is manual
- `duration` is in **seconds as a Double**, not milliseconds
- `CheckInUtils` helper is `@ApiStatus.Experimental` (API may change between releases)
- Rate limit: 6 check-ins per minute per monitor per environment

---

## Pattern A — `CheckInUtils.withCheckIn()` (Recommended)

`CheckInUtils` is the simplest API. It sends `IN_PROGRESS` on entry, automatically calculates duration, and sends `OK` on success or `ERROR` on exception.

> **Note:** `CheckInUtils` carries `@ApiStatus.Experimental`. Prefer Pattern B for production code where you need stable guarantees.

```kotlin
import io.sentry.CheckInUtils
import io.sentry.MonitorConfig
import io.sentry.MonitorSchedule

// Minimal — slug only
CheckInUtils.withCheckIn("nightly-sync") {
    performNightlySync()
}

// With upsert config — creates or updates the monitor automatically
val monitorConfig = MonitorConfig(MonitorSchedule.crontab("0 2 * * *")).apply {
    setCheckinMargin(5L)     // alert if check-in is 5+ minutes late
    setMaxRuntime(60L)       // alert if running for 60+ minutes
    setTimezone("UTC")
}

CheckInUtils.withCheckIn("nightly-sync", "production", monitorConfig) {
    performNightlySync()
}
```

**Full signature:**

```kotlin
CheckInUtils.withCheckIn(
    monitorSlug:  String,           // required — must match slug in Sentry dashboard
    environment:  String?,          // null → uses SDK default environment
    monitorConfig: MonitorConfig?,  // null → no upsert; monitor must exist in dashboard
    callable: Callable<T>
): T
```

---

## Pattern B — Manual Two-Step (Full Control)

Send `IN_PROGRESS` before the job starts, then `OK` or `ERROR` when it finishes. This gives you full control over duration and error handling.

```kotlin
import io.sentry.CheckIn
import io.sentry.CheckInStatus
import io.sentry.MonitorConfig
import io.sentry.MonitorSchedule
import io.sentry.Sentry

fun runDatabaseBackup() {
    val startedAt = SystemClock.elapsedRealtime()

    // 1. Signal that the job has started
    val startCheckIn = CheckIn("db-backup", CheckInStatus.IN_PROGRESS)
    val checkInId    = Sentry.captureCheckIn(startCheckIn)

    val status: CheckInStatus
    try {
        performBackup()
        status = CheckInStatus.OK
    } catch (e: Exception) {
        Sentry.captureException(e)   // also capture the error for Sentry Issues
        status = CheckInStatus.ERROR
    }

    // 2. Signal completion — link via checkInId
    val elapsed = SystemClock.elapsedRealtime() - startedAt
    val done = CheckIn(checkInId, "db-backup", status).apply {
        // ⚠️ Duration is in SECONDS (Double), not milliseconds
        setDuration(elapsed / 1000.0)
        setMonitorConfig(
            MonitorConfig(MonitorSchedule.crontab("0 3 * * *")).apply {
                setTimezone("UTC")
                setMaxRuntime(45L)
                setCheckinMargin(10L)
            }
        )
    }
    Sentry.captureCheckIn(done)
}
```

> **⚠️ Duration is in SECONDS, not milliseconds.** Always divide elapsed milliseconds by `1000.0`:
> ```kotlin
> setDuration(SystemClock.elapsedRealtime() - startMs) / 1000.0)  // CORRECT
> setDuration(SystemClock.elapsedRealtime() - startMs)             // WRONG — 1000× too large