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

# sentry-ios-swift-setup

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

# sentry-ios-swift-setupby sentry
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,…

`npx skills add https://github.com/getsentry/sentry-for-cursor --skill sentry-ios-swift-setup`Download ZIPGitHub

## 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 = "[email protected]"
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:

* Issues - Look for test message

* Performance - Look for app start transactions

* Replays - Look for session recordings

* Logs - Look for test log entry

## Common Issues and Solutions

### Issue: Events not appearing in Sentry

Solutions:

* Verify DSN is correct

* Check `options.debug = true` for console output

* Ensure network connectivity

* Wait 1-2 minutes for events to process

### Issue: Session Replay not recording

Solutions:

* Verify `sessionSampleRate > 0`

* Check SDK version is 8.0.0+

* For SwiftUI, check masking isn't hiding everything

### Issue: Tracing spans missing

Solutions:

* Verify `tracesSampleRate > 0`

* Ensure spans are properly finished with `.finish()`

### Issue: Logs not appearing

Solutions:

* Verify `options.enableLogs = true`

* Check SDK version is 8.55.0+

* Verify `beforeSendLog` isn't filtering everything

### Issue: CocoaPods installation fails

Solutions:

* Run `pod repo update`

* Delete `Podfile.lock` and `Pods/` directory, re-run `pod install`

* 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

FeatureConfigurationMinimum SDKError MonitoringDefault (always on)AnyTracing`tracesSampleRate`8.0.0+Profiling`configureProfiling`8.0.0+Session Replay`sessionReplay.sessionSampleRate`8.0.0+Logging`enableLogs = true`8.55.0+

Replay ModifierPurpose`.sentryReplayMask()`Hide view content`.sentryReplayUnmask()`Show view content`.sentryReplayPreviewMask()`Preview masking in SwiftUI previews

## More skills from sentry
sentry-cocoa-sdkby sentryFull 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-create-alertby sentryCreate Sentry alerts using the workflow engine API. Use when asked to create alerts, set up notifications, configure issue priority alerts, or build workflow…sentry-dotnet-sdkby sentryFull Sentry SDK setup for .NET. Use when asked to "add Sentry to .NET", "install Sentry for C#", or configure error monitoring, tracing, profiling, logging, or…sentry-fix-issuesby sentryFind and fix issues from Sentry using MCP. Use when asked to fix Sentry errors, debug production issues, investigate exceptions, or resolve bugs reported in…sentry-go-sdkby sentryFull Sentry SDK setup for Go. Use when asked to "add Sentry to Go", "install sentry-go", "setup Sentry in Go", or configure error monitoring, tracing, logging,…sentry-ios-swift-setupby sentrySetup Sentry in iOS/Swift apps. Use when asked to add Sentry to iOS, install sentry-cocoa SDK, or configure error monitoring for iOS applications using Swift…sentry-nextjs-sdkby sentryFull Sentry SDK setup for Next.js. Use when asked to "add Sentry to Next.js", "install @sentry/nextjs", or configure error monitoring, tracing, session replay,…sentry-otel-exporter-setupby sentryConfigure the OpenTelemetry Collector with Sentry Exporter for multi-project routing and automatic project creation. Use when setting up OTel with Sentry,…

---

**Source**: https://github.com/getsentry/sentry-for-cursor/tree/HEAD/skills/sentry-ios-swift-setup
**Author**: sentry
**Discovered via**: mcpservers.org