sentry-android-sdk

$27

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:

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**

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

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

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

Quick Reference: Full-Featured SentryAndroid.init()

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

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

Integration Reference

Built-in (Auto-Enabled)

These integrations activate automatically when SentryAndroid.init() is called:

Integration

What it does

UncaughtExceptionHandlerIntegration

Captures all uncaught Java/Kotlin exceptions

AnrIntegration

ANR detection via watchdog thread (5s) + ApplicationExitInfo (API 30+)

NdkIntegration

Native (C/C++) crash capture via sentry-native

ActivityLifecycleIntegration

Auto-instruments Activity create/resume/pause for TTID/TTFD

AppStartMetrics

Measures cold/warm/hot app start time

NetworkBreadcrumbsIntegration

Records connectivity changes as breadcrumbs

SystemEventsBreadcrumbsIntegration

Records battery, screen on/off, etc.

AppLifecycleIntegration

Records foreground/background transitions

UserInteractionIntegration

Breadcrumbs for taps, swipes, input events

CurrentActivityIntegration

Tracks active Activity for context

Optional Integrations

Add the artifact to your dependencies {} block (versions managed by BOM):

Integration

Artifact

When to add

Timber

io.sentry:sentry-android-timber

App uses Timber for logging

Fragment

io.sentry:sentry-android-fragment

App uses Jetpack Fragments (lifecycle tracing)

Compose

io.sentry:sentry-compose-android

App uses Jetpack Compose (navigation + masking)

Navigation

io.sentry:sentry-android-navigation

App uses Jetpack Navigation Component

OkHttp

io.sentry:sentry-okhttp

App uses OkHttp or Retrofit

Room/SQLite

io.sentry:sentry-android-sqlite

App uses Room or raw SQLite

Apollo 3

io.sentry:sentry-apollo-3

App uses Apollo GraphQL v3

Apollo 4

io.sentry:sentry-apollo-4

App uses Apollo GraphQL v4

Kotlin Extensions

io.sentry:sentry-kotlin-extensions

Kotlin coroutines context propagation

Ktor Client

io.sentry:sentry-ktor-client

App uses Ktor HTTP client

LaunchDarkly

io.sentry:sentry-launchdarkly-android

App uses LaunchDarkly feature flags

Gradle Plugin Bytecode Instrumentation

The plugin can inject instrumentation automatically (no source changes):

Feature

Instruments

Enable via

DATABASE

Room DAO, SupportSQLiteOpenHelper

tracingInstrumentation.features

FILE_IO

FileInputStream, FileOutputStream

tracingInstrumentation.features

OKHTTP

OkHttpClient.Builder automatically

tracingInstrumentation.features

COMPOSE

NavHostController auto-instrumentation

tracingInstrumentation.features

LOGCAT

android.util.Log capturing

tracingInstrumentation.features

Configuration Reference

Core SentryOptions (via SentryAndroid.init )

Option

Type

Default

Purpose

dsn

String

—

Required. Project DSN; SDK silently disabled if empty

environment

String

—

e.g., "production", "staging". Env: SENTRY_ENVIRONMENT

release

String

—

App version, e.g., "my-app@1.0.0+42". Env: SENTRY_RELEASE

dist

String

—

Build variant / distribution identifier

sendDefaultPii

Boolean

false

Include PII: IP address, user data

sampleRate

Double

1.0

Error event sampling (0.0–1.0)

maxBreadcrumbs

Int

100

Max breadcrumbs per event

isAttachStacktrace

Boolean

true

Auto-attach stack traces to message events

isAttachScreenshot

Boolean

false

Capture screenshot on error

isAttachViewHierarchy

Boolean

false

Attach JSON view hierarchy as attachment

isDebug

Boolean

false

Verbose SDK output. Never use in production

isEnabled

Boolean

true

Disable SDK entirely (e.g., for testing)

beforeSend

SentryOptions.BeforeSendCallback

—

Modify or drop error events before sending

beforeBreadcrumb

SentryOptions.BeforeBreadcrumbCallback

—

Filter breadcrumbs before storage

Tracing Options

Option

Type

Default

Purpose

tracesSampleRate

Double

0.0

Transaction sample rate (0–1). Use 1.0 in dev

tracesSampler

TracesSamplerCallback

—

Per-transaction sampling; overrides tracesSampleRate

tracePropagationTargets

List<String>

[".*"]

Hosts/URLs to receive sentry-trace and baggage headers

isEnableAutoActivityLifecycleTracing

Boolean

true

Auto-instrument Activity lifecycle

isEnableTimeToFullDisplayTracing

Boolean

false

TTFD spans (requires Sentry.reportFullyDisplayed())

isEnableUserInteractionTracing

Boolean

false

Auto-instrument user gestures as transactions

Profiling Options

Option

Type

Default

Purpose

profileSessionSampleRate

Double

0.0

Continuous profiling sample rate (SDK ≥ 8.7.0, API 22+)

profilesSampleRate

Double

0.0

Legacy transaction profiling rate (mutually exclusive with continuous)

isProfilingStartOnAppStart

Boolean

false

Auto-start profiling session on app launch

ANR Options

Option

Type

Default

Purpose

isAnrEnabled

Boolean

true

Enable ANR watchdog thread

anrTimeoutIntervalMillis

Long

5000

Milliseconds before reporting ANR

isAnrReportInDebug

Boolean

false

Report ANRs in debug builds (noisy in debugger)

NDK Options

Option

Type

Default

Purpose

isEnableNdk

