sentry-ios-swift-setup

name	sentry-ios-swift-setup
description	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. Use when this capability is needed.
metadata	{"author":"getsentry"}

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 1: Install SDK

Option A: Swift Package Manager (Recommended)

Via Package.swift:

dependencies: [
    .package(url: "https://github.com/getsentry/sentry-cocoa", from: "9.0.0")
]

Or via Xcode: File > Add Package Dependencies > https://github.com/getsentry/sentry-cocoa

Option B: CocoaPods

pod 'Sentry', '~> 9.0'

Then run pod install.

---

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 = "[e-mail]"
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

---

Common Issues and Solutions

Issue: Events not appearing in Sentry

Solutions:

1. Verify DSN is correct
2. Check options.debug = true for console output
3. Ensure network connectivity
4. Wait 1-2 minutes for events to process

Issue: Session Replay not recording

Solutions:

1. Verify sessionSampleRate > 0
2. Check SDK version is 8.0.0+
3. For SwiftUI, check masking isn't hiding everything

Issue: Tracing spans missing

Solutions:

1. Verify tracesSampleRate > 0
2. Ensure spans are properly finished with .finish()

Issue: Logs not appearing

Solutions:

1. Verify options.enableLogs = true
2. Check SDK version is 8.55.0+
3. Verify beforeSendLog isn't filtering everything

Issue: CocoaPods installation fails

Solutions:

1. Run pod repo update
2. Delete Podfile.lock and Pods/ directory, re-run pod install
3. Ensure minimum iOS deployment target is 13.0+

---

Summary Checklist

## Sentry iOS Setup Complete

### Installation:
- [ ] SDK added via Swift Package Manager or CocoaPods
- [ ] SDK version 9.0.0+ installed

### Configuration Applied:
- [ ] DSN configured
- [ ] Environment set
- [ ] attachScreenshot / attachViewHierarchy enabled
- [ ] Tracing (tracesSampleRate)
- [ ] Profiling (configureProfiling)
- [ ] Session Replay (sessionReplay settings)
- [ ] Logging (enableLogs)

### Next Steps:
1. Set appropriate sample rates for production
2. Configure user context after authentication
3. Review masking for sensitive screens
4. Add custom spans for important operations

---

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

---

Converted and distributed by TomeVault — claim your Tome and manage your conversions.