sentry-android-sdk

所有技能 > SDK 设置 > Android SDK

Sentry Android SDK

一款开箱即用的向导，可扫描你的 Android 项目并引导你完成完整的 Sentry 设置——错误监控、追踪、性能分析、会话回放、日志记录等。

在以下情况下调用此技能

• 用户要求“将 Sentry 添加到 Android”或“设置 Sentry”
• 用户希望在 Android 中进行错误监控、崩溃报告、ANR 检测、追踪、性能分析、会话回放或日志记录
• 用户提到 sentry-android、io.sentry:sentry-android、移动端崩溃跟踪或用于 Kotlin/Java Android 的 Sentry
• 用户希望监控原生（NDK）崩溃、应用无响应（ANR）事件或应用启动性能

注意： 以下 SDK 版本和 API 反映了撰写本文时最新的 Sentry 文档（io.sentry:sentry-android:8.33.0，Gradle 插件 6.1.0）。 实施前，请务必参阅 docs.sentry.io/platforms/android/ 进行确认。

---

阶段 1：检测

在提出任何建议前，运行以下命令了解项目：

# 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

需要确定的内容：

问题	影响
是否存在 build.gradle.kts？	所有示例均使用 Kotlin DSL 语法
是否存在 gradle/libs.versions.toml？	将 Sentry 添加到版本目录；在构建文件中通过 libs.* 引用
目录中是否已有 sentry 条目？	复用现有版本引用；不要重复添加或硬编码版本
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() 应放在此处

---

阶段 2：提出建议

根据发现的情况给出具体建议。不要提出开放式问题——直接给出方案：

推荐（核心覆盖范围——始终设置以下功能）：

• ✅ 错误监控 — 自动捕获未处理异常、ANR 和原生 NDK 崩溃
• ✅ 追踪 — 自动检测 Activity 生命周期、应用启动、HTTP 请求和数据库查询
• ✅ 会话回放 — 录制屏幕画面和用户交互，便于调试（API 26+）

可选（增强可观测性）：

• ⚡ 性能分析 — 持续 UI 性能分析（推荐）或基于事务的采样
• ⚡ 日志记录 — 通过 Sentry.logger() 记录结构化日志，并可选接入 Timber
• ⚡ 用户反馈 — 收集用户在应用内提交的错误报告

建议逻辑：

功能	建议条件……
错误监控	始终 — 这是任何 Android 应用不可或缺的基础功能
追踪	Android 应用始终需要 — 应用启动时间、Activity 生命周期和网络延迟都很重要
会话回放	面向用户的生产应用且 API 26+；用于直观地调试用户遇到的问题
性能分析	对性能敏感的应用、启动时间调查和生产环境性能分析
日志记录	应用使用结构化日志，或希望在 Sentry 中关联日志与追踪
用户反馈	希望收集用户提交的错误报告的 Beta 版或面向客户的应用

建议：“对于你的 [Kotlin / Java] Android 应用（minSdk X），我建议设置错误监控 + 追踪 + 会话回放。要不要我也添加性能分析和日志记录？”

---

阶段 3：引导

确定你的设置路径

项目类型	推荐设置方式	复杂度
新项目，没有现有的 Sentry	Gradle 插件（推荐）	低 — 插件会处理大部分配置
现有项目，没有 Sentry	Gradle 插件或手动初始化	中 — 添加依赖项和 Application 类
需要完全手动控制	在 Application 中使用 SentryAndroid.init()	中 — 显式配置，灵活性最高

选项 1：向导（推荐）

你需要亲自运行此命令 — 向导会打开浏览器进行登录， 并要求提供 Agent 无法处理的交互式输入。 将以下命令复制粘贴到终端：

npx @sentry/wizard@latest -i android

它会处理登录、组织/项目选择、Gradle 插件设置、依赖项安装、 DSN 配置以及 ProGuard/R8 映射文件上传。

完成后，请返回并跳到验证。

如果用户跳过向导，请继续下面的选项 2（手动设置）。

---

选项 2：手动设置

使用 Gradle 版本目录（gradle/libs.versions.toml）

如果第 1 阶段检测到 gradle/libs.versions.toml，请先将 Sentry 添加到版本目录，然后在构建文件中引用它。这样可以集中管理版本，并符合现代 AGP 项目的惯例。

步骤 1 — 在 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" }

**注意：**可选集成条目省略 version.ref — 其版本会在解析时从 BOM 获取。只有 sentry-bom 需要版本引用。 如果版本目录已定义 sentry 版本，请复用该版本，不要添加重复条目。

步骤 2 — 在 build.gradle[.kts] 中引用版本目录

项目级 build.gradle.kts：

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

应用级 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）：

plugins {
    id "com.android.application"
    alias libs.plugins.sentry.android.gradle
}

dependencies {
    implementation platform(libs.sentry.bom)
    implementation libs.sentry.android
}

然后继续使用下面路径 A、第 2 步中的 sentry {} 配置块。其余设置（Application 类初始化、清单注册、验证）完全相同。

---

路径 A：Gradle 插件（推荐）

Sentry Gradle 插件是最简单的设置方式。它可以：

• 在发布版本构建时自动上传 ProGuard/R8 映射文件
• 将源代码上下文注入堆栈帧
• 可选地通过字节码转换插桩 OkHttp、Room/SQLite、文件 I/O、Compose 导航和 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 {
    // 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
}

步骤 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"

            // 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 代码：

// 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"
    ... >

---

