sentry-cocoa-sdk

すべてのスキル > SDK のセットアップ > Cocoa SDK

Sentry Cocoa SDK

Apple プロジェクトをスキャンし、Sentry の完全なセットアップを案内する、独自の見解を持ったウィザードです。

このスキルを使うタイミング

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

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

---

フェーズ 1：検出

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

# Check existing Sentry dependency
grep -rEi "sentry|sentry-cocoa|SentrySPM|SentrySwiftUI" \
  --include="Package.swift" --include="Podfile" --include="Cartfile" \
  --include="Package.resolved" --include="project.pbxproj" . 2>/dev/null | head -20

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

# Detect platform and deployment targets
grep -rE "platforms:|\\.iOS|\\.macOS|\\.tvOS|\\.watchOS|\\.visionOS|IPHONEOS_DEPLOYMENT_TARGET|MACOSX_DEPLOYMENT_TARGET|TVOS_DEPLOYMENT_TARGET|WATCHOS_DEPLOYMENT_TARGET|XROS_DEPLOYMENT_TARGET" \
  --include="Package.swift" --include="project.pbxproj" . 2>/dev/null | head -20
grep -E "platform :ios|platform :osx|platform :tvos|platform :watchos" Podfile 2>/dev/null

# Detect logging
grep -rE "import OSLog|import os\\.log|Logger\\(|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 プラットフォームは何ですか？（利用可能な機能に影響します。「プラットフォームのサポートマトリックス」を参照してください。）
• 既存のロギングライブラリはありますか？（構造化ログの取り込みが可能になります。）
• SwiftUI のトレーシング用インポート／プロダクトはありますか？SentrySwiftUI は引き続き存在しますが、SDK 9.4.1 以降では非推奨です。リリース済みのバイナリプロダクトでは、メインの Sentry モジュールを優先してください。
• 関連するバックエンドはありますか？（分散トレーシングのため、フェーズ 4 の相互リンクが必要になります。）

---

フェーズ 2：推奨

確認結果に基づいて、具体的な推奨事項を提示してください。自由回答形式の質問はせず、提案を先に示します。

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

• エラーモニタリング — 常に推奨します。クラッシュレポート、アプリのハング、ウォッチドッグによる終了、NSError／Swift エラーに対応します。
• トレーシング — アプリには常に推奨します。アプリの起動、ネットワーク、UIViewController、ファイル I/O、Core Data を自動計測します。
• プロファイリング — 本番環境の iOS/macOS アプリに推奨します。configureProfiling による UI プロファイリングが利用できます。

任意（オブザーバビリティの強化）：

• セッションリプレイ — ユーザー向けの iOS アプリに推奨します。iOS 26 以降／Liquid Glass ビルドではマスキングを確認してください。
• ロギング — 構造化ログの取り込みが必要な場合に利用します。
• メトリクス — 集計カウンター、ゲージ、分布が必要な Swift アプリに適しています。
• ユーザーフィードバック — ユーザーからクラッシュ／エラーのフィードバックを受け取るフォームが必要なアプリに適しています。

Cocoa では利用できない機能：

• Crons — バックエンドのみ
• AI Monitoring — JS/Python のみ

推奨の基準：

機能	推奨する条件
エラーモニタリング	常に — 必須となる基本機能
トレーシング	アプリには常に — すぐに利用できる充実した自動計測
プロファイリング	パフォーマンスが重要な本番環境の iOS/macOS アプリ（tvOS/watchOS/visionOS は対象外）
セッションリプレイ	ユーザー向けの iOS アプリ。tvOS でも動作する可能性はありますが、公式にはサポートされていません
ロギング	既存の os.log / CocoaLumberjack の利用がある場合、または構造化ログが必要な場合
メトリクス	イシューを発生させずに集計したいプロダクトまたはヘルスシグナル。Swift のみ、SDK 9.12 以降
ユーザーフィードバック	スクリーンショット付きのアプリ内バグレポートが必要なアプリ

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

