sentry-android-sdk

> [All Skills](../../SKILL_TREE.md) > [SDK Setup](../sentry-sdk-setup/SKILL.md) > Android SDK # Sentry Android SDK Opinionated wizard that scans your Android project and guides you through complete Sentry setup — error monitoring, tracing, profiling, session replay, logging, and more. ## Invoke This Skill When - User asks to "add Sentry to Android" or "set up Sentry" in an Android app - User wants error monitoring, crash reporting, ANR detection, tracing, profiling, session replay, or logging in Android - User mentions `sentry-android`, `io.sentry:sentry-android`, mobile crash tracking, or Sentry for Kotlin/Java Android - User wants to monitor native (NDK) crashes, application not responding (ANR) events, or app startup performance > **Note:** SDK versions and APIs below reflect current Sentry docs at time of writing (`io.sentry:sentry-android:8.33.0`, Gradle plugin `6.1.0`). > Always verify against [docs.sentry.io/platforms/android/](https://docs.sentry.io/platforms/android/) before implementing. --- ## Phase 1: Detect Run these commands to understand the project before making any recommendations: ```bash # Detect project structure and build system ls build.gradle build.gradle.kts settings.gradle settings.gradle.kts 2>/dev/null # Check AGP version and existing Sentry grep -r '"com.android.application"' build.gradle* app/build.gradle* 2>/dev/null | head -3 grep -ri sentry build.gradle* app/build.gradle* 2>/dev/null | head -10 # Check app-level build file (Groovy vs KTS) ls app/build.gradle app/build.gradle.kts 2>/dev/null # Detect Gradle version catalog (libs.versions.toml) — modern AGP projects ls gradle/libs.versions.toml 2>/dev/null # Check for existing Sentry entries in the version catalog grep -iE 'sentry|io\.sentry' gradle/libs.versions.toml 2>/dev/null | head -10 # Check if build files reference the catalog (alias/libs.* usage) grep -E 'alias\(libs\.|libs\.[a-zA-Z]' build.gradle build.gradle.kts app/build.gradle app/build.gradle.kts 2>/dev/null | head -5 # Detect Kotlin vs Java find app/src/main -name "*.kt" 2>/dev/null | head -3 find app/src/main -name "*.java" 2>/dev/null | head -3 # Check minSdk, targetSdk grep -E 'minSdk|targetSdk|compileSdk|minSdkVersion|targetSdkVersion' app/build.gradle app/build.gradle.kts 2>/dev/null | head -6 # Detect Jetpack Compose grep -E 'compose|androidx.compose' app/build.gradle app/build.gradle.kts 2>/dev/null | head -5 # Detect OkHttp (popular HTTP client — has dedicated integration) grep -E 'okhttp|retrofit' app/build.gradle app/build.gradle.kts 2>/dev/null | head -3 # Detect Room or SQLite grep -E 'androidx.room|androidx.sqlite' app/build.gradle app/build.gradle.kts 2>/dev/null | head -3 # Detect Timber (logging library) grep -E 'timber' app/build.gradle app/build.gradle.kts 2>/dev/null | head -3 # Detect Jetpack Navigation grep -E 'androidx.navigation' app/build.gradle app/build.gradle.kts 2>/dev/null | head -3 # Detect Apollo (GraphQL) grep -E 'apollo' app/build.gradle app/build.gradle.kts 2>/dev/null | head -3 # Check existing Sentry initialization grep -r "SentryAndroid.init\|io.sentry.Sentry" app/src/ 2>/dev/null | head -5 # Check Application class find app/src/main -name "*.kt" -o -name "*.java" 2>/dev/null | xargs grep -l "Application()" 2>/dev/null | head -3 # Adjacent backend (for cross-linking) ls ../backend ../server ../api 2>/dev/null find .. -maxdepth 2 \( -name "go.mod" -o -name "requirements.txt" -o -name "Gemfile" \) 2>/dev/null | grep -v node_modules | head -5 ``` **What to determine:** | Question | Impact | |----------|--------| | `build.gradle.kts` present? | Use Kotlin DSL syntax in all examples | | `gradle/libs.versions.toml` present? | Add Sentry to the version catalog; reference via `libs.*` in build files | | Catalog already has `sentry` entries? | Reuse the existing version ref; don't duplicate or hardcode versions | | `minSdk < 26`? | Note Session Replay requires API 26+ — silent no-op below that | | Compose detected? | Recommend `sentry-compose-android` and Compose-specific masking | | OkHttp present? | Recommend `sentry-okhttp` interceptor or Gradle plugin bytecode auto-instrumentation | | Room/SQLite present? | Recommend `sentry-android-sqlite` or plugin bytecode instrumentation | | Timber present? | Recommend `sentry-android-timber` integration | | Jetpack Navigation? | Recommend `sentry-android-navigation` for screen tracking | | Already has `SentryAndroid.init()`? | Skip install, jump to feature config | | Application subclass exists? | That's where `SentryAndroid.init()` goes | --- ## Phase 2: Recommend Present a concrete recommendation based on what you found. Don't ask open-ended questions — lead with a proposal: **Recommended (core coverage — always set up these):** - ✅ **Error Monitoring** — captures uncaught exceptions, ANRs, and native NDK crashes automatically - ✅ **Tracing** — auto-instruments Activity lifecycle, app start, HTTP requests, and database queries - ✅ **Session Replay** — records screen captures and user interactions for debugging (API 26+) **Optional (enhanced observability):** - ⚡ **Profiling** — continuous UI profiling (recommended) or transaction-based sampling - ⚡ **Logging** — structured logs via `Sentry.logger()`, with optional Timber bridge - ⚡ **User Feedback** — collect user-submitted bug reports from inside the app **Recommendation logic:** | Feature | Recommend when... | |---------|------------------| | Error Monitoring | **Always** — non-negotiable baseline for any Android app | | Tracing | **Always for Android** — app start time, Activity lifecycle, network latency matter | | Session Replay | User-facing production app on API 26+; visual debugging of user issues | | Profiling | Performance-sensitive apps, startup time investigations, production perf analysis | | Logging | App uses structured logging or you want log-to-trace correlation in Sentry | | User Feedback | Beta or customer-facing app where you want user-submitted bug reports | Propose: *"For your [Kotlin / Java] Android app (minSdk X), I recommend setting up Error Monitoring + Tracing + Session Replay. Want me to also add Profiling and Logging?"* --- ## Phase 3: Guide ### Determine Your Setup Path | Project type | Recommended setup | Complexity | |-------------|------------------|------------| | New project, no existing Sentry | Gradle plugin (recommended) | Low — plugin handles most config | | Existing project, no Sentry | Gradle plugin or manual init | Medium — add dependency + Application class | | Manual full control | `SentryAndroid.init()` in Application | Medium — explicit config, most flexible | ### Option 1: Wizard (Recommended) > **You need to run this yourself** — the wizard opens a browser for login > and requires interactive input that the agent can't handle. > Copy-paste into your terminal: > > ``` > npx @sentry/wizard@latest -i android > ``` > > It handles login, org/project selection, Gradle plugin setup, dependency > installation, DSN configuration, and ProGuard/R8 mapping upload. > > **Once it finishes, come back and skip to [Verification](#verification).** If the user skips the wizard, proceed with Option 2 (Manual Setup) below. --- ### Option 2: Manual Setup #### Using a Gradle Version Catalog (`gradle/libs.versions.toml`) If Phase 1 detected `gradle/libs.versions.toml`, add Sentry to the catalog **first**, then reference it from your build files. This keeps versions centralized and matches modern AGP project conventions. **Step 1 — Add entries to `gradle/libs.versions.toml`** ```toml [versions] sentry = "8.33.0" sentryGradlePlugin = "6.1.0" [libraries] sentry-android = { module = "io.sentry:sentry-android", version.ref = "sentry" } sentry-bom = { module = "io.sentry:sentry-bom", version.ref = "sentry" } # Optional integrations — add only the ones your project uses: sentry-android-timber = { module = "io.sentry:sentry-android-timber" } sentry-android-fragment = { module = "io.sentry:sentry-android-fragment" } sentry-compose-android = { module = "io.sentry:sentry-compose-android" } sentry-android-navigation = { module = "io.sentry:sentry-android-navigation" } sentry-okhttp = { module = "io.sentry:sentry-okhttp" } sentry-android-sqlite = { module = "io.sentry:sentry-android-sqlite" } sentry-kotlin-extensions = { module = "io.sentry:sentry-kotlin-extensions" } [plugins] sentry-android-gradle = { id = "io.sentry.android.gradle", version.ref = "sentryGradlePlugin" } ``` > **Note:** Optional integration entries omit `version.ref` — their versions come from the BOM at resolution time. Only `sentry-bom` needs the version ref. > If the catalog already defines a `sentry` version, reuse it instead of adding a duplicate entry. **Step 2 — Reference the catalog from `build.gradle[.kts]`** Project-level `build.gradle.kts`: ```kotlin plugins { alias(libs.plugins.sentry.android.gradle) apply false } ``` App-level `app/build.gradle.kts`: ```kotlin plugins { id("com.android.application") alias(libs.plugins.sentry.android.gradle) } dependencies { implementation(platform(libs.sentry.bom)) implementation(libs.sentry.android) // implementation(libs.sentry.okhttp) // implementation(libs.sentry.compose.android) } ``` Groovy DSL (`app/build.gradle`) equivalent: ```groovy plugins { id "com.android.application" alias libs.plugins.sentry.android.gradle } dependencies { implementation platform(libs.sentry.bom) implementation libs.sentry.android } ``` Then continue with the `sentry {}` configuration block from Path A, Step 2 below. The rest of the setup (Application class init, manifest registration, verification) is identical. --- #### Path A: Gradle Plugin (Recommended) The Sentry Gradle plugin is the easiest setup path. It: - Uploads ProGuard/R8 mapping files automatically on release builds - Injects source context into stack frames - Optionally instruments OkHttp, Room/SQLite, File I/O, Compose navigation, and `android.util.Log` via bytecode transforms (zero source changes) **Step 1 — Add the plugin to `build.gradle[.kts]` (project-level)** Groovy DSL (`build.gradle`): ```groovy plugins { id "io.sentry.android.gradle" version "6.1.0" apply false } ``` Kotlin DSL (`build.gradle.kts`): ```kotlin plugins { id("io.sentry.android.gradle") version "6.1.0" apply false } ``` **Step 2 — Apply plugin + add dependencies in `app/build.gradle[.kts]`** Groovy DSL: ```groovy plugins { id "com.android.application" id "io.sentry.android.gradle" } android { // ... } dependencies { // Use BOM for consistent versions across sentry modules implementation platform("io.sentry:sentry-bom:8.33.0") implementation "io.sentry:sentry-android" // Optional integrations (add what's relevant): // implementation "io.sentry:sentry-android-timber" // Timber bridge // implementation "io.sentry:sentry-android-fragment" // Fragment lifecycle tracing // implementation "io.sentry:sentry-compose-android" // Jetpack Compose support // implementation "io.sentry:sentry-android-navigation" // Jetpack Navigation // implementation "io.sentry:sentry-okhttp" // OkHttp interceptor // implementation "io.sentry:sentry-android-sqlite" // Room/SQLite tracing // implementation "io.sentry:sentry-kotlin-extensions" // Coroutine context propagation } sentry { org = "YOUR_ORG_SLUG" projectName = "YOUR_PROJECT_SLUG" authToken = System.getenv("SENTRY_AUTH_TOKEN") // Enable auto-instrumentation via bytecode transforms (no source changes needed) tracingInstrumentation { enabled = true features = [InstrumentationFeature.DATABASE, InstrumentationFeature.FILE_IO, InstrumentationFeature.OKHTTP, InstrumentationFeature.COMPOSE] } // Upload ProGuard mapping and source context on release autoUploadProguardMapping = true includeSourceContext = true } ``` Kotlin DSL (`app/build.gradle.kts`): ```kotlin plugins { id("com.android.application") id("io.sentry.android.gradle") } dependencies { implementation(platform("io.sentry:sentry-bom:8.33.0")) implementation("io.sentry:sentry-android") // Optional integrations: // implementation("io.sentry:sentry-android-timber") // implementation("io.sentry:sentry-android-fragment") // implementation("io.sentry:sentry-compose-android") // implementation("io.sentry:sentry-android-navigation") // implementation("io.sentry:sentry-okhttp") // implementation("io.sentry:sentry-android-sqlite") // implementation("io.sentry:sentry-kotlin-extensions") } sentry { org = "YOUR_ORG_SLUG" projectName = "YOUR_PROJECT_SLUG" authToken = System.getenv("SENTRY_AUTH_TOKEN") tracingInstrumentation { enabled = true features = setOf( InstrumentationFeature.DATABASE, InstrumentationFeature.FILE_IO, InstrumentationFeature.OKHTTP, InstrumentationFeature.COMPOSE, ) } autoUploadProguardMapping = true includeSourceContext = true } ```