sentry-android-sdk by getsentry/sentry-for-ai
npx skills add https://github.com/getsentry/sentry-for-ai --skill sentry-android-sdk一个智能向导,用于扫描您的 Android 项目并指导您完成完整的 Sentry 设置——错误监控、追踪、性能剖析、会话回放、日志记录等。
sentry-android、io.sentry:sentry-android、移动端崩溃追踪,或用于 Kotlin/Java Android 的 Sentry注意: 下面的 SDK 版本和 API 反映了撰写时的当前 Sentry 文档(
io.sentry:sentry-android:8.33.0,Gradle 插件6.1.0)。在实施前,请务必根据 docs.sentry.io/platforms/android/ 进行验证。
广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
在提出任何建议之前,运行以下命令来了解项目:
# 检测项目结构和构建系统
ls build.gradle build.gradle.kts settings.gradle settings.gradle.kts 2>/dev/null
# 检查 AGP 版本和现有 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
# 检查应用级构建文件(Groovy 与 KTS)
ls app/build.gradle app/build.gradle.kts 2>/dev/null
# 检测 Kotlin 与 Java
find app/src/main -name "*.kt" 2>/dev/null | head -3
find app/src/main -name "*.java" 2>/dev/null | head -3
# 检查 minSdk, targetSdk
grep -E 'minSdk|targetSdk|compileSdk|minSdkVersion|targetSdkVersion' app/build.gradle app/build.gradle.kts 2>/dev/null | head -6
# 检测 Jetpack Compose
grep -E 'compose|androidx.compose' app/build.gradle app/build.gradle.kts 2>/dev/null | head -5
# 检测 OkHttp(流行的 HTTP 客户端——有专门的集成)
grep -E 'okhttp|retrofit' app/build.gradle app/build.gradle.kts 2>/dev/null | head -3
# 检测 Room 或 SQLite
grep -E 'androidx.room|androidx.sqlite' app/build.gradle app/build.gradle.kts 2>/dev/null | head -3
# 检测 Timber(日志库)
grep -E 'timber' app/build.gradle app/build.gradle.kts 2>/dev/null | head -3
# 检测 Jetpack Navigation
grep -E 'androidx.navigation' app/build.gradle app/build.gradle.kts 2>/dev/null | head -3
# 检测 Apollo (GraphQL)
grep -E 'apollo' app/build.gradle app/build.gradle.kts 2>/dev/null | head -3
# 检查现有的 Sentry 初始化
grep -r "SentryAndroid.init\|io.sentry.Sentry" app/src/ 2>/dev/null | head -5
# 检查 Application 类
find app/src/main -name "*.kt" -o -name "*.java" 2>/dev/null | xargs grep -l "Application()" 2>/dev/null | head -3
# 相邻的后端(用于交叉链接)
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
需要确定的内容:
| 问题 | 影响 |
|---|---|
存在 build.gradle.kts? | 在所有示例中使用 Kotlin DSL 语法 |
minSdk < 26? | 注意:会话回放需要 API 26+ —— 低于此版本会静默无操作 |
| 检测到 Compose? | 推荐 sentry-compose-android 和 Compose 特定的遮罩 |
| 存在 OkHttp? | 推荐 sentry-okhttp 拦截器或 Gradle 插件字节码自动插桩 |
| 存在 Room/SQLite? | 推荐 sentry-android-sqlite 或插件字节码插桩 |
| 存在 Timber? | 推荐 sentry-android-timber 集成 |
| 存在 Jetpack Navigation? | 推荐 sentry-android-navigation 用于屏幕追踪 |
已有 SentryAndroid.init()? | 跳过安装,跳转到功能配置 |
| 存在 Application 子类? | 这是放置 SentryAndroid.init() 的地方 |
根据您的发现提出具体建议。不要问开放式问题——直接提出方案:
推荐(核心覆盖范围——始终设置这些):
可选(增强的可观测性):
Sentry.logger() 进行结构化日志记录,可选择 Timber 桥接推荐逻辑:
| 功能 | 何时推荐... |
|---|---|
| 错误监控 | 始终 —— 任何 Android 应用不可或缺的基线 |
| 追踪 | 始终适用于 Android —— 应用启动时间、Activity 生命周期、网络延迟很重要 |
| 会话回放 | 面向用户的、API 26+ 的生产环境应用;用户问题的可视化调试 |
| 性能剖析 | 性能敏感的应用、启动时间调查、生产环境性能分析 |
| 日志记录 | 应用使用结构化日志记录,或者您希望在 Sentry 中进行日志到追踪的关联 |
| 用户反馈 | 希望收集用户提交的错误报告的 Beta 版或面向客户的应用 |
建议:“对于您的 [Kotlin / Java] Android 应用(minSdk X),我建议设置错误监控 + 追踪 + 会话回放。您希望我也添加性能剖析和日志记录吗?”
| 项目类型 | 推荐设置 | 复杂度 |
|---|---|---|
| 新项目,无现有 Sentry | Gradle 插件(推荐) | 低 —— 插件处理大部分配置 |
| 现有项目,无 Sentry | Gradle 插件或手动初始化 | 中 —— 添加依赖项 + Application 类 |
| 手动完全控制 | 在 Application 中使用 SentryAndroid.init() | 中 —— 显式配置,最灵活 |
您需要自己运行此命令 —— 向导会打开浏览器进行登录,并需要交互式输入,这是代理无法处理的。请复制粘贴到您的终端:
npx @sentry/wizard@latest -i android它处理登录、组织/项目选择、Gradle 插件设置、依赖项安装、DSN 配置以及 ProGuard/R8 映射文件上传。
完成后,请返回并跳转到验证部分。
如果用户跳过向导,请继续下面的选项 2(手动设置)。
Sentry Gradle 插件是最简单的设置路径。它:
android.util.Log步骤 1 — 将插件添加到 build.gradle[.kts](项目级)
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
}
步骤 2 — 在 app/build.gradle[.kts] 中应用插件 + 添加依赖项
Groovy DSL:
plugins {
id "com.android.application"
id "io.sentry.android.gradle"
}
android {
// ...
}
dependencies {
// 使用 BOM 确保所有 sentry 模块版本一致
implementation platform("io.sentry:sentry-bom:8.33.0")
implementation "io.sentry:sentry-android"
// 可选集成(添加相关的):
// implementation "io.sentry:sentry-android-timber" // Timber 桥接
// implementation "io.sentry:sentry-android-fragment" // Fragment 生命周期追踪
// implementation "io.sentry:sentry-compose-android" // Jetpack Compose 支持
// implementation "io.sentry:sentry-android-navigation" // Jetpack Navigation
// implementation "io.sentry:sentry-okhttp" // OkHttp 拦截器
// implementation "io.sentry:sentry-android-sqlite" // Room/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 = [InstrumentationFeature.DATABASE, InstrumentationFeature.FILE_IO,
InstrumentationFeature.OKHTTP, InstrumentationFeature.COMPOSE]
}
// 在发布时上传 ProGuard 映射和源代码上下文
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")
// 可选集成:
// 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
}
步骤 3 — 在您的 Application 类中初始化 Sentry
如果您没有 Application 子类,请创建一个:
// 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"
// 追踪 —— 在高流量生产环境中降低到 0.1–0.2
options.tracesSampleRate = 1.0
// 性能剖析 —— 使用持续 UI 性能剖析(推荐,SDK ≥ 8.7.0)
options.profileSessionSampleRate = 1.0
// 会话回放(仅限 API 26+;低于 API 26 会静默无操作)
options.sessionReplay.sessionSampleRate = 0.1 // 所有会话的 10%
options.sessionReplay.onErrorSampleRate = 1.0 // 发生错误时为 100%
// 结构化日志记录
options.logs.isEnabled = true
// 环境
options.environment = BuildConfig.BUILD_TYPE
}
}
}
Java 等价写法:
// 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);
});
}
}
步骤 4 — 在 AndroidManifest.xml 中注册 Application
<application
android:name=".MyApplication"
... >
如果您无法使用 Gradle 插件(例如,非标准构建设置),请使用此方法。
步骤 1 — 在 app/build.gradle[.kts] 中添加依赖项
dependencies {
implementation(platform("io.sentry:sentry-bom:8.33.0"))
implementation("io.sentry:sentry-android")
}
步骤 2 — 在 Application 类中初始化(与路径 A 的步骤 3 相同)
步骤 3 — 手动配置 ProGuard/R8
Sentry SDK 会自动附带一个 ProGuard 规则文件。对于手动映射上传,请安装 sentry-cli 并添加到您的 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()SentryAndroid.init(this) { options ->
options.dsn = "YOUR_SENTRY_DSN"
// 环境和发布版本
options.environment = BuildConfig.BUILD_TYPE // "debug", "release" 等
options.release = "${BuildConfig.APPLICATION_ID}@${BuildConfig.VERSION_NAME}+${BuildConfig.VERSION_CODE}"
// 追踪 —— 在开发中采样 100%,在生产中降低到 10–20%
options.tracesSampleRate = 1.0
// 持续 UI 性能剖析(推荐基于事务的)
options.profileSessionSampleRate = 1.0
// 会话回放(API 26+;在 API 21–25 上静默无操作)
options.sessionReplay.sessionSampleRate = 0.1
options.sessionReplay.onErrorSampleRate = 1.0
options.sessionReplay.maskAllText = true // 为隐私遮罩所有文本
options.sessionReplay.maskAllImages = true // 为隐私遮罩所有图像
// 结构化日志记录
options.logs.isEnabled = true
// 错误增强
options.isAttachScreenshot = true // 发生错误时捕获屏幕截图
options.isAttachViewHierarchy = true // 附加视图层次结构 JSON
// ANR 检测(默认 5 秒;看门狗 + ApplicationExitInfo API 30+)
options.isAnrEnabled = true
// NDK 原生崩溃处理(默认启用)
options.isEnableNdk = true
// 发送 PII:IP 地址、用户数据
options.sendDefaultPii = true
// 追踪传播(后端分布式追踪)
options.tracePropagationTargets = listOf("api.yourapp.com", ".*\\.yourapp\\.com")
// 详细日志记录 —— 在生产环境中禁用
options.isDebug = BuildConfig.DEBUG
}
逐个功能进行指导。为每个功能加载参考文件,按照其步骤操作,然后在继续之前进行验证:
| 功能 | 参考 | 何时加载 |
|---|---|---|
| 错误监控 | ${SKILL_ROOT}/references/error-monitoring.md | 始终(基线) |
| 追踪与性能 | ${SKILL_ROOT}/references/tracing.md | 始终适用于 Android(Activity 生命周期、网络) |
| 性能剖析 | ${SKILL_ROOT}/references/profiling.md | 性能敏感的生产环境应用 |
| 会话回放 | ${SKILL_ROOT}/references/session-replay.md | 面向用户的应用(API 26+) |
| 日志记录 | ${SKILL_ROOT}/references/logging.md | 结构化日志记录 / 日志到追踪的关联 |
| 指标 | ${SKILL_ROOT}/references/metrics.md | 自定义指标追踪(Beta,SDK ≥ 8.30.0) |
| 定时任务 | ${SKILL_ROOT}/references/crons.md | 计划作业、WorkManager 签到 |
对于每个功能:Read ${SKILL_ROOT}/references/<feature>.md,严格按照步骤操作,验证其是否有效。
当调用 SentryAndroid.init() 时,这些集成会自动激活:
| 集成 | 功能 |
|---|---|
UncaughtExceptionHandlerIntegration | 捕获所有未捕获的 Java/Kotlin 异常 |
AnrIntegration | 通过看门狗线程(5 秒)+ ApplicationExitInfo(API 30+)进行 ANR 检测 |
NdkIntegration | 通过 sentry-native 捕获原生(C/C++)崩溃 |
ActivityLifecycleIntegration | 自动插桩 Activity 的创建/恢复/暂停以计算 TTID/TTFD |
AppStartMetrics | 测量冷/温/热应用启动时间 |
NetworkBreadcrumbsIntegration | 将连接状态变化记录为面包屑 |
SystemEventsBreadcrumbsIntegration | 记录电池、屏幕开/关等 |
AppLifecycleIntegration | 记录前台/后台转换 |
UserInteractionIntegration | 记录点击、滑动、输入事件作为面包屑 |
CurrentActivityIntegration | 追踪当前活动的 Activity 以获取上下文 |
将构件添加到您的 dependencies {} 块中(版本由 BOM 管理):
| 集成 | 构件 | 何时添加 |
|---|---|---|
| Timber | io.sentry:sentry-android-timber | 应用使用 Timber 进行日志记录 |
| Fragment | io.sentry:sentry-android-fragment | 应用使用 Jetpack Fragments(生命周期追踪) |
| Compose | io.sentry:sentry-compose-android | 应用使用 Jetpack Compose(导航 + 遮罩) |
| Navigation | io.sentry:sentry-android-navigation | 应用使用 Jetpack Navigation 组件 |
| OkHttp | io.sentry:sentry-okhttp | 应用使用 OkHttp 或 Retrofit |
| Room/SQLite | io.sentry:sentry-android-sqlite | 应用使用 Room 或原始 SQLite |
| Apollo 3 | io.sentry:sentry-apollo-3 | 应用使用 Apollo GraphQL v3 |
| Apollo 4 | io.sentry:sentry-apollo-4 | 应用使用 Apollo GraphQL v4 |
| Kotlin 扩展 | io.sentry:sentry-kotlin-extensions | Kotlin 协程上下文传播 |
| Ktor 客户端 | io.sentry:sentry-ktor-client | 应用使用 Ktor HTTP 客户端 |
| LaunchDarkly | io.sentry:sentry-launchdarkly-android | 应用使用 LaunchDarkly 功能标志 |
插件可以自动注入插桩(无需源代码更改):
| 功能 | 插桩对象 | 启用方式 |
|---|---|---|
DATABASE | Room DAO, SupportSQLiteOpenHelper | tracingInstrumentation.features |
FILE_IO | FileInputStream, FileOutputStream | tracingInstrumentation.features |
OKHTTP | OkHttpClient.Builder 自动 | tracingInstrumentation.features |
COMPOSE | NavHostController 自动插桩 | tracingInstrumentation.features |
LOGCAT | android.util.Log 捕获 | tracingInstrumentation.features |
SentryOptions(通过 SentryAndroid.init)| 选项 | 类型 | 默认值 | 用途 |
|---|---|---|---|
dsn | String | — | 必需。 项目 DSN;如果为空,SDK 将静默禁用 |
environment | String | — | 例如,"production"、"staging"。环境变量:SENTRY_ENVIRONMENT |
release | String | — | 应用版本,例如,"my-app@1.0.0+42"。环境变量:SENTRY_RELEASE |
dist | String | — | 构建变体 / 分发标识符 |
sendDefaultPii | Boolean | false | 包含 PII:IP 地址、用户数据 |
sampleRate | Double | 1.0 | 错误事件采样率(0.0–1.0) |
maxBreadcrumbs | Int | 100 | 每个事件的最大面包屑数 |
isAttachStacktrace | Boolean | true | 自动将堆栈跟踪附加到消息事件 |
isAttachScreenshot | Boolean | false | 发生错误时捕获屏幕截图 |
isAttachViewHierarchy | Boolean | false | 将 JSON 视图层次结构作为附件附加 |
isDebug | Boolean | false | 详细的 SDK 输出。切勿在生产环境中使用 |
isEnabled | Boolean | true | 完全禁用 SDK(例如,用于测试) |
beforeSend | SentryOptions.BeforeSendCallback | — | 在发送前修改或丢弃错误事件 |
beforeBreadcrumb | SentryOptions.BeforeBreadcrumbCallback | — | 在存储前过滤面包屑 |
| 选项 | 类型 | 默认值 | 用途 |
|---|---|---|---|
tracesSampleRate | Double | 0.0 | 事务采样率(0–1)。在开发中使用 1.0 |
tracesSampler | TracesSamplerCallback | — | 每个事务的采样;覆盖 tracesSampleRate |
tracePropagationTargets | List<String> | [".*"] | 接收 sentry-trace 和 baggage 头的主机/URL |
isEnableAutoActivityLifecycleTracing | Boolean | true | 自动插桩 Activity 生命周期 |
isEnableTimeToFullDisplayTracing | Boolean | false | TTFD 跨度(需要调用 Sentry.reportFullyDisplayed()) |
isEnableUserInteractionTracing | Boolean | false | 自动将用户手势插桩为事务 |
| 选项 | 类型 | 默认值 | 用途 |
|---|---|---|---|
profileSessionSampleRate | Double | 0.0 | 持续性能剖析采样率(SDK ≥ 8.7.0,API 22+) |
profilesSampleRate | Double | 0.0 | 旧版事务性能剖析率(与持续模式互斥) |
isProfilingStartOnAppStart | Boolean | false | 在应用启动时自动开始性能剖析会话 |
| 选项 | 类型 | 默认值 | 用途 |
|---|---|---|---|
isAnrEnabled | Boolean | true | 启用 ANR 看门狗线程 |
anrTimeoutIntervalMillis | Long | 5000 | 报告 ANR 前的毫秒数 |
isAnrReportInDebug | Boolean | false | 在调试构建中报告 ANR(在调试器中可能很嘈杂) |
| 选项 | 类型 | 默认值 | 用途 |
|---|---|---|---|
isEnableNdk | Boolean | true | 通过 sentry-native 启用原生崩溃捕获 |
isEnableScopeSync | Boolean | true | 将 Java 作用域(用户、标签)同步到 NDK 层 |
isEnableTombstoneFetchJob | Boolean | true | 获取 NDK tombstone 文件以进行增强 |
options.sessionReplay)| 选项 | 类型 | 默认值 | 用途 |
|---|---|---|---|
sessionSampleRate | Double | 0.0 | 要记录的会话比例 |
onErrorSampleRate | Double | 0.0 | 发生错误的会话中要记录的比例 |
maskAllText | Boolean | true | 在回放中遮罩所有文本 |
maskAllImages | Boolean | true | 在回放中遮罩所有图像 |
quality | SentryReplayQuality | MEDIUM | 视频质量:LOW、MEDIUM、HIGH |
options.logs)| 选项 | 类型 | 默认值 | 用途 |
|---|---|---|---|
isEnabled | Boolean | false | 启用 Sentry.logger() API(SDK ≥ 8.12.0) |
setBeforeSend | BeforeSendLogCallback | — | 在发送前过滤/修改日志条目 |
| 变量 | 用途 | 备注 |
|---|---|---|
SENTRY_DSN | 数据源名称 | 在 CI 中设置;SDK 在初始化时从环境读取 |
SENTRY_AUTH_TOKEN | 上传 ProGuard 映射和源代码上下文 | 切勿提交 —— 使用 CI/CD 密钥 |
SENTRY_ORG | 组织标识 | 由 Gradle 插件 sentry.org 使用 |
SENTRY_PROJECT | 项目标识 | 由 Gradle 插件 sentry.projectName 使用 |
SENTRY_RELEASE | 发布标识符 | 回退自 options.release |
SENTRY_ENVIRONMENT | 环境名称 | 回退自 options.environment |
您也可以通过 AndroidManifest.xml 元数据配置 DSN 和许多选项:
<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 元数据是一个方便的替代方案,但不支持完整的选项集。对于复杂配置(会话回放、性能剖析、钩子),请使用
SentryAndroid.init()。
设置完成后,验证 Sentry 是否正在接收事件:
测试错误捕获:
// 在 Activity 或 Fragment 中
try {
throw RuntimeException("Sentry Android SDK test")
} catch (e: Exception) {
Sentry.captureException(e)
}
测试追踪:
val transaction = Sentry.startTransaction("test-task", "task")
val span = transaction.startChild("test-span", "description")
span.finish()
transaction.finish()
测试结构化日志记录(SDK ≥ 8.12.0):
Sentry.logger().info("Sentry logging test")
Sentry.logger().error("Error log test", Exception("test error"))
检查 Sentry 仪表板:
test-task 事务如果没有任何内容出现:
options.isDebug = true —— SDK 将日志输出到 LogcatApplication 类是否在 AndroidManifest.xml 中注册为 android:nameisEnableNdk = true(默认)并且构建时支持 NDK完成 Android 设置后,检查是否有缺少 Sentry 覆盖的后端或 Web 前端:
# 相邻的后端目录
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 对应应用
ls ../ios ../YourApp-iOS 2>/dev/null
find .. -maxdepth 3 -name "*.xcodeproj" 2>/dev/null | head -3
如果存在没有 Sentry 的后端或相关平台,建议匹配的技能:
| 检测到 | 建议技能 |
|---|---|
Go 后端 (go.mod) | sentry-go-sdk |
Python 后端 (requirements.txt, pyproject.toml) | sentry-python-sdk |
Ruby 后端 (Gemfile) | sentry-ruby-sdk |
| Node.js 后端 | @sentry/node —— 参见 docs.sentry.io/platforms/javascript/guides/express/ |
iOS 应用 (.xcodeproj) | sentry-cocoa-sdk |
React Native (package.json 包含 react-native) | sentry-react-native-sdk |
| React / Next.js Web | sentry-react-sdk 或 sentry-nextjs-sdk |
分布式追踪设置 —— 如果添加了后端技能,请在 Android 中配置 tracePropagationTargets 以将追踪上下文传播到您的 API:
options.tracePropagationTargets = listOf(
"api.yourapp.com",
".*\\.yourapp\\.com"
)
这将在 Sentry 瀑布视图中将移动端事务与后端追踪链接起来。
| 问题 | 解决方案 |
|---|---|
| 事件未出现在 Sentry 中 | 设置 isDebug = true,检查 Logcat 中的 SDK 错误;验证 DSN 是否正确并与您的项目匹配 |
SentryAndroid.init() 未被调用 | 确认 AndroidManifest.xml 中设置了 android:name=".MyApplication";Application 类不是抽象的 |
| Gradle 插件未找到 | 首先将插件添加到项目级 build.gradle.kts,然后 apply false;验证版本 6.1.0 |
| ProGuard 映射未上传 | 设置 SENTRY_AUTH_TOKEN 环境变量;确保 sentry {} 块中 autoUploadProguardMapping = true |
| NDK 崩溃未捕获 | 验证 isEnableNdk = true(默认);确保项目在 android.ndkVersion 中配置了 NDK |
| 调试器中报告 ANR | 设置 isAnrReportInDebug = false(默认);当调试器暂停线程时,ANR 看门狗会触发 |
| 会话回放未记录 | 需要 API 26+;验证 sessionSampleRate > 0 或 onErrorSampleRate > 0;检查 Logcat 中的回放错误 |
| 会话回放显示空白屏幕 | PixelCopy(默认)需要硬件加速;尝试 SentryReplayOptions.screenshotQuality = CANVAS |
| 回放遮罩错位 | 具有 translationX/Y 或 clipToPadding=false 的视图可能导致遮罩偏移;报告给 github.com/getsentry/sentry-java |
beforeSend 未触发 | beforeSend 仅拦截托管(Java/Kotlin)事件;NDK 原生崩溃会绕过它 |
| OkHttp 跨度未出现 | 将 SentryOkHttpInterceptor 添加到您的 OkHttpClient,或使用 Gradle 插件 OKHTTP 字节码插桩 |
| 跨度未附加到事务 | 确保启动事务时使用 TransactionOptions().setBindToScope(true);子跨度会查找作用域根 |
| 追踪未记录 | 验证 tracesSampleRate > 0;Activity 插桩需要 isEnableAutoActivityLifecycleTracing = true(默认) |
| 持续性能剖析不工作 | 需要 SDK ≥ 8.7.0;需要 API 22+;设置 profileSessionSampleRate > 0;不要同时设置 profilesSampleRate |
| 同时设置了两种性能剖析模式 | profilesSampleRate 和 profileSessionSampleRate 互斥 —— 仅使用一种 |
| TTFD 跨度缺失 | 设置 isEnableTimeToFullDisplayTracing = true 并在屏幕准备就绪时调用 Sentry.reportFullyDisplayed() |
| Kotlin 协程作用域丢失 | 添加 sentry-kotlin-extensions 依赖项;使用 Sentry.cloneMainContext() 来传播追踪上下文 |
| 发布版本堆栈跟踪不可读 | ProGuard 映射未上传;确认 Gradle 插件 autoUploadProguardMapping = true 且设置了身份验证令牌 |
| Sentry 中未显示源代码上下文 | 在 sentry {} 块中启用 includeSourceContext = true(需要 Gradle 插件) |
| BOM 版本冲突 | 使用 implementation(platform("io.sentry:sentry-bom:8.33.0")) 并从所有其他 io.sentry:* 条目中省略版本 |
SENTRY_AUTH_TOKEN 暴露 | 身份验证令牌仅用于构建时 —— 切勿将其传递给 SentryAndroid.init() 或嵌入到 APK 中 |
每周安装次数
158
仓库
[getsentry/sentry-for-ai](https://github.com/getsentry/sentry-for
All Skills > SDK Setup > 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.
sentry-android, io.sentry:sentry-android, mobile crash tracking, or Sentry for Kotlin/Java AndroidNote: SDK versions and APIs below reflect current Sentry docs at time of writing (
io.sentry:sentry-android:8.33.0, Gradle plugin6.1.0). Always verify against docs.sentry.io/platforms/android/ before implementing.
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 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 |
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 integration |
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):
Optional (enhanced observability):
Sentry.logger(), with optional Timber bridgeRecommendation 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?"
| 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 |
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 androidIt handles login, org/project selection, Gradle plugin setup, dependency installation, DSN configuration, and ProGuard/R8 mapping upload.
Once it finishes, come back and skip toVerification.
If the user skips the wizard, proceed with Option 2 (Manual Setup) below.
The Sentry Gradle plugin is the easiest setup path. It:
android.util.Log via bytecode transforms (zero source changes)Step 1 — Add the plugin tobuild.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 inapp/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 inAndroidManifest.xml
<application
android:name=".MyApplication"
... >
Use this if you can't use the Gradle plugin (e.g., non-standard build setups).
Step 1 — Add dependency inapp/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()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
}
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 |
For each feature: Read ${SKILL_ROOT}/references/<feature>.md, follow steps exactly, verify it works.
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 |
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 |
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 |
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 |
| 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 |
| 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 |
| Option | Type | Default | Purpose |
|---|---|---|---|
isAnrEnabled | Boolean | true | Enable ANR watchdog thread |
anrTimeoutIntervalMillis | Long | 5000 | Milliseconds before reporting ANR |
isAnrReportInDebug |
| 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 |
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 |
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 |
| 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 |
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().
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:
test-task transaction with child spanIf nothing appears:
options.isDebug = true — SDK logs to LogcatApplication class is registered in AndroidManifest.xml as android:nameisEnableNdk = true (default) and build with NDK supportAfter 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 |
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.
| 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 |
Weekly Installs
158
Repository
GitHub Stars
82
First Seen
Mar 4, 2026
Security Audits
Gen Agent Trust HubPassSocketPassSnykPass
Installed on
gemini-cli157
codex157
cursor157
kimi-cli156
amp156
cline156
Electron应用自动化指南:使用agent-browser通过CDP实现桌面应用自动化
13,200 周安装
sentry-android-timber| 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 |
${SKILL_ROOT}/references/logging.md| Structured logging / log-to-trace correlation |
| Metrics | ${SKILL_ROOT}/references/metrics.md | Custom metric tracking (Beta, SDK ≥ 8.30.0) |
| Crons | ${SKILL_ROOT}/references/crons.md | Scheduled jobs, WorkManager check-ins |
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 |
| 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 |
COMPOSE| NavHostController auto-instrumentation |
tracingInstrumentation.features |
LOGCAT | android.util.Log capturing | tracingInstrumentation.features |
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 |
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 |
Boolean |
false |
| Auto-start profiling session on app launch |
Boolean |
false |
| Report ANRs in debug builds (noisy in debugger) |
Boolean |
true |
| Fetch NDK tombstone files for enrichment |
Boolean |
true |
| Mask all text in replays |
maskAllImages | Boolean | true | Mask all images in replays |
quality | SentryReplayQuality | MEDIUM | Video quality: LOW, MEDIUM, HIGH |
SENTRY_RELEASE | Release identifier | Falls back from options.release |
SENTRY_ENVIRONMENT | Environment name | Falls back from options.environment |
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 |
| 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 |
SENTRY_AUTH_TOKEN exposed | Auth token is build-time only — never pass it to SentryAndroid.init() or embed in the APK |