All Skills > SDK Setup > Cocoa SDK

Sentry Cocoa SDK

Apple プロジェクトをスキャンし、完全な Sentry セットアップをガイドする意見的なウィザード。

このスキルを実行する場合

• ユーザーが Apple アプリで「iOS に Sentry を追加」「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 struct) または UIKit (AppDelegate)? 初期化パターンを決めます。
• どの Apple プラットフォーム? (利用可能な機能に影響します — プラットフォームサポートマトリックスを参照してください。)
• 既存のログライブラリ? (構造化ログキャプチャを有効にします。)
• バックエンドを伴いますか? (フェーズ 4 クロスリンクを分散トレーシング用にトリガーします。)

---

フェーズ 2: 推奨

見つけたものに基づいて、具体的な推奨を提示します。オープンエンドな質問はしないでください — 提案をリードしてください:

推奨 (コアカバレッジ):

• ✅ エラーモニタリング — 常に必須; クラッシュレポート、アプリハング、ウォッチドッグ終了、NSError/Swift エラー
• ✅ トレーシング — アプリの場合は常に必須; アプリ起動、ネットワーク、UIViewController、ファイル I/O、Core Data を自動計測します
• ✅ プロファイリング — 本番アプリ; 最小限のオーバーヘッドで継続的なプロファイリング

オプション (拡張観測性):

• ⚡ セッションリプレイ — ユーザー向けアプリ; ⚠️ iOS 26+ ではデフォルトで無効 (Liquid Glass レンダリング)
• ⚡ ログ — 構造化ログキャプチャが必要な場合
• ⚡ ユーザーフィードバック — ユーザーからのクラッシュ/エラーフィードバックフォームを希望するアプリ

Cocoa では利用不可:

• ❌ メトリクス — 代わりにカスタムスパンを使用してください
• ❌ Crons — バックエンドのみ
• ❌ AI Monitoring — JS/Python のみ

推奨ロジック:

機能	推奨される場合...
エラーモニタリング	常に必須 — 交渉不可のベースライン
トレーシング	アプリの場合は常に必須 — すぐに豊富な自動計測が可能
プロファイリング	パフォーマンスが重要な本番アプリ
セッションリプレイ	iOS のみ ユーザー向けアプリ (iOS 26+ の注意事項を確認; tvOS/macOS/watchOS/visionOS ではない)
ログ	既存の os.log / CocoaLumberjack の使用、または構造化ログが必要な場合
ユーザーフィードバック	スクリーンショット付きのアプリ内バグレポートを希望するアプリ

提案: 「エラーモニタリング + トレーシング + プロファイリングを推奨します。セッションリプレイとログも追加しましょうか?」

---

フェーズ 3: ガイド

インストール

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

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

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

これはログイン、org/プロジェクト選択、認証トークンセットアップ、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.5.1"),

SPM プロダクト — ターゲットごとに正確に 1 つを選択:

プロダクト	ユースケース
Sentry	推奨 — スタティックフレームワーク、高速アプリ起動
Sentry-Dynamic	ダイナミックフレームワークの代替
SentrySwiftUI	SwiftUI ビューパフォーマンストラッキング (SentryTracedView)
Sentry-WithoutUIKitOrAppKit	watchOS、アプリエクステンション、CLI ツール (Swift < 6.1)
SentrySPM + NoUIFramework trait	watchOS、アプリエクステンション、macOS CLI ツール (Swift 6.1+ / Xcode 16.3+ のみ)

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

Swift 6.1+ トレイトベースの UIKit/AppKit のオプトアウト (requires Package@swift-6.1.swift manifest):

// Package.swift (Swift 6.1+)
.package(url: "https://github.com/getsentry/sentry-cocoa", from: "9.5.1"),

// In your target's dependencies:
.product(name: "SentrySPM", package: "sentry-cocoa", condition: .when(traits: ["NoUIFramework"]))

これは Swift 6.1+ での macOS コマンドラインツールとアプリエクステンションの推奨されるオプトアウトパスです。Swift < 6.1 の場合は Sentry-WithoutUIKitOrAppKit を引き続き使用してください。

注: パッケージトレイトは Xcode 26.4+ 以降の Xcode UI に表示されます (現在ベータ版)。古い Xcode バージョンでも、Package.swift で宣言されたトレイトは機能しますが、GUI には表示されません。

オプション 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://examplePublicKey@o0.ingest.sentry.io/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://examplePublicKey@o0.ingest.sentry.io/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 初期化は メインスレッド で実行する必要があります。

---

合意した各機能について

機能を 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/user-feedback.md	アプリ内バグレポートが必要

各機能について: ${SKILL_ROOT}/references/<feature>.md を読み込み、手順に正確に従い、動作することを確認します。

---

設定リファレンス

キーとなる SentryOptions フィールド

オプション	型	デフォルト	目的
dsn	String	""	SDK が無効の場合は空; SENTRY_DSN 環境変数を読み込みます
environment	String	""	例: "production"; SENTRY_ENVIRONMENT を読み込みます
releaseName	String	""	例: "my-app@1.0.0"; 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	クラッシュ後の次のアプリ起動時に呼ばれます
strictTraceContinuation	Bool	false	他の org からの受信トレースを拒否; baggage ヘッダーの org_id を検証します (sentry-cocoa ≥9.10.0)
orgId	String?	nil	厳密なトレース検証用の Organization ID; DSN ホストから自動解析 (例: o123.ingest.sentry.io → "123") 明示的に設定されていない場合

環境変数

変数	マッピング先	目的
SENTRY_DSN	dsn	Data Source Name
SENTRY_RELEASE	releaseName	アプリバージョン (例: my-app@1.0.0)
SENTRY_ENVIRONMENT	environment	デプロイ環境

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

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

---

検証

Sentry がイベントを受け取っていることをテストします:

// テストエラーイベントをトリガー:
SentrySDK.capture(message: "Sentry Cocoa SDK test")

// またはクラッシュレポートをテスト (デバッガなし — クラッシュはデバッガによってインターセプト):
// SentrySDK.crash()  // コメント解除、デバッガなしで実行、再起動してクラッシュレポートを確認

数秒以内に Sentry ダッシュボードを確認します。何も表示されない場合:

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

---

本番設定

ボリュームとコストを制御するために、本番環境ではサンプルレートを下げます:

options.tracesSampleRate = 0.2          // トランザクションの 20%

options.configureProfiling = {
    $0.sessionSampleRate = 0.1          // セッションの 10%
    $0.lifecycle = .trace
}

options.sessionReplay.sessionSampleRate = 0.1   // 連続 10%
options.sessionReplay.onErrorSampleRate = 1.0   // エラー時 100% (高くしておく)

options.debug = false                   // 本番では決して使用しないでください

---

フェーズ 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)	Target Settings → "Enable User Script Sandbox" → NO
複数の SPM プロダクトが選択されている	Sentry、Sentry-Dynamic、SentrySwiftUI、Sentry-WithoutUIKitOrAppKit、または SentrySPM (Swift 6.1+ で NoUIFramework trait) のいずれか 1 つのみを選択します
inAppExclude コンパイルエラー	SDK 9.0.0 で削除 — inAppInclude のみを使用します
ウォッチドッグ終了が追跡されない	enableCrashHandler = true が必要です (デフォルトで有効)
ネットワークパンくずリストが不足	enableSwizzling = true が必要です (デフォルトで有効)
profilesSampleRate コンパイルエラー	SDK 9.0.0 で削除 — 代わりに configureProfiling クロージャを使用します