diff --git a/docs/platforms/apple/common/index.mdx b/docs/platforms/apple/common/index.mdx index 3caf1f19e63c92..fdf98487349c57 100644 --- a/docs/platforms/apple/common/index.mdx +++ b/docs/platforms/apple/common/index.mdx @@ -87,7 +87,7 @@ To capture all errors, initialize the SDK as soon as possible, such as in your ` -```swift {tabTitle:Swift} {"onboardingOptions": {"performance": "13-16", "profiling": "18-28"}} +```swift {tabTitle:Swift} {"onboardingOptions": {"performance": "13-16", "profiling": "17-21"}} import Sentry func application(_ application: UIApplication, @@ -101,27 +101,21 @@ func application(_ application: UIApplication, // For more information, visit: https://docs.sentry.io/platforms/apple/data-management/data-collected/ options.sendDefaultPii = true - // Set tracesSampleRate to 1.0 to capture 100% of transactions for performance monitoring. + // Set tracesSampleRate to 1 to capture 100% of transactions for performance monitoring. // We recommend adjusting this value in production. - options.tracesSampleRate = 1.0 + options.tracesSampleRate = 1 + + options.configureProfiling = { + $0.lifecycle = .trace + $0.sessionSampleRate = 1 + } } - // Manually call startProfiler and stopProfiler to profile any code that runs in between. - SentrySDK.startProfiler() - - // - // ...anything here will be profiled... - // - - // Calls to stopProfiler are optional - if you don't stop the profiler, it will keep profiling - // your application until the process exits, the app goes to the background, or stopProfiling is called. - SentrySDK.stopProfiler() - return true } ``` -```objc {tabTitle:Objective-C} {"onboardingOptions": {"performance": "12-15", "profiling": "17-27"}} +```objc {tabTitle:Objective-C} {"onboardingOptions": {"performance": "12-15", "profiling": "16-20"}} @import Sentry; - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions { @@ -136,25 +130,19 @@ func application(_ application: UIApplication, // Set tracesSampleRate to 1.0 to capture 100% of transactions for performance monitoring. // We recommend adjusting this value in production. - options.tracesSampleRate = @1.0; + options.tracesSampleRate = @1.f; + + options.configureProfiling = ^(SentryProfileOptions *profiling) { + profiling.lifecycle = SentryProfileLifecycleTrace; + profiling.sessionSampleRate = 1.f; + }; }]; - // Manually call startProfiler and stopProfiler to profile any code that runs in between. - [SentrySDK startProfiler]; - - // - // ...anything here will be profiled... - // - - // Calls to stopProfiler are optional - if you don't stop the profiler, it will keep profiling - // your application until the process exits, the app goes to the background, or stopProfiling is called. - [SentrySDK stopProfiler]; - return YES; } ``` -```swift {tabTitle:SwiftUI with App conformer} {"onboardingOptions": {"performance": "13-16", "profiling": "18-28"}} +```swift {tabTitle:SwiftUI with App conformer} {"onboardingOptions": {"performance": "13-16", "profiling": "17-21"}} import Sentry @main @@ -168,21 +156,15 @@ struct SwiftUIApp: App { // For more information, visit: https://docs.sentry.io/platforms/apple/data-management/data-collected/ options.sendDefaultPii = true - // Set tracesSampleRate to 1.0 to capture 100% of transactions for performance monitoring. + // Set tracesSampleRate to 1 to capture 100% of transactions for performance monitoring. // We recommend adjusting this value in production. - options.tracesSampleRate = 1.0 + options.tracesSampleRate = 1 + + options.configureProfiling = { + $0.lifecycle = .trace + $0.sessionSampleRate = 1 + } } - - // Manually call startProfiler and stopProfiler to profile any code that runs in between. - SentrySDK.startProfiler() - - // - // ...anything here will be profiled... - // - - // Calls to stopProfiler are optional - if you don't stop the profiler, it will keep profiling - // your application until the process exits, the app goes to the background, or stopProfiling is called. - SentrySDK.stopProfiler() } } ``` @@ -190,7 +172,7 @@ struct SwiftUIApp: App { -```swift {tabTitle:Swift} {"onboardingOptions": {"performance": "13-16"}} +```swift {tabTitle:Swift} {"onboardingOptions": {"performance": "13-16", "profiling": "17-21"}} import Sentry func application(_ application: UIApplication, @@ -204,16 +186,21 @@ func application(_ application: UIApplication, // For more information, visit: https://docs.sentry.io/platforms/apple/data-management/data-collected/ options.sendDefaultPii = true - // Set tracesSampleRate to 1.0 to capture 100% of transactions for performance monitoring. + // Set tracesSampleRate to 1 to capture 100% of transactions for performance monitoring. // We recommend adjusting this value in production. - options.tracesSampleRate = 1.0 + options.tracesSampleRate = 1 + + options.configureProfiling = { + $0.lifecycle = .trace + $0.sessionSampleRate = 1 + } } return true } ``` -```objc {tabTitle:Objective-C} {"onboardingOptions": {"performance": "12-15"}} +```objc {tabTitle:Objective-C} {"onboardingOptions": {"performance": "12-15", "profiling": "16-20"}} @import Sentry; - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions { @@ -228,14 +215,19 @@ func application(_ application: UIApplication, // Set tracesSampleRate to 1.0 to capture 100% of transactions for performance monitoring. // We recommend adjusting this value in production. - options.tracesSampleRate = @1.0; + options.tracesSampleRate = @1.f; + + options.configureProfiling = ^(SentryProfileOptions *profiling) { + profiling.lifecycle = SentryProfileLifecycleTrace; + profiling.sessionSampleRate = 1.f; + }; }]; return YES; } ``` -```swift {tabTitle:SwiftUI with App conformer} {"onboardingOptions": {"performance": "13-16"}} +```swift {tabTitle:SwiftUI with App conformer} {"onboardingOptions": {"performance": "13-16", "profiling": "17-21"}} import Sentry @main @@ -249,9 +241,14 @@ struct SwiftUIApp: App { // For more information, visit: https://docs.sentry.io/platforms/apple/data-management/data-collected/ options.sendDefaultPii = true - // Set tracesSampleRate to 1.0 to capture 100% of transactions for performance monitoring. + // Set tracesSampleRate to 1 to capture 100% of transactions for performance monitoring. // We recommend adjusting this value in production. - options.tracesSampleRate = 1.0 + options.tracesSampleRate = 1 + + options.configureProfiling = { + $0.lifecycle = .trace + $0.sessionSampleRate = 1 + } } } } diff --git a/docs/platforms/apple/common/profiling/index.mdx b/docs/platforms/apple/common/profiling/index.mdx index 2b7a080b6a82f3..06434031cd4662 100644 --- a/docs/platforms/apple/common/profiling/index.mdx +++ b/docs/platforms/apple/common/profiling/index.mdx @@ -1,6 +1,6 @@ --- title: Set Up Profiling -description: "Learn how to enable profiling in your app if it is not already set up." +description: "Learn how to enable profiling in your app." sidebar_order: 5000 supported: - apple @@ -15,17 +15,24 @@ notSupported: -## Enable Tracing +## Enable UI Profiling -Profiling depends on Sentry’s Tracing product being enabled beforehand. To enable tracing in the SDK: + + +UI Profiling was introduced in SDK version 8.49.0. All prior profiling API are deprecated and will be removed in a future major version of the SDK. + + +To configure profiling, assign a closure to `SentryOptions.configureProfiling`, setting the desired options on the object passed in as parameter: ```swift {tabTitle:Swift} import Sentry SentrySDK.start { options in options.dsn = "___PUBLIC_DSN___" - options.tracesSampleRate = 1.0 + options.configureProfiling = { + $0.sessionSampleRate = 1 + } } ``` @@ -34,31 +41,62 @@ SentrySDK.start { options in [SentrySDK startWithConfigureOptions:^(SentryOptions *options) { options.dsn = @"___PUBLIC_DSN___"; - options.tracesSampleRate = @1.0; + options.configureProfiling = ^(SentryProfileOptions *profiling) { + profiling.sessionSampleRate = 1.f; + }; }]; ``` -Check out the tracing setup documentation for more detailed information on how to configure sampling. Setting the sample rate to 1.0 means all transactions will be captured. +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. -By default, some transactions will be created automatically for common operations like loading a view controller/activity and app startup. +See the subsections below to learn about the various ways the profiler can be started and stopped. -## Enable Profiling +### 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. -iOS profiling is available starting in SDK version `8.12.0`. +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): - +```swift {tabTitle:Swift} +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: ```swift {tabTitle:Swift} import Sentry SentrySDK.start { options in options.dsn = "___PUBLIC_DSN___" - 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 // experimental new feature to start profiling in the pre-main launch phase + options.tracesSampleRate = 1 + options.configureProfiling = { + $0.sessionSampleRate = 1 + $0.lifecycle = .trace + } } ``` @@ -67,27 +105,73 @@ SentrySDK.start { options in [SentrySDK startWithConfigureOptions:^(SentryOptions *options) { options.dsn = @"___PUBLIC_DSN___"; - 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 = YES; // experimental new feature to start profiling in the pre-main launch phase + options.tracesSampleRate = @1.f; + options.configureProfiling = ^(SentryProfileOptions *profiling) { + profiling.sessionSampleRate = 1.f; + profiling.lifecycle = SentryProfileLifecycleTrace; + }; }]; ``` -The setting is _relative_ to the setting. +The `sessionSampleRate` for profiles is _relative_ to the `tracesSampleRate`: if `tracesSampleRate` and `sessionSampleRate` are both `0.5`, then on average 25% of attempts to start the profiler will result in actual data collection. -## Enable Launch Profiling +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) + + + +Profiling configuration, explained below, was originally introduced in SDK version `8.12.0`. It is now deprecated in favor of UI Profiling, introduced in 8.49.0. + + -This feature is experimental and may have bugs. +Transaction-based Profiling depends on Sentry’s Tracing product being enabled beforehand. Check out the tracing setup documentation for detailed information on how to configure sampling. -_(New in version 8.21.0)_ +Configure the sampling rates for traces and profiles to ensure they are nonzero so that some are recorded. The setting is _relative_ to the setting. + +```swift {tabTitle:Swift} +import Sentry + +SentrySDK.start { options in + options.dsn = "___PUBLIC_DSN___" + options.tracesSampleRate = 1.0 // tracing must be enabled for profiling + options.profilesSampleRate = 1.0 // see also `profilesSampler` if you need custom sampling logic +} +``` + +```objc {tabTitle:Objective-C} +@import Sentry; + +[SentrySDK startWithConfigureOptions:^(SentryOptions *options) { + options.dsn = @"___PUBLIC_DSN___"; + 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) + + + +Launch profiling configuration, explained below, was originally introduced in SDK version 8.21.0. It is now deprecated in favor of UI Profiling, released in 8.49.0. + + 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. @@ -97,16 +181,36 @@ If you use `SentryOptions.tracesSampler` or `SentryOptions.profilesSampler`, it Currently, launch profiles are attached to a special performance transaction operation called `app.launch` and displayed in the product simply as `launch`. -## Continuous Profiling +```swift {tabTitle:Swift} +import Sentry + +SentrySDK.start { options in + options.dsn = "___PUBLIC_DSN___" + 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 +} +``` + +```objc {tabTitle:Objective-C} +@import Sentry; + +[SentrySDK startWithConfigureOptions:^(SentryOptions *options) { + options.dsn = @"___PUBLIC_DSN___"; + 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 = YES; +}]; +``` + +## Continuous Profiling Beta (deprecated) -This feature is experimental and may have bugs. +Continuous Profiling Beta, explained below, was originally introduced in SDK version 8.36.0. It is now deprecated in favor of UI Profiling, released in 8.49.0. -_(New in version 8.36.0)_ - 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`. diff --git a/docs/platforms/apple/index.mdx b/docs/platforms/apple/index.mdx index 262d871773ba91..87e696cd5bc851 100644 --- a/docs/platforms/apple/index.mdx +++ b/docs/platforms/apple/index.mdx @@ -12,6 +12,6 @@ keywords: - swift --- -Sentry supports the Apple platform via the `sentry-cocoa` SDK. Select your platform to get started: +Sentry supports Apple platforms via the [`sentry-cocoa`](https://github.com/getsentry/sentry-cocoa) SDK. Select your platform to get started: