---
name: sentry-cocoa-sdk
description: Full Sentry SDK setup for Apple platforms (iOS, macOS, tvOS, watchOS, visionOS). Use when asked to "add Sentry to iOS", "add Sentry to Swift", "install…
---

# sentry-cocoa-sdk

Full Sentry SDK setup for Apple platforms (iOS, macOS, tvOS, watchOS, visionOS). Use when asked to "add Sentry to iOS", "add Sentry to Swift", "install…

# sentry-cocoa-sdkby sentry
Full Sentry SDK setup for Apple platforms (iOS, macOS, tvOS, watchOS, visionOS). Use when asked to "add Sentry to iOS", "add Sentry to Swift", "install…

`npx skills add https://github.com/getsentry/agent-skills --skill sentry-cocoa-sdk`Download ZIPGitHub

## Sentry Cocoa SDK

Opinionated wizard that scans your Apple project and guides you through complete Sentry setup.

## Invoke This Skill When

* User asks to "add Sentry to iOS/macOS/tvOS" or "set up Sentry" in an Apple app

* User wants error monitoring, tracing, profiling, session replay, or logging in Swift/ObjC

* User mentions `sentry-cocoa`, `SentrySDK`, or the Apple/iOS Sentry SDK

* User wants to monitor crashes, app hangs, watchdog terminations, or performance

Note: 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.

## Phase 1: Detect

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:

* Is `sentry-cocoa` already in `Package.swift` or `Podfile`? If yes, skip to Phase 2 (configure features).

* SwiftUI (`@main App` struct) or UIKit (`AppDelegate`)? Determines init pattern.

* Which Apple platforms? (Affects which features are available — see Platform Support Matrix.)

* Existing logging library? (Enables structured log capture.)

* Companion backend? (Triggers Phase 4 cross-link for distributed tracing.)

## Phase 2: Recommend

Based on what you found, present a concrete recommendation. Don't ask open-ended questions — lead with a proposal:

Recommended (core coverage):

* ✅ Error Monitoring — always; crash reporting, app hangs, watchdog terminations, NSError/Swift errors

* ✅ Tracing — always for apps; auto-instruments app launch, network, UIViewController, file I/O, Core Data

* ✅ Profiling — production apps; continuous profiling with minimal overhead

Optional (enhanced observability):

* ⚡ Session Replay — user-facing apps; ⚠️ disabled by default on iOS 26+ (Liquid Glass rendering)

* ⚡ Logging — when structured log capture is needed

* ⚡ User Feedback — apps that want crash/error feedback forms from users

Not available for Cocoa:

* ❌ Metrics — use custom spans instead

* ❌ Crons — backend only

* ❌ AI Monitoring — JS/Python only

Recommendation logic:

FeatureRecommend when...Error MonitoringAlways — non-negotiable baselineTracingAlways for apps — rich auto-instrumentation out of the boxProfilingProduction apps where performance mattersSession ReplayiOS only user-facing apps (check iOS 26+ caveat; not tvOS/macOS/watchOS/visionOS)LoggingExisting `os.log` / CocoaLumberjack usage, or structured logs neededUser FeedbackApps wanting in-app bug reports with screenshots
Propose: "I recommend Error Monitoring + Tracing + Profiling. Want me to also add Session Replay and Logging?"

## Phase 3: Guide

### Install

Option 1 — Sentry Wizard (recommended): Walks you through login, org/project selection, and auth token setup interactively. Then installs the SDK, updates AppDelegate, adds dSYM/debug symbol upload build phases, and configures everything automatically.

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

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:

ProductUse 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

