/sentry-cocoa-sdk

Tracing — Sentry Cocoa SDK

Minimum SDK: sentry-cocoa v7.0.0+
SwiftUI instrumentation stable: v8.17.0+
File I/O manual tracing extensions: v8.48.0+

Configuration

Code Examples

Basic tracing setup

import Sentry

SentrySDK.start { options in
    options.dsn = "___PUBLIC_DSN___"
    options.tracesSampleRate = 1.0   // 100% in dev; lower for production (e.g., 0.2)
}

Dynamic sampling with tracesSampler

SentrySDK.start { options in
    options.dsn = "___PUBLIC_DSN___"
    options.tracesSampler = { context in
        // Never sample next-launch transactions
        if context.isForNextAppLaunch { return 0 }
        // Always sample checkout
        if context.customSamplingContext?["flow"] as? String == "checkout" { return 1.0 }
        // Default: 25%
        return 0.25
    }
}

Custom transaction with child spans

import Sentry

func performCheckout() {
    let transaction = SentrySDK.startTransaction(
        name: "checkout",
        operation: "perform-checkout",
        bindToScope: true   // makes it accessible via SentrySDK.span
    )

    let validationSpan = transaction.startChild(
        operation: "validation",
        description: "validating shopping cart"
    )
    validateShoppingCart()
    validationSpan.finish()

    let processSpan = transaction.startChild(
        operation: "process",
        description: "processing payment"
    )

    do {
        try processPayment()
        processSpan.finish()
        transaction.finish()
    } catch {
        SentrySDK.capture(error: error)
        processSpan.finish(status: .internalError)
        transaction.finish(status: .internalError)
    }
}

Accessing the scope-bound span from a called function

func processPayment() {
    // Grab the transaction bound to scope (or start a standalone one)
    let span = SentrySDK.span ?? SentrySDK.startTransaction(
        name: "processPayment",
        operation: "task"
    )
    let child = span.startChild(operation: "payment.gateway")
    defer { child.finish() }

    // payment logic...
}

Setting data attributes on transactions and spans

let transaction = SentrySDK.startTransaction(name: "sync", operation: "task")
transaction.setData(value: "incremental",  key: "sync.type")
transaction.setData(value: 42,             key: "sync.item_count")
transaction.setData(value: true,           key: "sync.force")
transaction.setData(value: ["a", "b"],     key: "sync.queues")

let span = transaction.startChild(operation: "db.fetch")
span.setData(value: "orders",              key: "db.table")
span.finish()
transaction.finish()

Custom performance measurements

let span = SentrySDK.span

span?.setMeasurement(name: "memory_used",
                     value: 64,
                     unit: MeasurementUnitInformation.megabyte)

span?.setMeasurement(name: "profile_load_time",
                     value: 1.3,
                     unit: MeasurementUnitDuration.second)

span?.setMeasurement(name: "items_processed", value: 128)

Automatic Instrumentation

All features are enabled once tracesSampleRate > 0 (or tracesSampler is set). Disable all at once with enableAutoPerformanceTracing = false.

App Start Tracing

Platforms: iOS, tvOS, Mac Catalyst

Measures process creation → first rendered frame. Start type classifications:

Child spans produced (sequential):

⚠️ If more than 5 seconds elapse between transaction start and app-start end, app start spans are not attached to avoid misassociation.

URLSession Network Tracking

Platforms: All
Note: NSURLConnection is not supported — only NSURLSession.

Automatically adds HTTP spans to any active scope-bound transaction.

// Disable
options.enableNetworkTracking = false

UIViewController Lifecycle Tracing

Platforms: iOS, tvOS, Mac Catalyst
Not available for: SwiftUI (use SentryTracedView instead)

• Transaction operation: ui.load
• Transaction name: Your_App.MainViewController
• Auto-generated child spans: loadView, viewDidLoad, viewWillAppear, viewDidAppear
• Time to Initial Display (TTID) span: ui.load.initial-display

// Include framework view controllers
options.add(inAppInclude: "MyFramework")

// Exclude specific view controllers
options.swizzleClassNameExcludes = ["MyModalViewController"]

// Disable entirely
options.enableUIViewControllerTracing = false

Time to Full Display (TTFD)

