sentry-cocoa-sdk

$2b

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:

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?"

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:

.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.swift but 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.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://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.

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:

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.

Configuration Reference

Key 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

Environment Variables

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

Platform Feature Support Matrix

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+)

❌

❌

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

Troubleshooting

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