Set Up Profiling

With profiling, Sentry tracks your software's performance by sampling your program's call stack in a variety of environments. This feature collects function-level information about your code and enables you to fine-tune your program's performance. Sentry's profiler captures function calls and their exact locations, aggregates them, and shows you the most common code paths of your program. This highlights areas you could optimize to help increase both the performance of your code and increase user satisfaction, as well as drive down costs.

Enable UI Profiling

To configure profiling, assign a closure to SentryOptions.configureProfiling, setting the desired options on the object passed in as parameter:

import Sentry

SentrySDK.start { options in
    options.dsn = "https://examplePublicKey@o0.ingest.sentry.io/0"
    options.configureProfiling = {
        $0.sessionSampleRate = 1
    }
}

By default, sessionSampleRate is 0, so you'll need to set it to a higher value to receive profile data. sessionSampleRate is evaluated once per user session and applies to any attempt to start a profile until the next user session starts. See user session documentation for more information on user sessions.

See the subsections below to learn about the various ways the profiler can be started and stopped.

Manual Lifecycle

By default, the profiler can only be started and stopped manually with calls to SentrySDK.startProfiler and SentrySDK.stopProfiler. All code that executes on all threads in between those calls will be recorded. The snippets above demonstrate configuring manual profiling mode.

For example, if you wanted to profile everything that happens after starting a network request, and then update a table view with the contents of the response, you could do it like this (assuming you've already started the Sentry SDK with the options shown above):

import Sentry

struct MyModel: Codable {
    // fields...
}
var model: MyModel?
var tableView: UITableView!

@IBAction func updateTable() {
    SentrySDK.startProfiler()
    URLSession.shared.dataTask(with: URLRequest(url: URL(string: "https://my.domain.tld/endpoint")!)) { data, response, error in
        self.model = try! JSONDecoder().decode(MyModel.self, from: data!)
        DispatchQueue.main.async {
            self.tableView.performBatchUpdates {
                // update table view with model
            } completion: { finished in 
                SentrySDK.stopProfiler()
            }
        }
    }
}

This would capture every stacktrace on every thread involved with performing the network request, decoding the response and rebuilding the cells in the table view.

Trace Lifecycle

The profiler can be configured to start when a new root span is started where none already exist, and stopped when there are no root spans remaining. For this mode, you must set the SentryProfileOptions.lifecycle property to SentryProfileLifecycleTrace and ensure some traces will be sampled:

import Sentry

SentrySDK.start { options in
    options.dsn = "https://examplePublicKey@o0.ingest.sentry.io/0"
    options.tracesSampleRate = 1
    options.configureProfiling = {
        $0.sessionSampleRate = 1
        $0.lifecycle = .trace
    }
}

Check out the tracing setup documentation for more detailed information on how to configure sampling for Sentry Tracing.

App Starts

If configured with manual lifecycle, a profile starts on the next app launch, and continues until you call SentrySDK.stopProfiler.

If configured with trace lifecycle, app start profiles are attached to a special performance transaction operation called app.launch and displayed in the product as launch. It is stopped either when SentrySDK.startWithOptions is called, or, if Time to Initial Display (TTID)/Time to Full Display (TTFD) tracking is enabled, when the SDK determines that TTID/TTFD has been reached.

Every time SentrySDK.startWithOptions is called with app start profiling configured, a separate sample decision is generated with sessionSampleRate and stored until the next app launch (as well as tracesSampleRate if trace profile lifecycle is configured). The same sample decision will apply for the remainder of the profile session following that subsequent launch.

Transaction-based Profiling (deprecated)

Configure the sampling rates for traces and profiles to ensure they are nonzero so that some are recorded. The profilesSampleRate setting is relative to the tracesSampleRate setting.

import Sentry

SentrySDK.start { options in
    options.dsn = "https://examplePublicKey@o0.ingest.sentry.io/0"
    options.tracesSampleRate = 1.0 // tracing must be enabled for profiling
    options.profilesSampleRate = 1.0 // see also `profilesSampler` if you need custom sampling logic
}

Launch Profiling (deprecated)

Normally, a profile can only be taken during a trace span after the SDK has been initialized. Now, you can configure the SDK to automatically profile certain app launches.

To set up launch profiling, use the enableAppLaunchProfiling option and configure the sample rates for traces and profiles with SentrySDK.startWithOptions to determine if the subsequent app launch should be automatically profiled. This allows you to gather information on what is going on in your app even before main is called, making it easier to diagnose issues with slow app launches.

If you use SentryOptions.tracesSampler or SentryOptions.profilesSampler, it will be invoked after you call SentrySDK.startWithOptions, with SentryTransactionContext.forNextAppLaunch set to true indicating that it's evaluating a launch profile sampling decision. If instead you simply set SentryOptions.tracesSampleRate and SentryOptions.profilesSampleRate, those numerical rates will be used directly.

Currently, launch profiles are attached to a special performance transaction operation called app.launch and displayed in the product simply as launch.

import Sentry

SentrySDK.start { options in
    options.dsn = "https://examplePublicKey@o0.ingest.sentry.io/0"
    options.tracesSampleRate = 1.0 // tracing must be enabled for profiling
    options.profilesSampleRate = 1.0 // see also `profilesSampler` if you need custom sampling logic
    options.enableAppLaunchProfiling = true
}

Continuous Profiling Beta (deprecated)

The current profiling implementation stops the profiler automatically after 30 seconds (unless you manually stop it earlier). Naturally, this limitation makes it difficult to get full coverage of your app's execution. We now offer an experimental continuous mode, where profiling data is periodically uploaded while running, with no limit to how long the profiler may run.

Previously, profiles only ran in tandem with performance transactions that were started either automatically or manually with SentrySDK.startTransaction. Now, you can start and stop the profiler directly with SentrySDK.startProfiler and SentrySDK.stopProfiler. You can also start a profile at app launch by setting SentryOptions.enableAppLaunchProfiling = true in your call to SentrySDK.startWithOptions.

Continuous profiling mode is enabled by default, requiring no changes to SentryOptions when you start the SDK to opt in. If you had previously set SentryOptions.profilesSampleRate or SentryOptions.profilesSampler to use transaction-based profiling, then remove those lines of code from your configuration.

These new APIs do not offer any sampling functionality—every call to start the profiler will start it, and the same goes for launch profiles if you've configured that. If you are interested in reducing the amount of profiles that run, you must take care to do it at the call sites.

Continuous profiling has implications for your org's billing structure. This feature is only available for subscription plans that enrolled after June 5, 2024.