Boolean

true

Enable native crash capture via sentry-native

isEnableScopeSync

Boolean

true

Sync Java scope (user, tags) to NDK layer

isEnableTombstoneFetchJob

Boolean

true

Fetch NDK tombstone files for enrichment

Session Replay Options ( options.sessionReplay )

Option

Type

Default

Purpose

sessionSampleRate

Double

0.0

Fraction of all sessions to record

onErrorSampleRate

Double

0.0

Fraction of error sessions to record

maskAllText

Boolean

true

Mask all text in replays

maskAllImages

Boolean

true

Mask all images in replays

quality

SentryReplayQuality

MEDIUM

Video quality: LOW, MEDIUM, HIGH

Logging Options ( options.logs )

Option

Type

Default

Purpose

isEnabled

Boolean

false

Enable Sentry.logger() API (SDK ≥ 8.12.0)

setBeforeSend

BeforeSendLogCallback

—

Filter/modify log entries before sending

Environment Variables

Variable

Purpose

Notes

SENTRY_DSN

Data Source Name

Set in CI; SDK reads from environment at init

SENTRY_AUTH_TOKEN

Upload ProGuard mappings and source context

Never commit — use CI/CD secrets

SENTRY_ORG

Organization slug

Used by Gradle plugin sentry.org

SENTRY_PROJECT

Project slug

Used by Gradle plugin sentry.projectName

SENTRY_RELEASE

Release identifier

Falls back from options.release

SENTRY_ENVIRONMENT

Environment name

Falls back from options.environment

You can also configure DSN and many options via AndroidManifest.xml meta-data:

<application>

    <meta-data android:name="io.sentry.dsn" android:value="YOUR_DSN" />

    <meta-data android:name="io.sentry.traces-sample-rate" android:value="1.0" />

    <meta-data android:name="io.sentry.environment" android:value="production" />

    <meta-data android:name="io.sentry.anr.enable" android:value="true" />

    <meta-data android:name="io.sentry.attach-screenshot" android:value="true" />

    <meta-data android:name="io.sentry.attach-view-hierarchy" android:value="true" />

</application>

⚠️ Manifest meta-data is a convenient alternative but does not support the full option set. For complex configuration (session replay, profiling, hooks), use SentryAndroid.init().

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:

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

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

options.tracePropagationTargets = listOf(

    "api.yourapp.com",

    ".*\\.yourapp\\.com"

)

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

Troubleshooting

Issue

Solution

Events not appearing in Sentry

Set isDebug = true, check Logcat for SDK errors; verify DSN is correct and matches your project

SentryAndroid.init() not called

Confirm android:name=".MyApplication" is set in AndroidManifest.xml; Application class not abstract

Gradle plugin not found

Add the plugin to project-level build.gradle.kts first, then apply false; verify version 6.1.0

ProGuard mapping not uploading

Set SENTRY_AUTH_TOKEN env var; ensure autoUploadProguardMapping = true in sentry {} block

NDK crashes not captured

Verify isEnableNdk = true (default); ensure project has NDK configured in android.ndkVersion

ANR reported in debugger

Set isAnrReportInDebug = false (default); ANR watchdog fires when debugger pauses threads

Session replay not recording

Requires API 26+; verify sessionSampleRate > 0 or onErrorSampleRate > 0; check Logcat for replay errors

Session replay shows blank screen

PixelCopy (default) requires hardware acceleration; try SentryReplayOptions.screenshotQuality = CANVAS

Replay masking misaligned

Views with translationX/Y or clipToPadding=false can offset masks; report to github.com/getsentry/sentry-java

beforeSend not firing

beforeSend only intercepts managed (Java/Kotlin) events; NDK native crashes bypass it

OkHttp spans not appearing

Add SentryOkHttpInterceptor to your OkHttpClient, or use Gradle plugin OKHTTP bytecode instrumentation

Spans not attached to transaction

Ensure TransactionOptions().setBindToScope(true) when starting transaction; child spans look for scope root

Tracing not recording

Verify tracesSampleRate > 0; Activity instrumentation requires isEnableAutoActivityLifecycleTracing = true (default)

Continuous profiling not working

SDK ≥ 8.7.0 required; API 22+ required; set profileSessionSampleRate > 0; don't also set profilesSampleRate

Both profiling modes set

profilesSampleRate and profileSessionSampleRate are mutually exclusive — use only one

TTFD spans missing

Set isEnableTimeToFullDisplayTracing = true and call Sentry.reportFullyDisplayed() when screen is ready

Kotlin coroutine scope lost

Add sentry-kotlin-extensions dependency; use Sentry.cloneMainContext() to propagate trace context

Release build stack traces unreadable

ProGuard mapping not uploaded; confirm Gradle plugin autoUploadProguardMapping = true and auth token set

Source context not showing in Sentry

Enable includeSourceContext = true in sentry {} block (Gradle plugin required)

BOM version conflict

Use implementation(platform("io.sentry:sentry-bom:8.33.0")) and omit versions from all other io.sentry:* entries

Version catalog alias unresolved

After editing gradle/libs.versions.toml, sync Gradle; alias names use - in TOML and . in build files (e.g., sentry-android → libs.sentry.android)

Duplicate Sentry version in catalog

Reuse the existing [versions] sentry = "..." entry; don't add a second key, and don't hardcode the version in build.gradle when the catalog is in use

SENTRY_AUTH_TOKEN exposed

Auth token is build-time only — never pass it to SentryAndroid.init() or embed in the APK