Labsco
getsentry logo

sentry-android-sdk

โ˜… 233

by getsentry ยท part of getsentry/sentry-for-claude

Full Sentry SDK setup for Android. Use when asked to "add Sentry to Android", "install sentry-android", "setup Sentry in Android", or configure error monitoring, tracing, profiling, session replay, or logging for Android applications. Supports Kotlin and Java codebases.

๐Ÿ”Œ This skill ships inside the sentry plugin โ€” install the plugin and you also get 1 slash commands, an MCP server.

This is the playbook your agent receives when the skill activates โ€” you don't need to read it to use the skill, but it's here to audit before installing.

All Skills > SDK Setup > 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/ before implementing.


Phase 1: Detect

Run these commands to understand the project before making any recommendations:

# 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:

QuestionImpact
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:

FeatureRecommend when...
Error MonitoringAlways โ€” non-negotiable baseline for any Android app
TracingAlways for Android โ€” app start time, Activity lifecycle, network latency matter
Session ReplayUser-facing production app on API 26+; visual debugging of user issues
ProfilingPerformance-sensitive apps, startup time investigations, production perf analysis
LoggingApp uses structured logging or you want log-to-trace correlation in Sentry
User FeedbackBeta 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 typeRecommended setupComplexity
New project, no existing SentryGradle plugin (recommended)Low โ€” plugin handles most config
Existing project, no SentryGradle plugin or manual initMedium โ€” add dependency + Application class
Manual full controlSentryAndroid.init() in ApplicationMedium โ€” explicit config, most flexible

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.

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

[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:

plugins {
    alias(libs.plugins.sentry.android.gradle) apply false
}

App-level app/build.gradle.kts:

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:

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.


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):

plugins {
    id "io.sentry.android.gradle" version "6.1.0" apply false
}

Kotlin DSL (build.gradle.kts):

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:

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):

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
}

Step 3 โ€” Initialize Sentry in your Application class

If you don't have an Application subclass, create one:

// MyApplication.kt
import android.app.Application
import io.sentry.SentryLevel
import io.sentry.android.core.SentryAndroid
import io.sentry.android.replay.SentryReplayOptions

class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()

        SentryAndroid.init(this) { options ->
            options.dsn = "YOUR_SENTRY_DSN"

            // Tracing โ€” lower to 0.1โ€“0.2 in high-traffic production
            options.tracesSampleRate = 1.0

            // Profiling โ€” use continuous UI profiling (recommended, SDK โ‰ฅ 8.7.0)
            options.profileSessionSampleRate = 1.0

            // Session Replay (API 26+ only; silent no-op below API 26)
            options.sessionReplay.sessionSampleRate = 0.1    // 10% of all sessions
            options.sessionReplay.onErrorSampleRate = 1.0    // 100% on error

            // Structured logging
            options.logs.isEnabled = true

            // Environment
            options.environment = BuildConfig.BUILD_TYPE
        }
    }
}

Java equivalent:

// MyApplication.java
import android.app.Application;
import io.sentry.android.core.SentryAndroid;

public class MyApplication extends Application {
    @Override
    public void onCreate() {
        super.onCreate();

        SentryAndroid.init(this, options -> {
            options.setDsn("YOUR_SENTRY_DSN");
            options.setTracesSampleRate(1.0);
            options.setProfileSessionSampleRate(1.0);
            options.getSessionReplay().setSessionSampleRate(0.1);
            options.getSessionReplay().setOnErrorSampleRate(1.0);
            options.getLogs().setEnabled(true);
            options.setEnvironment(BuildConfig.BUILD_TYPE);
        });
    }
}

Step 4 โ€” Register Application in AndroidManifest.xml

<application
    android:name=".MyApplication"
    ... >

Path B: Manual Setup (No Gradle Plugin)

Use this if you can't use the Gradle plugin (e.g., non-standard build setups).

Step 1 โ€” Add dependency in app/build.gradle[.kts]

dependencies {
    implementation(platform("io.sentry:sentry-bom:8.33.0"))
    implementation("io.sentry:sentry-android")
}

Step 2 โ€” Initialize in Application class (same as Path A, Step 3)

Step 3 โ€” Configure ProGuard/R8 manually

The Sentry SDK ships a ProGuard rules file automatically. For manual mapping upload, install sentry-cli and add to your CI:

sentry-cli releases files "my-app@1.0.0+42" upload-proguard \
  --org YOUR_ORG --project YOUR_PROJECT \
  app/build/outputs/mapping/release/mapping.txt

