sentry-cocoa-sdk

Sentry Cocoa SDK

Apple プロジェクトをスキャンし、Sentry のセットアップを最初から最後まで案内する、独自のウィザードです。

このスキルを呼び出すタイミング

• ユーザーが Apple アプリへの「iOS/macOS/tvOS への Sentry の追加」や「Sentry のセットアップ」を依頼した場合
• ユーザーが Swift/ObjC でエラー監視、トレーシング、プロファイリング、セッションリプレイ、ロギングを行いたい場合
• ユーザーが sentry-cocoa、SentrySDK、または Apple/iOS 向け Sentry SDK に言及した場合
• ユーザーがクラッシュ、アプリのハング、ウォッチドッグによる終了、パフォーマンスを監視したい場合

注： 以下の SDK バージョンと API は、執筆時点の Sentry ドキュメント（sentry-cocoa 9.5.1）を反映しています。 実装前に、必ず docs.sentry.io/platforms/apple/ で確認してください。

---

フェーズ 1：検出

推奨事項を提示する前に、以下のコマンドを実行してプロジェクトを把握してください。

# Check existing Sentry dependency
grep -i sentry Package.swift Podfile Cartfile 2>/dev/null

# Detect UI framework (SwiftUI vs UIKit)
grep -rE "@main|struct.*App.*:.*App" --include="*.swift" . 2>/dev/null | head -5
grep -rE "AppDelegate|UIApplicationMain" --include="*.swift" . 2>/dev/null | head -5

# Detect platform and deployment targets
grep -E "platforms:|\.iOS|\.macOS|\.tvOS|\.watchOS|\.visionOS" Package.swift 2>/dev/null
grep -E "platform :ios|platform :osx|platform :tvos|platform :watchos" Podfile 2>/dev/null

# Detect logging
grep -rE "import OSLog|os\.log|CocoaLumberjack|DDLog" --include="*.swift" . 2>/dev/null | head -5

# Detect companion backend
ls ../backend ../server ../api 2>/dev/null
ls ../go.mod ../requirements.txt ../Gemfile ../package.json 2>/dev/null

確認事項：

• sentry-cocoa はすでに Package.swift または Podfile にありますか？ある場合は、フェーズ 2（機能の設定）に進んでください。
• SwiftUI（@main App 構造体）ですか、それとも UIKit（AppDelegate）ですか？初期化パターンが決まります。
• 対象の Apple プラットフォームは何ですか？（利用可能な機能に影響します。プラットフォームサポート一覧を参照してください。）
• 既存のロギングライブラリはありますか？（構造化ログのキャプチャが可能になります。）
• 関連するバックエンドはありますか？（分散トレーシングのフェーズ 4 で相互リンクします。）

---

フェーズ 2：提案

確認した内容に基づいて、具体的な推奨事項を提示してください。自由回答形式の質問は避け、提案を先に示してください。

推奨（基本的なカバレッジ）：

• ✅ エラー監視 — 常に有効にします。クラッシュレポート、アプリのハング、ウォッチドッグによる終了、NSError/Swift エラーに対応します。
• ✅ トレーシング — アプリでは常に有効にします。アプリ起動、ネットワーク、UIViewController、ファイル I/O、Core Data を自動計測します。
• ✅ プロファイリング — 本番アプリ向けです。オーバーヘッドを最小限に抑えた継続的なプロファイリングを行います。

オプション（可観測性の強化）：

• ⚡ セッションリプレイ — ユーザー向けアプリ向けです。⚠️ iOS 26 以降ではデフォルトで無効です（Liquid Glass のレンダリング）。
• ⚡ ロギング — 構造化ログのキャプチャが必要な場合に使用します。
• ⚡ ユーザーフィードバック — ユーザーからのクラッシュ／エラーに関するフィードバックフォームを利用したいアプリ向けです。

Cocoa では利用できません：

• ❌ メトリクス — 代わりにカスタムスパンを使用します。
• ❌ Cron — バックエンドのみです。
• ❌ AI 監視 — JS/Python のみです。

推奨の判断基準：

機能	推奨する条件
エラー監視	常に — 必須の基本機能です
トレーシング	アプリでは常に — 充実した自動計測をすぐに利用できます
プロファイリング	パフォーマンスが重要な本番アプリ
セッションリプレイ	iOS のみのユーザー向けアプリ（iOS 26 以降の注意点を確認してください。tvOS/macOS/watchOS/visionOS は対象外です）
ロギング	既存の os.log / CocoaLumberjack の使用、または構造化ログが必要な場合
ユーザーフィードバック	スクリーンショット付きのアプリ内バグレポートを希望するアプリ

