sentry-cocoa-sdk

What this skill does

> [All Skills](../../SKILL_TREE.md) > [SDK Setup](../sentry-sdk-setup/SKILL.md) > Cocoa SDK

# 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, or metrics in Swift
- 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.15.0).
> Always verify against [docs.sentry.io/platforms/apple/](https://docs.sentry.io/platforms/apple/) before implementing.

---

## Phase 1: Detect

Run these commands to understand the project before making any recommendations:

```bash
# 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
```

**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.)
- SwiftUI tracing import/product? `SentrySwiftUI` still exists but is deprecated in SDK 9.4.1+; prefer the main `Sentry` module for released binary products.
- 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 iOS/macOS apps; UI profiling via `configureProfiling`

**Optional (enhanced observability):**
- **Session Replay** — user-facing iOS apps; verify masking on iOS 26+ / Liquid Glass builds
- **Logging** — when structured log capture is needed
- **Metrics** — Swift apps needing aggregate counters, gauges, or distributions
- **User Feedback** — apps that want crash/error feedback forms from users

**Not available for Cocoa:**
- Crons — backend only
- AI Monitoring — JS/Python only

**Recommendation logic:**

| Feature | Recommend when... |
|---------|------------------|
| Error Monitoring | **Always** — non-negotiable baseline |
| Tracing | **Always for apps** — rich auto-instrumentation out of the box |
| Profiling | iOS/macOS production apps where performance matters (not tvOS/watchOS/visionOS) |
| Session Replay | User-facing iOS apps; tvOS may work but is not officially supported |
| Logging | Existing `os.log` / CocoaLumberjack usage, or structured logs needed |
| Metrics | Aggregate product or health signals that should not create issues; Swift only, SDK 9.12+ |
| 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?"*

---

## Phase 3: Guide

### Install

**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 ios
> ```
>
> It 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](#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`:
```swift
.package(url: "https://github.com/getsentry/sentry-cocoa", from: "9.15.0"),
```

**SPM Products** — choose **exactly one** per target:

| Product | Use Case |
|---------|----------|
| `Sentry` | **Recommended** — static framework, fast app start; includes SwiftUI APIs in SDK 9.4.1+ |
| `Sentry-Dynamic` | Dynamic framework alternative |
| `SentrySwiftUI` | Legacy/deprecated re-export for SwiftUI APIs; use only when maintaining older setup |
| `Sentry-WithoutUIKitOrAppKit` | watchOS, app extensions, CLI tools (Swift < 6.1) |
| `SentrySPM` + `NoUIFramework` trait | Source build without UIKit/AppKit for CLI/headless targets (**SDK 9.7+ / Swift 6.1+ / Xcode 26.4+** for Xcode UI) |

> Warning: Xcode allows selecting multiple products — choose only one.
>
> If using `SentrySPM` from source, current source-build projects may import `SentrySwift` instead of `Sentry`; verify the module name in the target. Released binary products use `import Sentry`.

**Swift 6.1+ trait-based opt-out of UIKit/AppKit** (requires `[email protected]` manifest):

```swift
// 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")
```

This is the preferred opt-out path for command-line/headless targets on Swift 6.1+. It compiles the SDK from source so the trait can remove UIKit/AppKit/SwiftUI linkage. For Swift < 6.1 continue using `Sentry-WithoutUIKitOrAppKit`.

> **Note:** Package traits are visible in the Xcode UI starting with **Xcode 26.4+**. On older Xcode versions, traits still work when declared in `Package.swift` but won't appear in the GUI.

**Option 3 — CocoaPods (deprecated; prefer SPM):**
```ruby
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 plans to stop publishing CocoaPods releases at the end of June 2026; use this only for existing CocoaPods projects.

> **Known issue (Xcode 14+):** Sandbox `rsync.samba` error → Target Settings → "Enable User Script Sandbox" → `NO`.

---

### Quick Start — Recommended Init

Full iOS app config enabling the most common features with sensible defaults. Add before any other code at app startup.

For macOS, watchOS, app extensions, or `NoUIFramework` builds, omit options that are unavailable for that platform (`sessionReplay`, screenshots/view hierarchy, user-feedback UI, UIKit tracing, and profiling on tvOS/watchOS/visionOS). Keep the core `dsn`, environment, error monitoring, tracing, logs, and metrics settings that compile for the detected target.

**SwiftUI — App entry point:**
```swift
import SwiftUI
import Sentry

@main
struct MyApp: App {
    init()