All Skills > SDK Setup > Android SDK

Sentry Android SDK

Androidプロジェクトをスキャンし、完全なSentry設定を通じてガイドするオピニオンのあるウィザード — エラー監視、トレーシング、プロファイリング、セッションリプレイ、ロギング、その他の機能。

このスキルを呼び出すとき

• ユーザーが「Add Sentry to Android」または「set up Sentry」をAndroidアプリで実行するよう求める
• ユーザーが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: 検出

推奨を行う前に、プロジェクトを理解するために以下のコマンドを実行してください:

# プロジェクト構造とビルドシステムを検出
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

# Gradleバージョンカタログを検出(libs.versions.toml) — 最新のAGPプロジェクト
ls gradle/libs.versions.toml 2>/dev/null

# バージョンカタログの既存Sentryエントリを確認
grep -iE 'sentry|io\.sentry' gradle/libs.versions.toml 2>/dev/null | head -10

# ビルドファイルがカタログを参照しているか確認(alias/libs.*の使用)
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

# 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構文を使用してください
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でログ-トレース相関が必要な場合
ユーザーフィードバック	ユーザー送信バグレポートが必要なベータまたはカスタマー向けアプリ

提案: 「[Kotlin/Java] Androidアプリ(minSdk X)の場合、エラー監視+トレーシング+セッションリプレイの設定をお勧めします。プロファイリングとロギングも追加したいですか?」

---

フェーズ3: ガイド

セットアップパスを決定してください

プロジェクトタイプ	推奨セットアップ	複雑さ
新規プロジェクト、既存のSentryなし	Gradleプラグイン(推奨)	低 — プラグインがほとんどの設定を処理
既存プロジェクト、Sentryなし	Gradleプラグインまたは手動初期化	中 — 依存関係追加+Applicationクラス
手動完全制御	Application内のSentryAndroid.init()	中 — 明示的な設定、最も柔軟

オプション1: ウィザード(推奨)

このウィザードは自分自身で実行する必要があります — ウィザードはログイン用のブラウザを開き、 エージェントが処理できない対話的入力が必要です。 ターミナルにコピー-ペーストしてください:

npx @sentry/wizard@latest -i android

ログイン、org/プロジェクト選択、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" }
# オプション統合 — プロジェクトが使用するもののみ追加:
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 {
    // sentryモジュール全体で一貫したバージョンのためにBOMを使用
    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 — ApplicationをAndroidManifest.xmlに登録

<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 "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検出(5sデフォルト、ウォッチドッグ+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
}

---

合意した各機能について

ウォークスルー機能を1つずつ。各機能の参照ファイルをロード、ステップを正確に従う、移動前に検証してください:

機能	リファレンス	ロードするとき...
エラー監視	${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)
Crons	${SKILL_ROOT}/references/crons.md	スケジュール済みジョブ、WorkManager check-ins

各機能について: ${SKILL_ROOT}/references/<feature>.mdを読む、ステップを正確に従う、それが機能することを確認してください。

---

統合リファレンス

ビルトイン(自動有効)

SentryAndroid.init()が呼び出されたときに、これらの統合は自動的にアクティベートします:

統合	行うこと
UncaughtExceptionHandlerIntegration	すべてのキャッチされないJava/Kotlin例外をキャプチャ
AnrIntegration	ウォッチドッグスレッド(5s)+ApplicationExitInfo(API 30+)を通じたANR検出
NdkIntegration	sentry-nativeを通じたネイティブ(C/C++)クラッシュキャプチャ
ActivityLifecycleIntegration	TTID/TTFDのためのActivity create/resume/pauseを自動計装
AppStartMetrics	コールド/ウォーム/ホットアプリ起動時間を測定
NetworkBreadcrumbsIntegration	接続性変更をパンくずとして記録
SystemEventsBreadcrumbsIntegration	バッテリー、画面オン/オフ等を記録
AppLifecycleIntegration	フォアグラウンド/バックグラウンド遷移を記録
UserInteractionIntegration	タップ、スワイプ、入力イベント用パンくず
CurrentActivityIntegration	アクティブActivityをコンテキスト用に追跡

オプション統合

成果物をdependencies {}ブロックに追加してください(バージョンはBOMで管理):

統合	成果物	追加するとき
Timber	io.sentry:sentry-android-timber	アプリがロギング用にTimberを使用
Fragment	io.sentry:sentry-android-fragment	アプリがJetpack Fragmentを使用(生ライフサイクル追跡)
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 Extensions	io.sentry:sentry-kotlin-extensions	Kotlinコルーチンコンテキスト伝播
Ktor Client	io.sentry:sentry-ktor-client	アプリがKtor HTTPクライアントを使用
LaunchDarkly	io.sentry:sentry-launchdarkly-android	アプリがLaunchDarklyフィーチャーフラグを使用