次のように提案してください：「エラー監視 + トレーシング + プロファイリングをおすすめします。セッションリプレイとロギングも追加しますか？」

---

フェーズ 3：案内

インストール

オプション 1 — Sentry Wizard（推奨）： ログイン、組織／プロジェクトの選択、認証トークンの設定を対話形式で案内します。その後、SDK をインストールし、AppDelegate を更新し、dSYM／デバッグシンボルのアップロード用ビルドフェーズを追加して、すべてを自動的に設定します。

brew install getsentry/tools/sentry-wizard && sentry-wizard -i ios

オプション 2 — Swift Package Manager： 「File」→「Add Packages」→ 次を入力します：

https://github.com/getsentry/sentry-cocoa.git

または、Package.swift に次を追加します：

.package(url: "https://github.com/getsentry/sentry-cocoa", from: "9.5.1"),

SPM のプロダクト — 各ターゲットにつき必ず 1 つだけ選択してください：

プロダクト	用途
Sentry	推奨 — 静的フレームワークで、アプリの起動が高速です
Sentry-Dynamic	動的フレームワークの代替
SentrySwiftUI	SwiftUI のビューのパフォーマンス追跡（SentryTracedView）
Sentry-WithoutUIKitOrAppKit	watchOS、アプリ拡張機能、CLI ツール

⚠️ Xcode では複数のプロダクトを選択できますが、1 つだけ選んでください。

オプション 3 — CocoaPods：

platform :ios, '11.0'
use_frameworks!

target 'YourApp' do
  pod 'Sentry', :git => 'https://github.com/getsentry/sentry-cocoa.git', :tag => '9.5.1'
end

既知の問題（Xcode 14 以降）： Sandbox の rsync.samba エラーが発生した場合 →「Target Settings」→「Enable User Script Sandbox」→ NO。

---

クイックスタート — 推奨される初期化

適切なデフォルト値を設定した、ほとんどの機能を有効にする構成です。アプリの起動時に、ほかのコードより前に追加します。

SwiftUI — アプリのエントリーポイント：

import SwiftUI
import Sentry

@main
struct MyApp: App {
    init() {
        SentrySDK.start { options in
            options.dsn = ProcessInfo.processInfo.environment["SENTRY_DSN"]
                ?? "https://[email protected]/0"
            options.environment = ProcessInfo.processInfo.environment["SENTRY_ENVIRONMENT"]
            options.releaseName = Bundle.main.infoDictionary?["CFBundleShortVersionString"] as? String

            // Error monitoring (on by default — explicit for clarity)
            options.enableCrashHandler = true
            options.enableAppHangTrackingV2 = true
            options.enableWatchdogTerminationTracking = true
            options.attachScreenshot = true
            options.attachViewHierarchy = true
            options.sendDefaultPii = true

            // Tracing
            options.tracesSampleRate = 1.0          // lower to 0.2 in high-traffic production

            // Profiling (SDK 9.0.0+ API)
            options.configureProfiling = {
                $0.sessionSampleRate = 1.0
                $0.lifecycle = .trace
            }

            // Session Replay (disabled on iOS 26+ by default — safe to configure)
            options.sessionReplay.sessionSampleRate = 1.0
            options.sessionReplay.onErrorSampleRate = 1.0

            // Logging (SDK 9.0.0+ top-level; use options.experimental.enableLogs in 8.x)
            options.enableLogs = true
        }
    }

    var body: some Scene {
        WindowGroup { ContentView() }
    }
}

UIKit — AppDelegate：

import UIKit
import Sentry

@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate {
    func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
    ) -> Bool {
        SentrySDK.start { options in
            options.dsn = ProcessInfo.processInfo.environment["SENTRY_DSN"]
                ?? "https://[email protected]/0"
            options.environment = ProcessInfo.processInfo.environment["SENTRY_ENVIRONMENT"]
            options.releaseName = Bundle.main.infoDictionary?["CFBundleShortVersionString"] as? String

            options.enableCrashHandler = true
            options.enableAppHangTrackingV2 = true
            options.enableWatchdogTerminationTracking = true
            options.attachScreenshot = true
            options.attachViewHierarchy = true
            options.sendDefaultPii = true

            options.tracesSampleRate = 1.0

            options.configureProfiling = {
                $0.sessionSampleRate = 1.0
                $0.lifecycle = .trace
            }

            options.sessionReplay.sessionSampleRate = 1.0
            options.sessionReplay.onErrorSampleRate = 1.0

            // Logging (SDK 9.0.0+ top-level; use options.experimental.enableLogs in 8.x)
            options.enableLogs = true
        }
        return true
    }
}

