Labsco
getsentry logo

sentry-cocoa-sdk

โœ“ Officialโ˜… 19

by sentry ยท part of getsentry/sentry-agent-skills

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", or configure error monitoring, tracing, profiling, session replay, or logging for Apple applications. Supports SwiftUI and UIKit.

๐Ÿ”ฅ๐Ÿ”ฅ๐Ÿ”ฅ๐Ÿ”ฅโœ“ VerifiedFreeAdvanced setup
๐Ÿงฉ One of 7 skills in the getsentry/sentry-agent-skills package โ€” works on its own, and pairs well with its siblings.

This is the playbook your agent receives when the skill activates โ€” you don't need to read it to use the skill, but it's here to audit before installing.

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 baseline
TracingAlways for apps โ€” rich auto-instrumentation out of the box
ProfilingProduction apps where performance matters
Session ReplayiOS only user-facing apps (check iOS 26+ caveat; not tvOS/macOS/watchOS/visionOS)
LoggingExisting os.log / CocoaLumberjack usage, or structured logs needed
User 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
SentryRecommended โ€” static framework, fast app start
Sentry-DynamicDynamic framework alternative
SentrySwiftUISwiftUI view performance tracking (SentryTracedView)
Sentry-WithoutUIKitOrAppKitwatchOS, 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.


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:

FeatureReference fileLoad when...
Error Monitoring${SKILL_ROOT}/references/error-monitoring.mdAlways (baseline)
Tracing${SKILL_ROOT}/references/tracing.mdApp launch, network, UIViewController perf
Profiling${SKILL_ROOT}/references/profiling.mdProduction perf-sensitive apps
Session Replay${SKILL_ROOT}/references/session-replay.mdUser-facing iOS/tvOS apps
Logging${SKILL_ROOT}/references/logging.mdStructured log capture needed
User Feedback${SKILL_ROOT}/references/user-feedback.mdIn-app bug reporting wanted

For each feature: Read ${SKILL_ROOT}/references/<feature>.md, follow steps exactly, verify it works.


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:

  1. Set options.debug = true โ€” prints SDK internals to Xcode console
  2. Verify the DSN is correct and the project exists
  3. 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

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