---

フェーズ 3：案内

インストール

オプション 1 — Sentry Wizard（推奨）：

この操作はご自身で実行する必要があります — ウィザードはログイン用のブラウザーを開き、エージェントが処理できない対話形式の入力を求めます。以下をコピーしてターミナルに貼り付けてください：

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

ログイン、組織／プロジェクトの選択、認証トークンの設定、SDK のインストール、AppDelegate の更新、dSYM／デバッグシンボルのアップロード用ビルドフェーズを処理します。

完了したら、戻って確認に進んでください。

ユーザーがウィザードをスキップした場合は、オプション 2（SPM／CocoaPods）と以下の手動セットアップに進んでください。

オプション 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.15.0"),

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

プロダクト	用途
Sentry	推奨 — 静的フレームワークで、アプリの起動が高速です。SDK 9.4.1 以降では SwiftUI API を含みます
Sentry-Dynamic	動的フレームワークの代替
SentrySwiftUI	SwiftUI API 用の旧式／非推奨の再エクスポート。古いセットアップの保守に限り使用してください
Sentry-WithoutUIKitOrAppKit	watchOS、アプリ拡張機能、CLI ツール（Swift < 6.1）
SentrySPM + NoUIFramework trait	UIKit／AppKit を使わないソースビルド（CLI／ヘッドレスのターゲット向け。Xcode の UI には SDK 9.7+ / Swift 6.1+ / Xcode 26.4+ が必要です）

警告：Xcode では複数のプロダクトを選択できますが、1 つだけ選択してください。

SentrySPM をソースから使用する場合、現在のソースビルドプロジェクトでは Sentry ではなく SentrySwift をインポートすることがあります。ターゲット内のモジュール名を確認してください。リリース済みのバイナリプロダクトでは import Sentry を使用します。

Swift 6.1 以降で trait を使用して UIKit／AppKit を除外する方法（[email protected] マニフェストが必要です）：

// Package.swift (Swift 6.1+)
.package(
    url: "https://github.com/getsentry/sentry-cocoa",
    from: "9.15.0",
    traits: ["NoUIFramework"]
),

// In your target's dependencies:
.product(name: "SentrySPM", package: "sentry-cocoa")

これは、Swift 6.1 以降のコマンドライン／ヘッドレスのターゲットで、UIKit／AppKit／SwiftUI とのリンクを trait で除外できる、推奨の除外方法です。SDK をソースからコンパイルするため、Swift < 6.1 では引き続き Sentry-WithoutUIKitOrAppKit を使用してください。

注： パッケージの trait は、Xcode 26.4 以降で Xcode の UI に表示されます。それ以前のバージョンでも、Package.swift で宣言すれば trait は機能しますが、GUI には表示されません。

オプション 3 — CocoaPods（非推奨。SPM を推奨）：

platform :ios, '15.0'
use_frameworks!

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

Sentry は 2026 年 6 月末をもって CocoaPods リリースの公開を終了する予定です。既存の CocoaPods プロジェクトでのみ使用してください。

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

オプション 4 — SentryObjC（Objective-C／C++ のみのプロジェクト向け）：

Clang モジュールを有効にできない Objective-C または Objective-C++ のみのプロジェクト（例：-fmodules=NO）では、SentryObjC ラッパー SDK を使用してください。メイン SDK と同じ機能を備えていますが、Swift モジュールのインポートが不要な純粋な Objective-C ヘッダーを提供します。

SPM：

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

// In your target's dependencies:
.product(name: "SentryObjC", package: "sentry-cocoa")

または、リリースページから SentryObjC-Dynamic.xcframework.zip をダウンロードしてください。

通常の Sentry から SentryObjC への移行：

• #import <Sentry/Sentry.h> を #import <SentryObjC/SentryObjC.h> に変更します
• Sentry で始まる型名を SentryObjC に変更します（例：SentrySDK → SentryObjCSDK、SentryOptions → SentryObjCOptions）
• それ以外の API は同一です