⚠️ SDK の初期化はメインスレッドで行う必要があります。

---

合意した各機能について

機能を一つずつ確認します。それぞれのリファレンスファイルを読み込み、手順に従ってから、次の機能に進む前に動作を確認します。

機能	リファレンスファイル	読み込むタイミング
エラーモニタリング	${SKILL_ROOT}/references/error-monitoring.md	常時（基本）
トレーシング	${SKILL_ROOT}/references/tracing.md	アプリの起動、ネットワーク、UIViewController のパフォーマンス
プロファイリング	${SKILL_ROOT}/references/profiling.md	本番環境でパフォーマンスが重要なアプリ
セッションリプレイ	${SKILL_ROOT}/references/session-replay.md	ユーザー向けの iOS/tvOS アプリ
ロギング	${SKILL_ROOT}/references/logging.md	構造化ログの収集が必要な場合
ユーザーフィードバック	${SKILL_ROOT}/references/user-feedback.md	アプリ内でのバグ報告が必要な場合

各機能について、Read ${SKILL_ROOT}/references/<feature>.md を実行し、手順に正確に従って、動作を確認します。

---

構成リファレンス

主な SentryOptions フィールド

オプション	型	デフォルト	目的
dsn	String	""	空の場合は SDK が無効になります。SENTRY_DSN 環境変数を読み込みます
environment	String	""	例："production"。SENTRY_ENVIRONMENT を読み込みます
releaseName	String	""	例："[email protected]"。SENTRY_RELEASE を読み込みます
debug	Bool	false	SDK の詳細な出力 — 本番環境では無効にしてください
sendDefaultPii	Bool	false	有効なインテグレーションから IP アドレスやユーザー情報を含めます
enableCrashHandler	Bool	true	クラッシュレポートのマスタースイッチ
enableAppHangTrackingV2	Bool	true (9.0+)	完全にブロックされたハングと、完全ではないハングを区別します
appHangTimeoutInterval	Double	2.0	ハングと判定するまでの秒数
enableWatchdogTerminationTracking	Bool	true	ウォッチドッグによる終了を追跡します（iOS、tvOS、Mac Catalyst）
attachScreenshot	Bool	false	エラー発生時にスクリーンショットを取得します
attachViewHierarchy	Bool	false	エラー発生時にビュー階層を取得します
tracesSampleRate	NSNumber?	nil	トランザクションのサンプルレート（nil = トレーシング無効）。Swift は Double リテラル（例：1.0 → NSNumber）を自動的にボックス化します
tracesSampler	Closure	nil	トランザクションごとの動的サンプリング（レートを上書きします）
enableAutoPerformanceTracing	Bool	true	自動計測のマスタースイッチ
tracePropagationTargets	[String]	[".*"]	分散トレースヘッダーを送信するホスト／正規表現
enableCaptureFailedRequests	Bool	true	HTTP 5xx エラーをイベントとして自動取得します
enableNetworkBreadcrumbs	Bool	true	送信 HTTP リクエストのパンくずリスト
inAppInclude	[String]	[]	「アプリ内」コードとして扱うモジュールのプレフィックス
maxBreadcrumbs	Int	100	イベントあたりのパンくずリストの最大数
sampleRate	Float	1.0	エラーイベントのサンプルレート
beforeSend	Closure	nil	エラーイベントを変更または破棄するフック
onCrashedLastRun	Closure	nil	クラッシュ後の次回起動時に呼び出されます

環境変数

変数	対応先	目的
SENTRY_DSN	dsn	データソース名
SENTRY_RELEASE	releaseName	アプリのバージョン（例：[email protected]）
SENTRY_ENVIRONMENT	environment	デプロイ環境

プラットフォーム機能のサポートマトリックス