Gradleプラグインバイトコード計装

プラグインは計装を自動的に注入できます(ソース変更なし):

機能	計装	有効化
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(via SentryAndroid.init)

オプション	タイプ	デフォルト	目的
dsn	String	—	必須。 プロジェクトDSN; 空の場合SDKは静黙的に無効化
environment	String	—	例えば、"production"、"staging"。Env: SENTRY_ENVIRONMENT
release	String	—	アプリバージョン、例えば、"my-app@1.0.0+42"。Env: 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	アプリ起動時プロファイリングセッション自動開始

ANRオプション

オプション	タイプ	デフォルト	目的
isAnrEnabled	Boolean	true	ANRウォッチドッグスレッド有効化
anrTimeoutIntervalMillis	Long	5000	ANR報告前のミリ秒
isAnrReportInDebug	Boolean	false	デバッグビルドでANRを報告(デバッガーで騒々しい)

NDKオプション

オプション	タイプ	デフォルト	目的
isEnableNdk	Boolean	true	sentry-native経由のネイティブクラッシュキャプチャ有効化
isEnableScopeSync	Boolean	true	Java scope(ユーザー、タグ)をNDK層に同期
isEnableTombstoneFetchJob	Boolean	true	NDKカタコンボファイルをエンリッチメント用にフェッチ

セッションリプレイオプション(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	Data Source Name	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>

⚠️ マニフェストメタデータは便利な代替案ですが、フルオプションセットをサポートしていません。複雑な設定(セッションリプレイ、プロファイリング、フック)については、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ダッシュボードを確認:

• Issues → テスト例外が数秒以内に表示される
• Traces → 子スパン付きtest-taskトランザクションを探す
• Replays → アプリインタラクション後のセッション記録が表示される(API 26+が必要)
• Logs → ログタブの下に構造化ログエントリが表示される

何も表示されない場合:

1. options.isDebug = trueを設定 — SDKがLogcatにログ出力
2. DSNが正しく、Sentryプロジェクトに一致することを確認
3. AndroidManifest.xmlでandroid:nameとしてApplicationクラスが登録されていることを確認
4. デバイス/エミュレーターがインターネット接続を持つことを確認
5. NDKクラッシュ用に、isEnableNdk = true(デフォルト)を確認し、NDKサポートでビルドする

---

フェーズ4: クロスリンク

Androidセットアップ完了後、Sentryカバレッジが欠落しているバックエンドまたはウェブフロントエンドをチェックしてください:

# 隣接するバックエンドディレクトリ
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(react-native付きpackage.json)	sentry-react-native-sdk
React / Next.jsウェブ	sentry-react-sdkまたはsentry-nextjs-sdk

分散トレーシングセットアップ — バックエンドスキルが追加される場合、AndroidでトレースコンテキストをAPI に伝播させるためにtracePropagationTargetsを設定してください:

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スパンが表示されない	OkHttpClient にSentryOkHttpInterceptorを追加、またはGradleプラグインOKHTTPバイトコード計装を使用
スパンがトランザクションにアタッチされない	トランザクション開始時にTransactionOptions().setBindToScope(true)を確認、子スパンはスコープルートを探す
トレーシングが記録されない	tracesSampleRate > 0を確認、Activity計装はisEnableAutoActivityLifecycleTracing = true(デフォルト)が必要
継続的プロファイリングが機能しない	SDK ≥ 8.7.0が必要、API 22+が必要、profileSessionSampleRate > 0を設定、profilesSampleRateも設定しない
両方のプロファイリングモードが設定される	profilesSampleRateとprofileSessionSampleRateは相互排他的 — 1つのみ使用
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:*エントリからバージョンを省略
バージョンカタログエイリアスが未解決	gradle/libs.versions.toml編集後、Gradleを同期、エイリアス名はTOMLで-、ビルドファイルで.を使用(例えば、sentry-android → libs.sentry.android)
カタログにSentryバージョンが重複	既存[versions] sentry = "..."エントリを再利用、第2のキーを追加しない、カタログが使用中の場合build.gradleでバージョンをハードコードしない
SENTRY_AUTH_TOKENが公開された	認証トークンはビルド時のみ — SentryAndroid.init()に渡さないか、APKに組み込まない