ほとんどのユーザーには標準の Sentry プロダクト（オプション 2）を推奨します。Clang モジュールを使用できない具体的な理由がある場合に限り、SentryObjC を使用してください。

---

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

一般的な機能を、適切なデフォルト設定で有効にする iOS アプリの完全な設定です。アプリ起動時に、ほかのコードより前に追加してください。

macOS、watchOS、アプリ拡張機能、または NoUIFramework ビルドでは、そのプラットフォームで利用できないオプション（sessionReplay、スクリーンショット／ビュー階層、ユーザーフィードバック UI、UIKit トレーシング、tvOS／watchOS／visionOS でのプロファイリング）を省略してください。検出されたターゲットでコンパイルできる、コアの dsn、環境、エラー監視、トレーシング、ログ、メトリクスの設定は維持してください。

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"]
                ?? "production"
            // releaseName defaults to "<bundle id>@<version>+<build>"; set only if you need a custom release.

            // Error monitoring (on by default — explicit for clarity)
            options.enableCrashHandler = true
            options.enableAppHangTracking = true
            options.enableReportNonFullyBlockingAppHangs = 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. Keep production sampling conservative and verify masking on iOS 26+.
            options.sessionReplay.sessionSampleRate = 0.1
            options.sessionReplay.onErrorSampleRate = 1.0

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

            // Metrics are enabled by default in SDK 9.12+. Set false only to opt out.
            options.enableMetrics = 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"]
                ?? "production"
            // releaseName defaults to "<bundle id>@<version>+<build>"; set only if you need a custom release.

            options.enableCrashHandler = true
            options.enableAppHangTracking = true
            options.enableReportNonFullyBlockingAppHangs = 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 = 0.1
            options.sessionReplay.onErrorSampleRate = 1.0

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

            // Metrics are enabled by default in SDK 9.12+. Set false only to opt out.
            options.enableMetrics = true
        }
        return true
    }
}

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

---

合意した各機能について

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