// Enable globally
options.enableTimeToFullDisplayTracing = true

// In your view controller, signal when async content is fully loaded:
SentrySDK.reportFullyDisplayed()

TTFD span status:

SwiftUI Instrumentation

Package: SentrySwiftUI (separate SPM product — do not also add Sentry)

import SentrySwiftUI

// Option 1: wrapper
var body: some View {
    SentryTracedView("My Awesome Screen") {
        List { /* content */ }
    }
}

// Option 2: modifier
var body: some View {
    List { /* content */ }
        .sentryTrace("My Awesome Screen")
}

// With TTFD (v8.44.0+)
SentryTracedView("Content", waitForFullDisplay: true) {
    VStack { /* async content */ }
        .onAppear {
            Task {
                data = await loadData()
                SentrySDK.reportFullyDisplayed()
            }
        }
}

Slow & Frozen Frames

Platforms: iOS, tvOS, Mac Catalyst
Tracked automatically during any active transaction. Appears as Mobile Vitals in the Sentry Performance UI.

User Interaction Tracing

Platforms: iOS, tvOS, Mac Catalyst
Not available for: SwiftUI

Creates a transaction for every UIControl tap/click.

• Transaction operation: ui.action or ui.action.click
• Transaction name: YourApp_LoginViewController.loginButton
• idleTimeout: 3000 ms — transaction finishes if no child spans within 3 seconds
• Transactions with no child spans are dropped

// Create child spans inside a tap handler:
func onLoginTapped() {
    let span = SentrySDK.span
    let child = span?.startChild(operation: "loadUserProfile")
    // ... work ...
    child?.finish()
}

// Disable
options.enableUserInteractionTracing = false

File I/O Tracing (NSData)

Platforms: All
Tracks NSData read/write operations as spans.

options.enableFileIOTracing = true   // default

// iOS 18+ / macOS 15+: NSFileManager no longer backed by NSData
// Enable experimental NSFileManager swizzling:
options.enableFileManagerSwizzling = true   // experimental, v9.0.0+

Manual tracing extensions (v8.48.0+) — only create spans when an active transaction exists:

// Data read/write
let data = try Data(contentsOfWithSentryTracing: url)
try data.writeWithSentryTracing(to: url)

// FileManager
let fm = FileManager.default
fm.createFileWithSentryTracing(atPath: path, contents: data)
try fm.moveItemWithSentryTracing(at: src, to: dst)
try fm.copyItemWithSentryTracing(at: src, to: dst)
try fm.removeItemWithSentryTracing(at: url)

Span operations created:

Core Data Tracing

Platforms: All
Instruments NSManagedObjectContext fetch and save operations.

options.enableCoreDataTracing = true   // default

// Disable
options.enableCoreDataTracing = false

Distributed Tracing

Sentry injects two headers into outgoing NSURLSession requests when the host matches tracePropagationTargets:

SentrySDK.start { options in
    options.dsn = "___PUBLIC_DSN___"
    options.tracesSampleRate = 1.0

    // Only propagate to your own backend (default: all requests)
    options.tracePropagationTargets = [
        "api.myapp.com",
        ".*\\.myapp\\.com"   // regex supported
    ]

    // Also add W3C traceparent header (requires sentry-cocoa 9.0.0+)
    options.enablePropagateTraceparent = true
}

enablePropagateTraceparent requires sentry-cocoa 9.0.0+. It is not available in 8.x.

⚠️ Both headers must be included in CORS allowlists and must not be blocked by proxies or firewalls.

Platform Support Matrix

Best Practices

• Start with tracesSampleRate = 1.0 in development; lower to 0.1–0.2 in production
• Use tracesSampler (not tracesSampleRate) for route-specific or user-tier-based sampling
• Use bindToScope: true when starting a transaction so child spans created anywhere in the call stack are automatically linked
• Always finish() spans — unfinished spans are silently dropped
• Use SentryTracedView from the SentrySwiftUI package for SwiftUI screens (UIViewController tracing doesn't apply)
• Call SentrySDK.reportFullyDisplayed() only after your async data has been rendered — not just loaded
• Avoid setting tracePropagationTargets = [".*"] in production if you make requests to third-party services not using Sentry

Troubleshooting