Automatic Instrumentation

UIViewController Tracking

This feature is available for iOS, tvOS, and Mac Catalyst, is enabled by default, and works for UIViewControllers.

UIViewController Tracking is enabled by default once you set up performance monitoring. This feature captures transactions when your app loads an in-app UIViewController. However, the SDK doesn't capture transactions for UIViewControllers of third-party libraries or SwiftUI. The SDK sets the transaction name to the name of the ViewController, including the module — for example, Your_App.MainViewController — and the transaction operation to ui.load.

The SDK creates spans to provide insight into the time consumed by each of the methods shown in the screenshot below. Due to implementation limitations, the SDK only adds a span for loadView if the instrumented view controller implements it. The SDK adds spans for all other methods, whether you implement them in your view controller or not.

`UIViewController` Transaction

To disable the UIViewController Tracking:

Copied
import Sentry

SentrySDK.start { options in
    options.dsn = "https://examplePublicKey@o0.ingest.sentry.io/0"
    options.enableUIViewControllerTracking = false
}

App Start Tracking

This feature is available for iOS, tvOS, and Mac Catalyst.

App Start Tracking is enabled by default once you set up performance monitoring. This feature provides insight into how long your application takes to launch. It adds spans for different phases, from the application launch to the first auto-generated UI transaction. To enable this feature, enable AutoUIPerformanceTracking.

The SDK differentiates between a cold and a warm start, but doesn't track hot starts/resumes.

  • Cold start: App launched for the first time, after a reboot or update. The app is not in memory and no process exists.
  • Warm start: App launched at least once, is partially in memory, and no process exists.

The SDK uses the process start time as the beginning of the app start and the UIWindowDidBecomeVisibleNotification as the end. The SDK creates the following spans:

App Start Transaction

Cold and warm start are Mobile Vitals, which you can learn about in the full documentation.

Prewarmed App Start Tracking

Starting with iOS 15, the system might prewarm your app by creating the process before the user opens it. In these cases, we won’t be able to reliably measure the app start. However, with sentry-cocoa 7.31.0, we’ve introduced an enablePreWarmedAppStartTracking feature (still in its experimental phase), which allows us to collect prewarmed app starts.

Once enabled, the SDK drops the first app start span if prewarming pauses. This approach shortens the app start duration, but it accurately represents the span of time from when a user clicks the app icon to when the app is responsive. With this feature, the SDK differentiates between four different app start types:

  • Non-prewarmed cold start (See cold start definition above.)
  • Non-prewarmed warm start (See warm start definition above.)
  • Prewarmed cold start
  • Prewarmed warm start

You can filter for different app start types in Discover with app_start_type:cold.prewarmed, app_start_type:warm.prewarmed, app_start_type:cold, and app_start_type:warm.

To enable prewarmed app start tracking:

Copied
import Sentry

SentrySDK.start { options in
    options.dsn = "https://examplePublicKey@o0.ingest.sentry.io/0"
    options.enablePreWarmedAppStartTracking = true
}

Slow and Frozen Frames

This feature is available for iOS, tvOS, and Mac Catalyst.

Slow and Frozen Frames are enabled by default once you set up performance monitoring. Unresponsive UI and animation hitches annoy users and degrade the user experience. Two measurements to track these types of experiences are slow frames and frozen frames. If you want your app to run smoothly, you should try to avoid both. The SDK adds these two measurements for the transactions you capture.

The detail view of the transaction displays the slow, frozen, and total frames:

Slow and Frozen Frames

Slow and frozen frames are Mobile Vitals, which you can learn about in the full documentation.

Network Tracking

Network Tracking is enabled by default once you set up performance monitoring. The Sentry SDK adds spans for outgoing HTTP requests to ongoing transactions bound to the Scope. Currently, the SDK supports requests with NSURLSession, but not the legacy NSURLConnection yet. The SDK attaches auto-generated transactions automatically to the Scope if there is no other transaction bound. When starting a transaction, you can use bindToScope to indicate whether the SDK should bind the new transaction to the Scope or not.

To disable the HTTP instrumentation:

Copied
import Sentry

SentrySDK.start { options in
    options.dsn = "https://examplePublicKey@o0.ingest.sentry.io/0"
    options.enableNetworkTracking = false
}

File I/O Tracking

The Sentry SDK adds spans for file I/O operations to ongoing transactions bound to the scope. Currently, the SDK supports operations with NSData, but many other APIs like NSFileManager, NSString and NSBundle uses NSData. This feature is experimental and is disabled by default.

To enable file I/O tracking:

Copied
import Sentry

SentrySDK.start { options in
    options.dsn = "https://examplePublicKey@o0.ingest.sentry.io/0"
    options.enableFileIOTracking = true
}

Core Data Tracking

The Sentry SDK adds spans for Core Data operations to ongoing transactions bound to the scope. Currently, the SDK supports fetch and save operations with NSManagedObjectContext. To enable core data tracking:

Copied
import Sentry

SentrySDK.start { options in
    options.dsn = "https://examplePublicKey@o0.ingest.sentry.io/0"
    options.enableCoreDataTracking = true
}

User Interaction Tracing

User interaction

tracingThe process of logging the events that took place during a request, often across multiple services.
, once enabled, captures transactions for clicks. User interaction tracing is disabled by default, but you can enable it by setting:

Copied
import Sentry

SentrySDK.start { options in
    options.dsn = "https://examplePublicKey@o0.ingest.sentry.io/0"
    options.enableUserInteractionTracing = true
}

The SDK composes the transaction name out of the host UIViewController and the method that the UIView is calling; for example, YourApp_LoginUIViewController.loginButton. The SDK sets the transaction operation to ui.action. If the SDK detects the interaction's origin was a click, it adds click as a suffix to the operation. The transaction finishes automatically after it reaches the specified idleTimeout and all of its child spans are finished. The idleTimeoout defaults to 3000 milliseconds (three seconds).

The SDK binds user interaction transactions to the Scope automatically if there's no other transaction set. Because of that, you can create spans using manual instrumentation, and those spans will be automatically associated with the running UI transaction.

Copied
import Sentry

func loadUserDataOnClick() {
    let span = SentrySDK.span
    let innerSpan = span?.startChild(operation: "loadUserData")
    // omitted code
    innerSpan?.finish()
}

When the user interaction transaction is not finished yet, but the user makes a new interaction, or the SDK starts a new UIViewController transaction, the SDK automatically finishes the previous user interaction transaction. This is because only one transaction can be bound to the scope at a time. However, if the same view has been interacted with (for example, a UIButton was clicked again within the idleTimeout window), the idle timer will be reset and the transaction duration will be extended with the idleTimeout value.

Opt Out

You can opt out of all automatic instrumentations using the options:

Copied
import Sentry

SentrySDK.start { options in
    options.dsn = "https://examplePublicKey@o0.ingest.sentry.io/0"
    options.enableAutoPerformanceTracking = false
}
Help improve this content
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) to suggesting an update ("yeah, this would be better").