機能	リファレンスファイル	読み込むタイミング...
エラー監視	${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/metrics.md	集計カウンター、ゲージ、分布
ユーザーフィードバック	${SKILL_ROOT}/references/user-feedback.md	アプリ内でのバグ報告が必要な場合

各機能について、Read ${SKILL_ROOT}/references/<feature>.md を読み、手順に正確に従って、動作を確認してください。

---

設定リファレンス

主要な SentryOptions フィールド

オプション	型	デフォルト	目的
dsn	String?	nil	空の場合は SDK が無効になります。macOS では SENTRY_DSN を読み取れますが、その他の Apple プラットフォームでは明示的に設定する必要があります
environment	String	"production"	例："production"
releaseName	String?	バンドルから取得	デフォルトは <bundle id>@<version>+<build> です
debug	Bool	false	詳細な SDK 出力 — 本番環境では無効にしてください
sendDefaultPii	Bool	false	有効なインテグレーションから IP アドレスやユーザー情報を含めます
enableCrashHandler	Bool	true	クラッシュレポートのマスタースイッチ
enableAppHangTracking	Bool	true	アプリのハング追跡のマスタースイッチ
enableReportNonFullyBlockingAppHangs	Bool	true	対応する UI プラットフォームで、完全にはブロックしないハングを報告します
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	[Any]	すべてのリクエスト	分散トレースヘッダーを受け取る文字列または NSRegularExpression 値
enableCaptureFailedRequests	Bool	true	HTTP 5xx エラーをイベントとして自動キャプチャします
enableNetworkBreadcrumbs	Bool	true	送信 HTTP リクエストのパンくずリスト
add(inAppInclude:)	Method	バンドルの実行ファイル	「アプリ内」コードとして扱うモジュールのプレフィックスを追加します
maxBreadcrumbs	Int	100	イベントあたりのパンくずリストの最大数
sampleRate	Float	1.0	エラーイベントのサンプルレート
beforeSend	Closure	nil	エラーイベントを変更または破棄するフック
onLastRunStatusDetermined	Closure	nil	SDK が前回起動時のクラッシュ状態を判定した後に呼び出されます
strictTraceContinuation	Bool	false	他の組織からのトレースを拒否します。baggage ヘッダー内の sentry-org_id を検証します（sentry-cocoa ≥9.10.0）
orgId	String?	nil	厳格なトレース検証に使用する組織 ID。明示的に設定されていない場合は、DSN ホストから自動解析されます（例：o123.ingest.sentry.io → "123"）
enableLogs	Bool	false	構造化ログを有効にします
enableMetrics	Bool	true	Swift Metrics API を有効にします（SDK 9.12+）

環境変数

変数	対応先	目的
SENTRY_DSN	dsn	macOS のみのフォールバックです。iOS/tvOS/watchOS/visionOS では明示的に設定してください
SENTRY_RELEASE	releaseName	Cocoa による自動フォールバックを前提にしないでください。必要に応じて明示的に設定してください
SENTRY_ENVIRONMENT	environment	Cocoa による自動フォールバックを前提にしないでください。必要に応じて明示的に設定してください

プラットフォーム機能サポート一覧

機能	iOS	tvOS	macOS	watchOS	visionOS
クラッシュレポート	はい	はい	はい	いいえ	はい
アプリのハング	はい	はい	はい	いいえ	はい
ウォッチドッグによる終了	はい	はい	いいえ	いいえ	はい
アプリ起動トレーシング	はい	はい	いいえ	いいえ	はい
UIViewController トレーシング	はい	はい	いいえ	いいえ	はい
SwiftUI トレーシング	はい	はい	はい	いいえ	はい
ネットワーク追跡	はい	はい	はい	いいえ	はい
プロファイリング	はい	いいえ	はい	いいえ	いいえ
セッションリプレイ	はい	非公式	いいえ	いいえ	いいえ
MetricKit	はい（15+）	いいえ	はい（12+）	いいえ	いいえ
Metrics API	はい	はい	はい	要確認	はい

本番環境の設定

ボリュームとコストを抑えるため、本番環境ではサンプルレートを下げてください。

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.enableLogs = true
options.enableMetrics = true             // default true in SDK 9.12+
options.debug = false                   // never in production

---

検証

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. 初期化がメインスレッドで行われていることを確認します

---

フェーズ 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 を確認します
Session Replay が記録されない	sessionSampleRate > 0 または onErrorSampleRate > 0 を確認します。iOS 26 以降では、マスキングと手動の Liquid Glass ゲーティングがある場合はその設定を確認します
トレーシングデータがない	tracesSampleRate > 0 を確認し、enableAutoPerformanceTracing = true であることを確認します
プロファイリングデータがない	configureProfiling 内の sessionSampleRate > 0 を確認します。.trace のライフサイクルでは、トレーシングを有効にする必要があります
rsync.samba のビルドエラー（CocoaPods）	Target Settings → 「Enable User Script Sandbox」→ NO
SPM のプロダクトが複数選択されている	Sentry、Sentry-Dynamic、SentrySwiftUI、Sentry-WithoutUIKitOrAppKit、SentrySPM のうち、1 つだけを選択します（Swift 6.1 以降では NoUIFramework トレイトを指定します）
inAppExclude のコンパイルエラー	SDK 9.0.0 で削除されました — 代わりに options.add(inAppInclude:) を使用します
enableAppHangTrackingV2 のコンパイルエラー	SDK 9.0.0 で削除されました — enableAppHangTracking を使用します。サポートされている環境では、V2 の動作がデフォルトです
Watchdog による終了が追跡されない	enableCrashHandler = true が必要です（デフォルトで有効です）
ネットワークのブレッドクラムがない	enableSwizzling = true が必要です（デフォルトで有効です）
profilesSampleRate のコンパイルエラー	SDK 9.0.0 で削除されました — 代わりに configureProfiling クロージャーを使用します