npx claudepluginhub getsentry/sentry-for-ai --plugin sentryThis skill uses the workspace's default tool permissions.
> [All Skills](../../SKILL_TREE.md) > [SDK Setup](../sentry-sdk-setup/SKILL.md) > Cocoa SDK
Sets up full Sentry SDK for Apple platforms including iOS, macOS, tvOS, watchOS, visionOS with error monitoring, tracing, profiling, session replay, and logging. Supports SwiftUI and UIKit.
Sets up Sentry SDK in Flutter and Dart projects for error monitoring, tracing, profiling, session replay, logging, and integrations like Dio, go_router. Supports Android, iOS, macOS, Linux, Windows, Web.
Routes iOS build failures, compilation errors, Xcode issues, simulator problems, SPM conflicts, and test crashes to specialized diagnostics before code debugging.
Share bugs, ideas, or general feedback.
All Skills > SDK Setup > Cocoa SDK
Opinionated wizard that scans your Apple project and guides you through complete Sentry setup.
sentry-cocoa, SentrySDK, or the Apple/iOS Sentry SDKNote: SDK versions and APIs below reflect Sentry docs at time of writing (sentry-cocoa 9.5.1). Always verify against docs.sentry.io/platforms/apple/ before implementing.
Run these commands to understand the project before making any recommendations:
# 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
What to note:
sentry-cocoa already in Package.swift or Podfile? If yes, skip to Phase 2 (configure features).@main App struct) or UIKit (AppDelegate)? Determines init pattern.Based on what you found, present a concrete recommendation. Don't ask open-ended questions — lead with a proposal:
Recommended (core coverage):
Optional (enhanced observability):
Not available for Cocoa:
Recommendation logic:
| Feature | Recommend when... |
|---|---|
| Error Monitoring | Always — non-negotiable baseline |
| Tracing | Always for apps — rich auto-instrumentation out of the box |
| Profiling | Production apps where performance matters |
| Session Replay | iOS only user-facing apps (check iOS 26+ caveat; not tvOS/macOS/watchOS/visionOS) |
| Logging | Existing os.log / CocoaLumberjack usage, or structured logs needed |
| User Feedback | Apps wanting in-app bug reports with screenshots |
Propose: "I recommend Error Monitoring + Tracing + Profiling. Want me to also add Session Replay and Logging?"
Option 1 — Sentry Wizard (recommended):
You need to run this yourself — the wizard opens a browser for login and requires interactive input that the agent can't handle. Copy-paste into your terminal:
brew install getsentry/tools/sentry-wizard && sentry-wizard -i iosIt handles login, org/project selection, auth token setup, SDK installation, AppDelegate updates, and dSYM/debug symbol upload build phases.
Once it finishes, come back and skip to Verification.
If the user skips the wizard, proceed with Option 2 (SPM/CocoaPods) and manual setup below.
Option 2 — Swift Package Manager: File → Add Packages → enter:
https://github.com/getsentry/sentry-cocoa.git
Or in Package.swift:
.package(url: "https://github.com/getsentry/sentry-cocoa", from: "9.5.1"),
SPM Products — choose exactly one per target:
| Product | Use Case |
|---|---|
Sentry | Recommended — static framework, fast app start |
Sentry-Dynamic | Dynamic framework alternative |
SentrySwiftUI | SwiftUI view performance tracking (SentryTracedView) |
Sentry-WithoutUIKitOrAppKit | watchOS, app extensions, CLI tools (Swift < 6.1) |
SentrySPM + NoUIFramework trait | watchOS, app extensions, macOS CLI tools (Swift 6.1+ / Xcode 16.3+ only) |
⚠️ Xcode allows selecting multiple products — choose only one.
Swift 6.1+ trait-based opt-out of 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"]))
This is the preferred opt-out path for macOS command-line tools and app extensions on Swift 6.1+. For Swift < 6.1 continue using Sentry-WithoutUIKitOrAppKit.
Note: Package traits are visible in the Xcode UI starting with Xcode 26.4+ (currently in beta). On older Xcode versions, traits still work when declared in
Package.swiftbut won't appear in the GUI.
Option 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
Known issue (Xcode 14+): Sandbox
rsync.sambaerror → Target Settings → "Enable User Script Sandbox" →NO.
Full config enabling the most features with sensible defaults. Add before any other code at app startup.
SwiftUI — App entry point:
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 initialization must occur on the main thread.
Walk through features one at a time. Load the reference file for each, follow its steps, and verify before moving to the next:
| Feature | Reference file | Load when... |
|---|---|---|
| Error Monitoring | ${SKILL_ROOT}/references/error-monitoring.md | Always (baseline) |
| Tracing | ${SKILL_ROOT}/references/tracing.md | App launch, network, UIViewController perf |
| Profiling | ${SKILL_ROOT}/references/profiling.md | Production perf-sensitive apps |
| Session Replay | ${SKILL_ROOT}/references/session-replay.md | User-facing iOS/tvOS apps |
| Logging | ${SKILL_ROOT}/references/logging.md | Structured log capture needed |
| User Feedback | ${SKILL_ROOT}/references/user-feedback.md | In-app bug reporting wanted |
For each feature: Read ${SKILL_ROOT}/references/<feature>.md, follow steps exactly, verify it works.
SentryOptions Fields| Option | Type | Default | Purpose |
|---|---|---|---|
dsn | String | "" | SDK disabled if empty; reads SENTRY_DSN env var |
environment | String | "" | e.g., "production"; reads SENTRY_ENVIRONMENT |
releaseName | String | "" | e.g., "my-app@1.0.0"; reads SENTRY_RELEASE |
debug | Bool | false | Verbose SDK output — disable in production |
sendDefaultPii | Bool | false | Include IP, user info from active integrations |
enableCrashHandler | Bool | true | Master switch for crash reporting |
enableAppHangTrackingV2 | Bool | true (9.0+) | Differentiates fully/non-fully blocked hangs |
appHangTimeoutInterval | Double | 2.0 | Seconds before classifying as hang |
enableWatchdogTerminationTracking | Bool | true | Track watchdog kills (iOS, tvOS, Mac Catalyst) |
attachScreenshot | Bool | false | Capture screenshot on error |
attachViewHierarchy | Bool | false | Capture view hierarchy on error |
tracesSampleRate | NSNumber? | nil | Transaction sample rate (nil = tracing disabled); Swift auto-boxes Double literals (e.g. 1.0 → NSNumber) |
tracesSampler | Closure | nil | Dynamic per-transaction sampling (overrides rate) |
enableAutoPerformanceTracing | Bool | true | Master switch for auto-instrumentation |
tracePropagationTargets | [String] | [".*"] | Hosts/regex that receive distributed trace headers |
enableCaptureFailedRequests | Bool | true | Auto-capture HTTP 5xx errors as events |
enableNetworkBreadcrumbs | Bool | true | Breadcrumbs for outgoing HTTP requests |
inAppInclude | [String] | [] | Module prefixes treated as "in-app" code |
maxBreadcrumbs | Int | 100 | Max breadcrumbs per event |
sampleRate | Float | 1.0 | Error event sample rate |
beforeSend | Closure | nil | Hook to mutate/drop error events |
onCrashedLastRun | Closure | nil | Called on next launch after a crash |
strictTraceContinuation | Bool | false | Reject incoming traces from other orgs; validates org_id in baggage headers (sentry-cocoa ≥9.10.0) |
orgId | String? | nil | Organization ID for strict trace validation; auto-parsed from DSN host (e.g. o123.ingest.sentry.io → "123") if not set explicitly |
| Variable | Maps to | Purpose |
|---|---|---|
SENTRY_DSN | dsn | Data Source Name |
SENTRY_RELEASE | releaseName | App version (e.g., my-app@1.0.0) |
SENTRY_ENVIRONMENT | environment | Deployment environment |
| Feature | iOS | tvOS | macOS | watchOS | visionOS |
|---|---|---|---|---|---|
| Crash Reporting | ✅ | ✅ | ✅ | ✅ | ✅ |
| App Hangs V2 | ✅ | ✅ | ❌ | ❌ | ❌ |
| Watchdog Termination | ✅ | ✅ | ❌ | ❌ | ❌ |
| App Start Tracing | ✅ | ✅ | ❌ | ❌ | ✅ |
| UIViewController Tracing | ✅ | ✅ | ❌ | ❌ | ✅ |
| SwiftUI Tracing | ✅ | ✅ | ✅ | ❌ | ✅ |
| Network Tracking | ✅ | ✅ | ✅ | ❌ | ✅ |
| Profiling | ✅ | ✅ | ✅ | ❌ | ✅ |
| Session Replay | ✅ | ❌ | ❌ | ❌ | ❌ |
| MetricKit | ✅ (15+) | ❌ | ✅ (12+) | ❌ | ❌ |
Test that Sentry is receiving events:
// 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
Check the Sentry dashboard within a few seconds. If nothing appears:
options.debug = true — prints SDK internals to Xcode consoleLower sample rates for production to control volume and cost:
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
After completing Apple setup, check for a companion backend missing Sentry coverage:
# 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
If a backend is found, configure tracePropagationTargets to enable distributed tracing end-to-end, and suggest the matching skill:
| Backend detected | Suggest skill | Trace header support |
|---|---|---|
Go (go.mod) | sentry-go-sdk | ✅ automatic |
Python (requirements.txt) | sentry-python-sdk | ✅ automatic |
Ruby (Gemfile) | sentry-ruby-sdk | ✅ automatic |
Node.js backend (package.json) | sentry-node-sdk (or sentry-express-sdk) | ✅ automatic |
| Issue | Solution |
|---|---|
| Events not appearing | Set debug: true, verify DSN format, ensure init is on main thread |
| Crashes not captured | Run without debugger attached — debugger intercepts signals |
| App hangs not reported | Auto-disabled when debugger attached; check appHangTimeoutInterval |
| Session Replay not recording | Check iOS version — disabled by default on iOS 26+ (Liquid Glass); verify sessionSampleRate > 0 |
| Tracing data missing | Confirm tracesSampleRate > 0; check enableAutoPerformanceTracing = true |
| Profiling data missing | Verify sessionSampleRate > 0 in configureProfiling; for .trace lifecycle, tracing must be enabled |
rsync.samba build error (CocoaPods) | Target Settings → "Enable User Script Sandbox" → NO |
| Multiple SPM products selected | Choose only one of Sentry, Sentry-Dynamic, SentrySwiftUI, Sentry-WithoutUIKitOrAppKit, or SentrySPM (with NoUIFramework trait on Swift 6.1+) |
inAppExclude compile error | Removed in SDK 9.0.0 — use inAppInclude only |
| Watchdog termination not tracked | Requires enableCrashHandler = true (it is by default) |
| Network breadcrumbs missing | Requires enableSwizzling = true (it is by default) |
profilesSampleRate compile error | Removed in SDK 9.0.0 — use configureProfiling closure instead |