路径 B：手动设置（不使用 Gradle 插件）

如果无法使用 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 "[email protected]+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
}

---

对每项已确定的功能

逐项处理功能。每项功能都加载对应的参考文件，按照其中的步骤操作，然后验证完成后再继续：

功能	参考文件	在以下情况下加载……
错误监控	${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	自定义指标跟踪（SDK ≥ 8.30.0）
定时任务	${SKILL_ROOT}/references/crons.md	定时作业、WorkManager 签到
集成参考	${SKILL_ROOT}/references/integrations.md	内置、可选及 Gradle 字节码集成

对于每项功能：Read ${SKILL_ROOT}/references/<feature>.md，严格按照步骤操作，并验证其是否正常运行。

---

配置参考

核心 SentryOptions（通过 SentryAndroid.init）

选项	类型	默认值	用途
dsn	String	—	必填。 项目 DSN；如果为空，SDK 将静默停用
environment	String	—	例如，"production"、"staging"。环境变量：SENTRY_ENVIRONMENT
release	String	—	应用版本，例如，"[email protected]+42"。环境变量：SENTRY_RELEASE
dist	String	—	构建变体／分发标识符
sendDefaultPii	Boolean	false	包含个人身份信息：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 Span（需要调用 Sentry.reportFullyDisplayed()）
isEnableUserInteractionTracing	Boolean	false	自动将用户手势作为事务添加检测

性能分析选项

选项	类型	默认值	用途
profileSessionSampleRate	Double	0.0	连续性能分析采样率（SDK ≥ 8.7.0，API 22+）
profilesSampleRate	Double	0.0	旧版事务性能分析采样率（与连续性能分析互斥）
isProfilingStartOnAppStart	Boolean	false	应用启动时自动开启性能分析会话

ANR 选项

选项	类型	默认值	用途
isAnrEnabled	Boolean	true	启用 ANR 看门狗线程
anrTimeoutIntervalMillis	Long	5000	报告 ANR 前等待的毫秒数
isAnrReportInDebug	Boolean	false	在调试版本中报告 ANR（调试器中会产生大量日志）

NDK 选项

选项	类型	默认值	用途
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 是否正在接收事件：

测试错误捕获：

// In an Activity or 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 控制面板：

• Issues → 几秒内应显示你的测试异常
• Traces → 查找带有子 span 的 test-task 事务
• Replays → 与应用交互后可查看会话录制（需要 API 26+）
• Logs → 在 Logs 标签页中查看结构化日志条目

如果没有显示任何内容：

1. 设置 options.isDebug = true — SDK 会向 Logcat 输出日志
2. 确认 DSN 正确且与 Sentry 项目匹配
3. 检查 Application 类是否已在 AndroidManifest.xml 中注册为 android:name
4. 确认设备/模拟器可以连接互联网
5. 对于 NDK 崩溃，确保 isEnableNdk = true（默认值），并使用 NDK 支持进行构建

---

第 4 阶段：交叉链接

完成 Android 设置后，检查是否有尚未接入 Sentry 的后端或 Web 前端：

# 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

如果存在未接入 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（包含 react-native 的 package.json）	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 的 View 可能导致遮罩偏移；请在 github.com/getsentry/sentry-java 报告此问题
未触发 beforeSend	beforeSend 仅拦截托管（Java/Kotlin）事件；NDK 原生崩溃会绕过它
未显示 OkHttp spans	将 SentryOkHttpInterceptor 添加到 OkHttpClient，或使用 Gradle 插件的 OKHTTP 字节码插桩
spans 未附加到事务	启动事务时确保使用 TransactionOptions().setBindToScope(true)；子 spans 会查找作用域根节点
未记录追踪数据	确认 tracesSampleRate > 0；Activity 插桩需要设置 isEnableAutoActivityLifecycleTracing = true（默认值）
持续性能分析无法运行	需要 SDK ≥ 8.7.0；需要 API 22+；设置 profileSessionSampleRate > 0；不要同时设置 profilesSampleRate
同时设置了两种性能分析模式	profilesSampleRate 和 profileSessionSampleRate 互斥——只能使用其中一个
缺少 TTFD spans	设置 isEnableTimeToFullDisplayTracing = true，并在屏幕就绪时调用 Sentry.reportFullyDisplayed()
Kotlin 协程作用域丢失	添加 sentry-kotlin-extensions 依赖；使用 Sentry.cloneMainContext() 传播追踪上下文
Release 构建的堆栈跟踪难以阅读	未上传 ProGuard 映射文件；确认 Gradle 插件的 autoUploadProguardMapping = true，并已设置身份验证令牌
Sentry 中未显示源代码上下文	在 sentry {} 代码块中启用 includeSourceContext = true（需要 Gradle 插件）
BOM 版本冲突	使用 implementation(platform("io.sentry:sentry-bom:8.33.0"))，并从所有其他 io.sentry:* 条目中省略版本号
无法解析版本目录别名	编辑 gradle/libs.versions.toml 后同步 Gradle；别名在 TOML 中使用 -，在构建文件中使用 .（例如，sentry-android → libs.sentry.android）
版本目录中存在重复的 Sentry 版本	复用现有的 [versions] sentry = "..." 条目；不要添加第二个键；使用版本目录时，也不要在 build.gradle 中硬编码版本号
SENTRY_AUTH_TOKEN 暴露	身份验证令牌仅用于构建时——绝不要将其传递给 SentryAndroid.init()，也不要嵌入 APK 中