⚠️ Xcode allows selecting multiple products — choose only one.

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.samba` error → Target Settings → "Enable User Script Sandbox" → `NO`.

### Quick Start — Recommended Init

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://[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 initialization must occur on the main thread.

### For Each Agreed Feature

Walk through features one at a time. Load the reference file for each, follow its steps, and verify before moving to the next:

FeatureReference fileLoad when...Error Monitoring`${SKILL_ROOT}/references/error-monitoring.md`Always (baseline)Tracing`${SKILL_ROOT}/references/tracing.md`App launch, network, UIViewController perfProfiling`${SKILL_ROOT}/references/profiling.md`Production perf-sensitive appsSession Replay`${SKILL_ROOT}/references/session-replay.md`User-facing iOS/tvOS appsLogging`${SKILL_ROOT}/references/logging.md`Structured log capture neededUser 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.

## Configuration Reference

### Key `SentryOptions` Fields

OptionTypeDefaultPurpose`dsn``String``""`SDK disabled if empty; reads `SENTRY_DSN` env var`environment``String``""`e.g., `"production"`; reads `SENTRY_ENVIRONMENT``releaseName``String``""`e.g., `"[email&#160;protected]"`; 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

### Environment Variables

VariableMaps toPurpose`SENTRY_DSN``dsn`Data Source Name`SENTRY_RELEASE``releaseName`App version (e.g., `[email&#160;protected]`)`SENTRY_ENVIRONMENT``environment`Deployment environment

### Platform Feature Support Matrix

FeatureiOStvOSmacOSwatchOSvisionOSCrash Reporting✅✅✅✅✅App Hangs V2✅✅❌❌❌Watchdog Termination✅✅❌❌❌App Start Tracing✅✅❌❌✅UIViewController Tracing✅✅❌❌✅SwiftUI Tracing✅✅✅❌✅Network Tracking✅✅✅❌✅Profiling✅✅✅❌✅Session Replay✅❌❌❌❌MetricKit✅ (15+)❌✅ (12+)❌❌

## Verification

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:

* Set `options.debug = true` — prints SDK internals to Xcode console

* Verify the DSN is correct and the project exists

* Ensure initialization is on the main thread

## Production Settings

Lower 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
`
```

## Phase 4: Cross-Link

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 detectedSuggest skillTrace header supportGo (`go.mod`)`sentry-go-sdk`✅ automaticPython (`requirements.txt`)`sentry-python-sdk`✅ automaticRuby (`Gemfile`)`sentry-ruby-sdk`✅ automaticNode.js backend (`package.json`)`sentry-node-sdk` (or `sentry-express-sdk`)✅ automatic

## Troubleshooting

IssueSolutionEvents not appearingSet `debug: true`, verify DSN format, ensure init is on main threadCrashes not capturedRun without debugger attached — debugger intercepts signalsApp hangs not reportedAuto-disabled when debugger attached; check `appHangTimeoutInterval`Session Replay not recordingCheck iOS version — disabled by default on iOS 26+ (Liquid Glass); verify `sessionSampleRate > 0`Tracing data missingConfirm `tracesSampleRate > 0`; check `enableAutoPerformanceTracing = true`Profiling data missingVerify `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 selectedChoose only one of `Sentry`, `Sentry-Dynamic`, `SentrySwiftUI`, `Sentry-WithoutUIKitOrAppKit``inAppExclude` compile errorRemoved in SDK 9.0.0 — use `inAppInclude` onlyWatchdog termination not trackedRequires `enableCrashHandler = true` (it is by default)Network breadcrumbs missingRequires `enableSwizzling = true` (it is by default)`profilesSampleRate` compile errorRemoved in SDK 9.0.0 — use `configureProfiling` closure instead

## More skills from sentry
sentry-create-alertby sentryCreate Sentry alerts using the workflow engine API. Use when asked to create alerts, set up notifications, configure issue priority alerts, or build workflow…sentry-dotnet-sdkby sentryFull Sentry SDK setup for .NET. Use when asked to "add Sentry to .NET", "install Sentry for C#", or configure error monitoring, tracing, profiling, logging, or…sentry-fix-issuesby sentryFind and fix issues from Sentry using MCP. Use when asked to fix Sentry errors, debug production issues, investigate exceptions, or resolve bugs reported in…sentry-go-sdkby sentryFull Sentry SDK setup for Go. Use when asked to "add Sentry to Go", "install sentry-go", "setup Sentry in Go", or configure error monitoring, tracing, logging,…sentry-ios-swift-setupby sentrySetup Sentry in iOS/Swift apps. Use when asked to add Sentry to iOS, install sentry-cocoa SDK, or configure error monitoring for iOS applications using Swift…sentry-nextjs-sdkby sentryFull Sentry SDK setup for Next.js. Use when asked to "add Sentry to Next.js", "install @sentry/nextjs", or configure error monitoring, tracing, session replay,…sentry-otel-exporter-setupby sentryConfigure the OpenTelemetry Collector with Sentry Exporter for multi-project routing and automatic project creation. Use when setting up OTel with Sentry,…sentry-pr-code-reviewby sentryReview a project's PRs to check for issues detected in code review by Seer Bug Prediction. Use when asked to review or fix issues identified by Sentry in PR…

---

**Source**: https://github.com/getsentry/agent-skills/tree/HEAD/skills/sentry-cocoa-sdk
**Author**: sentry
**Discovered via**: mcpservers.org