Labsco
getsentry logo

sentry-android-sdk

✓ Official★ 232

by sentry · part of getsentry/sentry-for-ai

Full Sentry SDK setup for Android. Use when asked to "add Sentry to Android", "install sentry-android", "setup Sentry in Android", or configure error…

🔥🔥🔥🔥✓ VerifiedAccount requiredAdvanced setup
#email#automation#database#devops#git#monitoring#translation
🧰 Not standalone. This skill ships with getsentry/sentry-for-ai and only works together with that tool — install the tool first, then add this skill.

Full Sentry SDK setup for Android. Use when asked to "add Sentry to Android", "install sentry-android", "setup Sentry in Android", or configure error…

Inspect the full instructions your agent will receiveExpand

This is the exact playbook injected into your agent when the skill activates — shown here so you can audit it before installing. You don't need to read it to use the skill.

by sentry

Full Sentry SDK setup for Android. Use when asked to "add Sentry to Android", "install sentry-android", "setup Sentry in Android", or configure error… npx skills add https://github.com/getsentry/sentry-for-ai --skill sentry-android-sdk Download ZIPGitHub232

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:

Copy & paste — that's it
# 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:

Copy & paste — that's it
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

Copy & paste — that's it
[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:

Copy & paste — that's it
plugins {
 alias(libs.plugins.sentry.android.gradle) apply false
}

App-level app/build.gradle.kts:

Copy & paste — that's it
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:

Copy & paste — that's it
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):

Copy & paste — that's it
plugins {
 id "io.sentry.android.gradle" version "6.1.0" apply false
}

Kotlin DSL (build.gradle.kts):

Copy & paste — that's it
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:

Copy & paste — that's it
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):

Copy & paste — that's it
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:

Copy & paste — that's it
// 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:

Copy & paste — that's it
// 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

Copy & paste — that's it

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]

Copy & paste — that's it
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:

Copy & paste — that's it
sentry-cli releases files "[email protected]+42" upload-proguard \
 --org YOUR_ORG --project YOUR_PROJECT \
 app/build/outputs/mapping/release/mapping.txt

Quick Reference: Full-Featured SentryAndroid.init()

Copy & paste — that's it
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:

Feature Reference Load when... Error Monitoring ${SKILL_ROOT}/references/error-monitoring.md Always (baseline) Tracing & Performance ${SKILL_ROOT}/references/tracing.md Always for Android (Activity lifecycle, network) Profiling ${SKILL_ROOT}/references/profiling.md Performance-sensitive production apps Session Replay ${SKILL_ROOT}/references/session-replay.md User-facing apps (API 26+) Logging ${SKILL_ROOT}/references/logging.md Structured logging / log-to-trace correlation Metrics ${SKILL_ROOT}/references/metrics.md Custom metric tracking (SDK ≥ 8.30.0) Crons ${SKILL_ROOT}/references/crons.md Scheduled jobs, WorkManager check-ins Integration Reference ${SKILL_ROOT}/references/integrations.md Built-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:

Copy & paste — that's it
// In an Activity or Fragment
try {
 throw RuntimeException("Sentry Android SDK test")
} catch (e: Exception) {
 Sentry.captureException(e)
}

Test tracing:

Copy & paste — that's it
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):

Copy & paste — that's it
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:

  • Set options.isDebug = true — SDK logs to Logcat

  • Verify DSN is correct and matches your Sentry project

  • Check that your Application class is registered in AndroidManifest.xml as android:name

  • Confirm the device/emulator has internet connectivity

  • For NDK crashes, ensure isEnableNdk = true (default) and build with NDK support

Phase 4: Cross-Link

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

Copy & paste — that's it
# 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:

Detected Suggest 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 web sentry-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:

Copy & paste — that's it
options.tracePropagationTargets = listOf(
 "api.yourapp.com",
 ".*\\.yourapp\\.com"
)

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