機能	iOS	tvOS	macOS	watchOS	visionOS
クラッシュレポート	✅	✅	✅	✅	✅
アプリのハング V2	✅	✅	❌	❌	❌
ウォッチドッグによる終了	✅	✅	❌	❌	❌
アプリ起動のトレース	✅	✅	❌	❌	✅
UIViewController のトレース	✅	✅	❌	❌	✅
SwiftUI のトレース	✅	✅	✅	❌	✅
ネットワークトラッキング	✅	✅	✅	❌	✅
プロファイリング	✅	✅	✅	❌	✅
セッションリプレイ	✅	❌	❌	❌	❌
MetricKit	✅ (15+)	❌	✅ (12+)	❌	❌

---

検証

Sentry がイベントを受信していることをテストします。

// Trigger a test error event:
SentrySDK.capture(message: "Sentry Cocoa SDK test")

// Or test crash reporting (without debugger — crashes are intercepted by debugger):
// SentrySDK.crash()  // uncomment, run without debugger, relaunch to see crash report

数秒以内に Sentry ダッシュボードを確認します。何も表示されない場合は、次の手順を実施してください。

1. options.debug = true を設定します。SDK の内部情報が Xcode コンソールに出力されます
2. DSN が正しく、プロジェクトが存在することを確認します
3. 初期化がメインスレッドで行われていることを確認します

---

本番環境の設定

本番環境では、イベント量とコストを抑えるためにサンプルレートを下げます。

options.tracesSampleRate = 0.2          // 20% of transactions

options.configureProfiling = {
    $0.sessionSampleRate = 0.1          // 10% of sessions
    $0.lifecycle = .trace
}

options.sessionReplay.sessionSampleRate = 0.1   // 10% continuous
options.sessionReplay.onErrorSampleRate = 1.0   // 100% on error (keep high)

options.debug = false                   // never in production

---

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

Apple の設定が完了したら、Sentry のカバレッジが不足している関連バックエンドがないか確認します。

# Detect companion backend
ls ../backend ../server ../api 2>/dev/null
cat ../go.mod 2>/dev/null | head -5
cat ../requirements.txt ../Pipfile 2>/dev/null | head -5
cat ../Gemfile 2>/dev/null | head -5
cat ../package.json 2>/dev/null | grep -E '"name"|"dependencies"' | head -5

バックエンドが見つかった場合は、分散トレーシングをエンドツーエンドで有効にするために tracePropagationTargets を設定し、対応するスキルを提案します。

検出されたバックエンド	提案するスキル	トレースヘッダーのサポート
Go (go.mod)	sentry-go-sdk	✅ 自動
Python (requirements.txt)	sentry-python-sdk	✅ 自動
Ruby (Gemfile)	sentry-ruby-sdk	✅ 自動
Node.js バックエンド (package.json)	sentry-node-sdk（または sentry-express-sdk）	✅ 自動

---

トラブルシューティング

問題	解決策
イベントが表示されない	debug: true を設定し、DSN の形式を確認して、初期化がメインスレッドで行われていることを確認します
クラッシュが記録されない	デバッガーを接続せずに実行してください。デバッガーがシグナルを横取りします
アプリのハングが報告されない	デバッガーが接続されていると自動的に無効になります。appHangTimeoutInterval を確認してください
セッションリプレイが記録されない	iOS のバージョンを確認してください。iOS 26 以降ではデフォルトで無効です（Liquid Glass）。sessionSampleRate > 0 であることを確認してください
トレースデータが見つからない	tracesSampleRate > 0 であることを確認し、enableAutoPerformanceTracing = true であることを確認してください
プロファイリングデータが見つからない	configureProfiling で sessionSampleRate > 0 であることを確認してください。.trace ライフサイクルでは、トレーシングを有効にする必要があります
rsync.samba ビルドエラー（CocoaPods）	ターゲット設定 → 「Enable User Script Sandbox」 → NO
複数の SPM プロダクトが選択されている	Sentry、Sentry-Dynamic、SentrySwiftUI、Sentry-WithoutUIKitOrAppKit のいずれか 1 つだけを選択してください
inAppExclude のコンパイルエラー	SDK 9.0.0 で削除されました。inAppInclude のみを使用してください
ウォッチドッグによる終了が追跡されない	enableCrashHandler = true が必要です（デフォルトで有効です）
ネットワークのブレッドクラムが見つからない	enableSwizzling = true が必要です（デフォルトで有効です）
profilesSampleRate のコンパイルエラー	SDK 9.0.0 で削除されました。代わりに configureProfiling クロージャーを使用してください