SentryAndroid.init(this) { options ->
    options.dsn = "YOUR_SENTRY_DSN"

    // Environment and release
    options.environment = BuildConfig.BUILD_TYPE     // "debug", "release", etc.
    options.release = "${BuildConfig.APPLICATION_ID}@${BuildConfig.VERSION_NAME}+${BuildConfig.VERSION_CODE}"

    // Tracing โ€” sample 100% in dev, lower to 10โ€“20% in production
    options.tracesSampleRate = 1.0

    // Continuous UI profiling (recommended over transaction-based)
    options.profileSessionSampleRate = 1.0

    // Session Replay (API 26+; silent no-op on API 21โ€“25)
    options.sessionReplay.sessionSampleRate = 0.1
    options.sessionReplay.onErrorSampleRate = 1.0
    options.sessionReplay.maskAllText = true         // mask text for privacy
    options.sessionReplay.maskAllImages = true       // mask images for privacy

    // Structured logging
    options.logs.isEnabled = true

    // Error enrichment
    options.isAttachScreenshot = true                // capture screenshot on error
    options.isAttachViewHierarchy = true             // attach view hierarchy JSON

    // ANR detection (5s default; watchdog + ApplicationExitInfo API 30+)
    options.isAnrEnabled = true

    // NDK native crash handling (enabled by default)
    options.isEnableNdk = true

    // Send PII: IP address, user data
    options.sendDefaultPii = true

    // Trace propagation (backend distributed tracing)
    options.tracePropagationTargets = listOf("api.yourapp.com", ".*\\.yourapp\\.com")

    // Verbose logging โ€” disable in production
    options.isDebug = BuildConfig.DEBUG
}

For Each Agreed Feature

Walk through features one at a time. Load the reference file for each, follow its steps, then verify before moving on:

FeatureReferenceLoad when...
Error Monitoring${SKILL_ROOT}/references/error-monitoring.mdAlways (baseline)
Tracing & Performance${SKILL_ROOT}/references/tracing.mdAlways for Android (Activity lifecycle, network)
Profiling${SKILL_ROOT}/references/profiling.mdPerformance-sensitive production apps
Session Replay${SKILL_ROOT}/references/session-replay.mdUser-facing apps (API 26+)
Logging${SKILL_ROOT}/references/logging.mdStructured logging / log-to-trace correlation
Metrics${SKILL_ROOT}/references/metrics.mdCustom metric tracking (SDK โ‰ฅ 8.30.0)
Crons${SKILL_ROOT}/references/crons.mdScheduled jobs, WorkManager check-ins
Integration Reference${SKILL_ROOT}/references/integrations.mdBuilt-in, optional, and Gradle bytecode integrations

For each feature: Read ${SKILL_ROOT}/references/<feature>.md, follow steps exactly, verify it works.


Verification

After setup, verify Sentry is receiving events:

Test error capture:

// In an Activity or Fragment
try {
    throw RuntimeException("Sentry Android SDK test")
} catch (e: Exception) {
    Sentry.captureException(e)
}

Test tracing:

val transaction = Sentry.startTransaction("test-task", "task")
val span = transaction.startChild("test-span", "description")
span.finish()
transaction.finish()

Test structured logging (SDK โ‰ฅ 8.12.0):

Sentry.logger().info("Sentry logging test")
Sentry.logger().error("Error log test", Exception("test error"))

Check the Sentry dashboard:

  • Issues โ†’ your test exception should appear within seconds
  • Traces โ†’ look for test-task transaction with child span
  • Replays โ†’ session recording visible after app interaction (requires API 26+)
  • Logs โ†’ structured log entries visible under Logs tab

If nothing appears:

  1. Set options.isDebug = true โ€” SDK logs to Logcat
  2. Verify DSN is correct and matches your Sentry project
  3. Check that your Application class is registered in AndroidManifest.xml as android:name
  4. Confirm the device/emulator has internet connectivity
  5. For NDK crashes, ensure isEnableNdk = true (default) and build with NDK support

After completing Android setup, check for a backend or web frontend missing Sentry coverage:

# Adjacent backend directories
ls ../backend ../server ../api 2>/dev/null
cat ../go.mod 2>/dev/null | head -3
cat ../requirements.txt ../pyproject.toml 2>/dev/null | head -5
cat ../Gemfile 2>/dev/null | head -3
ls ../backend/package.json ../server/package.json 2>/dev/null

# iOS counterpart app
ls ../ios ../YourApp-iOS 2>/dev/null
find .. -maxdepth 3 -name "*.xcodeproj" 2>/dev/null | head -3

If a backend or related platform exists without Sentry, suggest the matching skill:

DetectedSuggest skill
Go backend (go.mod)sentry-go-sdk
Python backend (requirements.txt, pyproject.toml)sentry-python-sdk
Ruby backend (Gemfile)sentry-ruby-sdk
Node.js backend@sentry/node โ€” see docs.sentry.io/platforms/javascript/guides/express/
iOS app (.xcodeproj)sentry-cocoa-sdk
React Native (package.json with react-native)sentry-react-native-sdk
React / Next.js websentry-react-sdk or sentry-nextjs-sdk

Distributed tracing setup โ€” if the backend skill is added, configure tracePropagationTargets in Android to propagate trace context to your API:

options.tracePropagationTargets = listOf(
    "api.yourapp.com",
    ".*\\.yourapp\\.com"
)

This links mobile transactions to backend traces in the Sentry waterfall view.