Sentry Cocoa Sdk

# Error Monitoring — Sentry Cocoa SDK

> Minimum SDK: `sentry-cocoa` v7.0.0+
> Swift Error improvements: v8.7.0+
> HTTP client error capture: v8.0.0+

## Configuration

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `enableCrashHandler` | `Bool` | `true` | Master switch for crash reporting (signal handlers, Mach exceptions, C++) |
| `sampleRate` | `Float` (0.0–1.0) | `1.0` | Percentage of error events sent |
| `attachStacktrace` | `Bool` | `true` | Attach stack traces to all captured messages |
| `attachAllThreads` | `Bool` | `false` | Attach full stack traces for all threads (SDK 9.9+) |
| `maxBreadcrumbs` | `Int` | `100` | Max breadcrumbs per event |
| `enableAppHangTracking` | `Bool` | `true` | Detect main thread unresponsiveness |
| `appHangTimeoutInterval` | `Double` | `2.0` | Seconds before a hang is reported |
| `enableReportNonFullyBlockingAppHangs` | `Bool` | `true` | Include non-fully-blocking hangs where V2 is supported |
| `enableWatchdogTerminationTracking` | `Bool` | `true` | Track OS watchdog kills via heuristics |
| `enableCaptureFailedRequests` | `Bool` | `true` | Auto-capture HTTP client errors as Sentry events |
| `failedRequestStatusCodes` | `[HttpStatusCodeRange]` | `[500–599]` | Status code ranges that trigger error capture |
| `failedRequestTargets` | `[String]` | `[".*"]` | Hosts/regex patterns to monitor for HTTP errors |
| `attachScreenshot` | `Bool` | `false` | Capture screenshot when an error event fires |
| `attachViewHierarchy` | `Bool` | `false` | Capture view hierarchy when an error event fires |
| `sendDefaultPii` | `Bool` | `false` | Include PII (IP address, username) in events |

## Code Examples

### SDK initialization

```swift
import Sentry

SentrySDK.start { options in
    options.dsn = "https://examplePublicKey@o0.ingest.sentry.io/0"
    options.environment = "production"
    options.releaseName = "my-app@2.0.0+123"
    options.enableCrashHandler = true   // default; explicit for clarity
    options.attachScreenshot = true
    options.attachViewHierarchy = true
}
```

### Capture a message

```swift
SentrySDK.capture(message: "Something noteworthy happened")
```

### Capture a Swift Error / NSError

```swift
do {
    try riskyOperation()
} catch {
    SentrySDK.capture(error: error)
}
```

### Capture a custom SentryEvent

```swift
let event = Event(level: .warning)
event.message = SentryMessage(formatted: "Checkout flow aborted")
event.tags = ["feature": "checkout"]
event.extra = ["cart_items": 3]
SentrySDK.capture(event: event)
```

### Swift Error enum — human-readable titles (v8.7.0+)

By default, Swift error enum cases appear as `LoginError - Code: 1`. To get readable titles, conform to `CustomNSError`:

```swift
enum LoginError: Error {
    case wrongUser(id: String)
    case wrongPassword
}

extension LoginError: CustomNSError {
    var errorUserInfo: [String: Any] {
        [NSDebugDescriptionErrorKey: debugDescription]
    }

    private var debugDescription: String {
        switch self {
        case .wrongUser(let id): return "Wrong user (id: \(id))"
        case .wrongPassword:     return "Wrong password"
        }
    }
}

// Captures "LoginError - Wrong user (id: 12345)" as the issue title
SentrySDK.capture(error: LoginError.wrongUser(id: "12345"))
```

> Use `NSDebugDescriptionErrorKey`, NOT `NSLocalizedDescriptionKey`. Localized strings vary by device locale and create duplicate issues.

### Capture with per-event scope

The scope callback receives an isolated copy — changes don't affect global state:

```swift
SentrySDK.capture(error: error) { scope in
    scope.setTag(value: "checkout", key: "feature")
    scope.setContext(value: ["amount": 99.99, "currency": "USD"], key: "payment")
}

SentrySDK.capture(message: "Payment declined") { scope in
    scope.setLevel(.fatal)
    scope.setTag(value: "stripe", key: "payment_provider")
}
```

### App hang detection

```swift
SentrySDK.start { options in
    options.dsn = "___PUBLIC_DSN___"