Labsco
getsentry logo

sentry-ios-swift-setup

✓ Official★ 2

by sentry · part of getsentry/sentry-for-cursor

Setup Sentry in iOS/Swift apps. Use when asked to add Sentry to iOS, install sentry-cocoa SDK, or configure error monitoring, tracing, session replay, logging, or profiling for iOS applications using Swift and SwiftUI.

🔥🔥🔥✓ VerifiedFreeQuick setup
#email#automation#devops#git#monitoring
🧰 Not standalone. This skill ships with getsentry/sentry-for-cursor and only works together with that tool — install the tool first, then add this skill.

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.

Setup Sentry for iOS (Swift)

This skill helps configure Sentry's iOS SDK (sentry-cocoa) for Swift and SwiftUI applications, including error monitoring, tracing, session replay, structured logging, and profiling.

When to Use This Skill

Invoke this skill when:

  • User asks to "setup Sentry for iOS" or "add Sentry to my Swift app"
  • User wants error monitoring, crash reporting, or performance monitoring for iOS
  • User requests session replay, tracing, logging, or profiling for iOS
  • User mentions "sentry-cocoa" or SentrySDK.start

Platform Detection

Before configuring, verify this is an iOS/Swift project:

# Check for Xcode project files
ls -la *.xcodeproj *.xcworkspace Package.swift 2>/dev/null

# Check for existing Sentry installation
grep -r "sentry-cocoa" Package.swift Package.resolved 2>/dev/null
grep -i "sentry" Podfile Podfile.lock 2>/dev/null

# Check for existing Sentry imports
grep -r "import Sentry" --include="*.swift" . 2>/dev/null | head -5

Minimum Requirements

  • iOS: 13.0+ / Xcode: 15.0+ / Swift: 5.0+
  • SDK Version: 9.0.0+ (current stable: 9.3.0)

Step 2: Locate App Entry Point

Find the main app file:

  • SwiftUI: File with @main attribute (e.g., YourAppApp.swift)
  • UIKit: AppDelegate.swift

Step 3: Initialize Sentry

SwiftUI App

import SwiftUI
import Sentry

@main
struct YourAppApp: App {
    init() {
        SentrySDK.start { options in
            options.dsn = "YOUR_DSN_HERE"
            options.environment = "development"
            options.debug = true  // Disable in production

            // Error monitoring
            options.attachScreenshot = true
            options.attachViewHierarchy = true

            // Tracing (1.0 = 100%, lower in production)
            options.tracesSampleRate = 1.0

            // Profiling
            options.configureProfiling = {
                $0.sessionSampleRate = 1.0
                $0.lifecycle = .trace
            }

            // Session Replay
            options.sessionReplay.sessionSampleRate = 1.0
            options.sessionReplay.onErrorSampleRate = 1.0

            // Structured Logging
            options.enableLogs = true
        }
    }

    var body: some Scene {
        WindowGroup {
            ContentView()
        }
    }
}

UIKit App

import UIKit
import Sentry

@main
class AppDelegate: UIResponder, UIApplicationDelegate {
    func application(_ application: UIApplication,
                     didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {

        SentrySDK.start { options in
            options.dsn = "YOUR_DSN_HERE"
            options.environment = "development"
            options.debug = true
            options.attachScreenshot = true
            options.attachViewHierarchy = true
            options.tracesSampleRate = 1.0
            options.configureProfiling = {
                $0.sessionSampleRate = 1.0
                $0.lifecycle = .trace
            }
            options.sessionReplay.sessionSampleRate = 1.0
            options.sessionReplay.onErrorSampleRate = 1.0
            options.enableLogs = true
        }

        return true
    }
}

Production Sample Rates

For production, use appropriate sample rates:

options.debug = false
options.tracesSampleRate = 0.2
options.configureProfiling = { $0.sessionSampleRate = 0.2; $0.lifecycle = .trace }
options.sessionReplay.sessionSampleRate = 0.1
options.sessionReplay.onErrorSampleRate = 1.0

Structured Logging

Requires SDK 8.55.0+ (recommended: 9.0.0+). Ensure options.enableLogs = true is set.

let logger = SentrySDK.logger

// Basic levels
logger.trace("Detailed trace information")
logger.debug("Debug information")
logger.info("Informational message")
logger.warn("Warning message")
logger.error("Error occurred")
logger.fatal("Fatal error")

// With attributes
logger.info("User action completed", attributes: [
    "userId": "user_123",
    "action": "checkout",
    "itemCount": 3
])

// String interpolation (values become searchable attributes)
logger.info("User \(userId) purchased \(itemCount) items")

Log Filtering

options.beforeSendLog = { log in
    if log.level == .debug { return nil }
    return log
}

Session Replay

By default, Session Replay masks all text, images, and user input.

SwiftUI Masking Modifiers

// Unmask safe content
Text("Welcome to the App").sentryReplayUnmask()

// Mask sensitive content
Text(user.email).sentryReplayMask()
Text(user.creditCardLast4).sentryReplayMask()

Masking by View Class

options.sessionReplay.maskedViewClasses = [SensitiveDataView.self]
options.sessionReplay.unmaskedViewClasses = [PublicLabel.self]

Unmasking for Development

// WARNING: Only for development/testing
options.sessionReplay.maskAllText = false
options.sessionReplay.maskAllImages = false

Custom Spans

With tracing enabled, Sentry automatically instruments app launches, URLSession requests, UI transitions, File I/O, Core Data, and app hangs.

For custom operations:

// Simple span
let span = SentrySDK.span
let childSpan = span?.startChild(operation: "custom.operation", description: "Processing data")
// Do work...
childSpan?.finish()

// Async/await pattern
func processOrder(_ orderId: String) async throws -> Order {
    let span = SentrySDK.span?.startChild(
        operation: "order.process",
        description: "Processing order \(orderId)"
    )
    defer { span?.finish() }
    span?.setData(value: orderId, key: "order.id")
    let order = try await orderService.process(orderId)
    span?.setData(value: order.total, key: "order.total")
    return order
}

User Context

// Set user after authentication
let user = User()
user.userId = "user_123"
user.email = "user@example.com"
user.username = "johndoe"
SentrySDK.setUser(user)

// Clear on logout
SentrySDK.setUser(nil)

Manual Error Capture

// Capture an error
do {
    try riskyOperation()
} catch {
    SentrySDK.capture(error: error)
}

// Capture with extra context
SentrySDK.capture(error: error) { scope in
    scope.setTag(value: "checkout", key: "feature")
    scope.setExtra(value: orderId, key: "order_id")
}

Verification Steps

// Test error capture
SentrySDK.capture(message: "Test message from iOS app")

// Test logging
SentrySDK.logger.info("Test log from iOS app", attributes: ["test": true])

Check in Sentry:

  1. Issues - Look for test message
  2. Performance - Look for app start transactions
  3. Replays - Look for session recordings
  4. Logs - Look for test log entry

Summary Checklist


## Quick Reference

| Feature | Configuration | Minimum SDK |
|---------|--------------|-------------|
| Error Monitoring | Default (always on) | Any |
| Tracing | `tracesSampleRate` | 8.0.0+ |
| Profiling | `configureProfiling` | 8.0.0+ |
| Session Replay | `sessionReplay.sessionSampleRate` | 8.0.0+ |
| Logging | `enableLogs = true` | 8.55.0+ |

| Replay Modifier | Purpose |
|-----------------|---------|
| `.sentryReplayMask()` | Hide view content |
| `.sentryReplayUnmask()` | Show view content |
| `.sentryReplayPreviewMask()` | Preview masking in SwiftUI previews |