Skip to content

feat: update docs for profiling v2 #13197

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
kahest merged 9 commits into from
Apr 9, 2025
Merged

feat: update docs for profiling v2 #13197

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
55abee0
feat(profiling[cocoa]): update docs for profiling v2
armcknight Apr 1, 2025
05c88ad
add example of manual profiling
armcknight Apr 1, 2025
d9203cf
improve table view example
armcknight Apr 4, 2025
5f09992
Update docs/platforms/apple/common/profiling/index.mdx
armcknight Apr 4, 2025
02854da
Update docs/platforms/apple/common/profiling/index.mdx
armcknight Apr 4, 2025
883dd02
Update docs/platforms/apple/common/profiling/index.mdx
armcknight Apr 4, 2025
d0f0956
Apply suggestions from code review
armcknight Apr 4, 2025
86cbf85
pr feedback
armcknight Apr 4, 2025
cdcc6c0
more feedback
armcknight Apr 4, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
95 changes: 46 additions & 49 deletions docs/platforms/apple/common/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -87,7 +87,7 @@ To capture all errors, initialize the SDK as soon as possible, such as in your `

<PlatformSection notSupported={["apple.tvos", "apple.watchos", "apple.visionos"]}>

```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,
Expand All @@ -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 {
Expand All @@ -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
Expand All @@ -168,29 +156,23 @@ 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()
}
}
```
</PlatformSection>

<PlatformSection notSupported={["apple.ios", "apple.macos"]}>

```swift {tabTitle:Swift} {"onboardingOptions": {"performance": "13-16"}}
```swift {tabTitle:Swift} {"onboardingOptions": {"performance": "13-16", "profiling": "17-21"}}
import Sentry

func application(_ application: UIApplication,
Expand All @@ -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 {
Expand All @@ -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
Expand All @@ -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
}
}
}
}
Expand Down
149 changes: 125 additions & 24 deletions docs/platforms/apple/common/profiling/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,17 +15,24 @@ notSupported:
<PlatformContent includePath="profiling/index/preface" />
<PlatformContent includePath="profiling/index/why-profiling" />

## Enable Tracing
## Enable Profiling

<Alert>

Profiling depends on Sentry’s Tracing product being enabled beforehand. To enable tracing in the SDK:
Profiling V2 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.

</Alert>

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
}
}
```

Expand All @@ -34,31 +41,59 @@ 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 <PlatformLink to="/tracing/">tracing setup documentation</PlatformLink> 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 <PlatformLink to="/configuration/releases/#sessions">user session documentation</PlatformLink> 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

<Alert>
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 configurations shown 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 updating a table view with the contents of the response, you could do is as follows (assuming you've already started the Sentry SDK with the options as shown above):

</Alert>
```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.reloadData()
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
}
}
```

Expand All @@ -67,27 +102,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;
};
}];
```

<Alert>

The <PlatformIdentifier name="profiles-sample-rate" /> setting is _relative_ to the <PlatformIdentifier name="traces-sample-rate" /> setting.
The `sessionSampleRate` for profiles is undersampled with respect to the `tracesSampleRate`.

</Alert>

## Enable Launch Profiling
Check out the <PlatformLink to="/tracing/">tracing setup documentation</PlatformLink> for more detailed information on how to configure sampling for Sentry Tracing.

### App Starts

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

If configured with trace lifecycle, then app start profiles are attached to a special performance transaction operation called `app.launch` and displayed in the product simply as `launch`, which is stopped either when `SentrySDK.startWithOptions` is called, or, if <PlatformLink to="/tracing/instrumentation/automatic-instrumentation/#time-to-initial-display">TTID</PlatformLink>/<PlatformLink to="/tracing/instrumentation/automatic-instrumentation/#time-to-full-display">TTFD</PlatformLink> 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 Profiling (deprecated)

<Alert>

Profiling configuration as explained below was originally introduced in SDK version `8.12.0` and is deprecated in favor of profiling V2 introduced in 8.49.0, explained at the beginning of this section.

</Alert>

<Alert>

This feature is experimental and may have bugs.
Profiling depends on Sentry’s Tracing product being enabled beforehand. Check out the <PlatformLink to="/tracing/">tracing setup documentation</PlatformLink> for more detailed information on how to configure sampling.

</Alert>

_(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 <PlatformIdentifier name="profiles-sample-rate" /> setting is _relative_ to the <PlatformIdentifier name="traces-sample-rate" /> 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)

<Alert>

Launch profiling configuration as explained below was originally introduced in SDK version 8.21.0 and is deprecated in favor of profiling V2 configuration released in 8.49.0, explained at the beginning of this section.

</Alert>

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.

Expand All @@ -97,16 +178,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 (deprecated)

<Alert>

This feature is experimental and may have bugs.
Continuous profiling as explained below was originally introduced in SDK version 8.36.0 and is deprecated in favor of profiling V2 configuration released in 8.49.0, explained at the beginning of this section.

</Alert>

_(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`.
Expand Down
Loading