Skip to content

Commit 3afdf06

Browse files
philipphofmannphilprime
philipphofmann
and
philprime
authored
feat(apple): Migration Guide for V9 (#15649)
Add the migration guide for major version v9. We still have to wait for Cocoa V9 to be shipped on Monday Dec 1st to merge this PR. Co-authored-by: Philip Niedertscheider <phil.niedertscheider@sentry.io>
1 parent 90c86fd commit 3afdf06

File tree

14 files changed

+287
-42
lines changed

14 files changed

+287
-42
lines changed

‎docs/platforms/apple/common/configuration/app-hangs.mdx‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -134,11 +134,11 @@ SentrySDK.resumeAppHangTracking()
134134

135135
### App Hangs V2
136136

137-
As of version 8.50.0, you can enable AppHangsV2, which is available on iOS and tvOS. The main difference is that AppHangsV2 differentiates between fully-blocking and non-fully-blocking app hangs, which you might choose to ignore, and measures the duration of app hangs. A fully-blocking app hang is when the main thread is stuck completely, and the app can't render a single frame. A non-fully-blocking app hang is when the app appears stuck to the user, but can still render a few frames. Fully-blocking app hangs are more actionable because the stacktrace shows the exact blocking location on the main thread. Non-fully-blocking app hangs can have a stacktrace that doesn't highlight the exact blocking location, since the main thread isn't completely blocked.
137+
As of version 8.50.0, you can enable AppHangsV2, which is available on iOS and tvOS. **Starting with version 9.0.0, App Hangs V2 is enabled by default.** The main difference is that AppHangsV2 differentiates between fully-blocking and non-fully-blocking app hangs, which you might choose to ignore, and measures the duration of app hangs. A fully-blocking app hang is when the main thread is stuck completely, and the app can't render a single frame. A non-fully-blocking app hang is when the app appears stuck to the user, but can still render a few frames. Fully-blocking app hangs are more actionable because the stacktrace shows the exact blocking location on the main thread. Non-fully-blocking app hangs can have a stacktrace that doesn't highlight the exact blocking location, since the main thread isn't completely blocked.
138138

139139
The SDK sets the `exception.type` to `App Hang Fully Blocked` or `App Hang Non Fully Blocked`, so you can filter for App Hangs via `error.type` in Sentry.
140140

141-
To enable the feature:
141+
To enable the feature in version 8.50.0 and later (enabled by default starting with 9.0.0):
142142

143143
```swift {tabTitle:Swift}
144144
import Sentry
@@ -190,7 +190,7 @@ SentrySDK.start { options in
190190
191191
<Alert level="info">
192192
193-
The SDK supports App Hang Rate calculation starting with version 8.50.0. Additionally, you have to enable App Hangs V2 via `options.enableAppHangTrackingV2 = true` in your SDK configuration.
193+
The SDK supports App Hang Rate calculation starting with version 8.50.0. For versions 8.50.0 to 8.x, you have to enable App Hangs V2 via `options.enableAppHangTrackingV2 = true` in your SDK configuration. **Starting with version 9.0.0, App Hangs V2 is enabled by default.**
194194
195195
</Alert>
196196

‎docs/platforms/apple/common/configuration/options.mdx‎

Lines changed: 9 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -129,7 +129,9 @@ Sentry differentiates stack frames that are directly related to your application
129129

130130
</SdkOption>
131131

132-
<SdkOption name="inAppExclude" type="array">
132+
<SdkOption name="inAppExclude" type="array" removedSince="9.0.0">
133+
134+
**Removed in version 9.0.0** - This option had no effect and was removed.
133135

134136
A list of string prefixes of module names that do not belong to the app, but rather to third-party packages. Modules considered not part of the app will be hidden from stack traces by default.
135137

@@ -212,13 +214,17 @@ Once enabled, this feature automatically captures HTTP client errors, like bad r
212214

213215
For many platform SDKs integrations can be configured alongside it. On some platforms that happen as part of the `init()` call, in some others, different patterns apply.
214216

215-
<SdkOption name="integrations" type="array" />
217+
<SdkOption name="integrations" type="array" removedSince="9.0.0" />
218+
219+
**Removed in version 9.0.0** - Integrations are now automatically managed by the SDK. Use specific configuration options to control SDK features instead.
216220

217221
In some SDKs, the integrations are configured through this parameter on library initialization. For more information, please see our documentation for a specific integration.
218222

219223
<PlatformSection notSupported={["java", "dart"]}>
220224

221-
<SdkOption name="defaultIntegrations" type="bool" />
225+
<SdkOption name="defaultIntegrations" type="bool" removedSince="9.0.0" />
226+
227+
**Removed in version 9.0.0** - Integrations are now automatically managed by the SDK.
222228

223229
This can be used to disable integrations that are added by default. When set to `false`, no default integrations are added.
224230

‎docs/platforms/apple/common/enriching-events/attachments/index.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -89,7 +89,7 @@ Alternately, attachments also appear in the _Attachments_ tab on the **Issue Det
8989

9090
The maximum size for each attachment is set on `SentryOptions.maxAttachmentSize`.
9191

92-
The scale is bytes and the default is `20 MiB`. Please also check the
92+
The scale is bytes and the default is `20 MiB` for versions prior to 9.0.0, and `200 MiB` starting with version 9.0.0. Please also check the
9393
[maximum attachment size of Relay](/product/relay/options/)
9494
to make sure your attachments don't get discarded there.
9595

‎docs/platforms/apple/common/install/carthage.mdx‎

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,17 @@
11
---
2-
title: Carthage
2+
title: Carthage (Deprecated)
33
description: "Learn about integrating Sentry into your Xcode project using Carthage."
4+
sidebar_order: 8000
45
---
56

7+
<Alert level="warning" title="Deprecated">
8+
We dropped official support for Carthage in v9. If you're using Carthage, please migrate to <PlatformLink to="/install/swift-package-manager/">Swift Package Manager (SPM)</PlatformLink> or <PlatformLink to="/install/cocoapods/">CocoaPods</PlatformLink>.
9+
</Alert>
10+
611
To integrate Sentry into your Xcode project using Carthage, specify it in your _Cartfile_:
712

813
```ruby
9-
github "getsentry/sentry-cocoa" "{{@inject packages.version('sentry.cocoa') }}"
14+
github "getsentry/sentry-cocoa" "8.57.3"
1015
```
1116

1217
Run `carthage update` to download the framework and drag the built _Sentry.xcframework_ into your Xcode project. We also provide a pre-built version for every release, which can be downloaded at [releases on GitHub](https://github.com/getsentry/sentry-cocoa/releases).

‎docs/platforms/apple/common/install/cocoapods.mdx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
---
22
title: Cocoapods
33
description: "Learn about installing the Sentry SDK with CocoaPods."
4+
sidebar_order: 2000
45
---
56

67
To integrate Sentry into your Xcode project using CocoaPods, specify it in your _Podfile_:

‎docs/platforms/apple/common/install/manual-install.mdx‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
---
2-
title: Manual Install
2+
title: Manual Install
33
description: "Integrate Sentry into your Xcode project by using our pre-compiled frameworks."
4+
sidebar_order: 3000
45
---
56

67
To integrate Sentry into your Xcode project, follow these steps:
@@ -16,4 +17,4 @@ To integrate Sentry into your Xcode project, follow these steps:
1617
### Usage Guidelines:
1718

1819
• Use `Sentry-Dynamic`, `Sentry`, or `Sentry-WithoutUIKitOrAppKit` independently. Only one of these should be included in your project at a time.
19-
• If you're using `SentrySwiftUI`, it must be combined with `Sentry-Dynamic`.
20+
• If you're using `SentrySwiftUI`, it must be combined with `Sentry-Dynamic`.

‎docs/platforms/apple/common/install/swift-package-manager.mdx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
---
22
title: Swift Package Manager (SPM)
33
description: "Integrate Sentry into your Xcode project using Swift Package Manager (SPM)."
4+
sidebar_order: 1000
45
---
56

67
To integrate Sentry into your Xcode project using Swift Package Manager (SPM), open your App in Xcode and open **File > Add Packages**. Then add the SDK by entering the git repo url in the top right search field:

‎docs/platforms/apple/common/integrations/default.mdx‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -37,7 +37,9 @@ This integration tracks watchdog terminations based on heuristics. This feature
3737

3838
## Disable an Integration
3939

40-
This example removes the default-enabled integration for adding breadcrumbs to the event:
40+
**Note:** The `integrations` property and `defaultIntegrations()` method were removed in version 9.0.0. Integrations are now automatically managed by the SDK and cannot be disabled individually. If you need to disable specific functionality, use the corresponding configuration options instead (e.g., `enableAutoBreadcrumbTracking`).
41+
42+
For versions prior to 9.0.0, this example shows how to remove the default-enabled integration for adding breadcrumbs to the event:
4143

4244
```swift {tabTitle:Swift}
4345
import Sentry

‎docs/platforms/apple/common/migration/index.mdx‎

Lines changed: 129 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,135 @@ title: Migration Guide
33
sidebar_order: 8000
44
---
55

6-
To upgrade from version 4.x of the SDK to version 8.x of the SDK, you must first migrate from 4.x to 5.x, then 5.x to 6.x, then 6.x to 7.x, and finally from 7.x to 8.x.
6+
To upgrade from version 4.x of the SDK to version 9.x of the SDK, you must first migrate from 4.x to 5.x, then 5.x to 6.x, then 6.x to 7.x, 7.x to 8.x, and finally from 8.x to 9.x.
7+
8+
## Migrating From 8.x to 9.x
9+
10+
Migrating to 9.x from 8.x includes several breaking changes. We provide this guide to help you update your SDK.
11+
12+
### Changes to Minimum OS Versions and Xcode
13+
14+
We bumped the minimum supported OS versions to:
15+
- **iOS**: 15.0 (previously 11.0)
16+
- **macOS**: 10.14 (previously 10.13)
17+
- **tvOS**: 15.0 (previously 11.0)
18+
- **visionOS**: 1.0 (unchanged)
19+
- **watchOS**: 8.0 (previously 4.0)
20+
21+
We now build the precompiled XCFramework with **Xcode 16**. To submit to the App Store, Apple now requires Xcode 16. If you need a precompiled XCFramework built with Xcode 15, continue using Sentry SDK 8.x.x.
22+
23+
Additionally, the Package.swift sets `swift-tools-version` to 6.0.
24+
25+
### Carthage Support Dropped
26+
27+
We dropped official support for Carthage in v9. If you're using Carthage, please migrate to <PlatformLink to="/install/swift-package-manager/">Swift Package Manager (SPM)</PlatformLink> or <PlatformLink to="/install/cocoapods/">CocoaPods</PlatformLink>.
28+
29+
### Features Enabled by Default
30+
31+
We now enabled the following features by default:
32+
33+
- **Performance V2 is enabled by default**: The app start duration now finishes when the first frame is drawn instead of when the OS posts the `UIWindowDidBecomeVisibleNotification`. We removed the `enablePerformanceV2` option.
34+
- **Pre-warmed app start tracking**: The SDK now collects pre-warmed app starts by default via `enablePreWarmedAppStartTracing`.
35+
- <PlatformLink to="/configuration/app-hangs/#app-hangs-v2">App hang tracking V2</PlatformLink>: This is now the default and we removed the option to enable/disable it.
36+
37+
### Disable App Hang Tracking for Extensions
38+
39+
We now automatically disable app hang tracking for: Widgets, Live Activities, Action Extensions, (Siri) Intent Extensions, Share Extensions. These components run in separate processes or sandboxes with different execution characteristics, which can cause false positive app hang reports.
40+
41+
### Structured Logging
42+
43+
We moved structured logging out of experimental and made it part of the stable API. The `enableLogs` option moved from `options.experimental.enableLogs` to `options.enableLogs`. We added log APIs to `Hub` and `Client`, and logs now include a `sentry.replay_id` attribute.
44+
45+
**Migration required:** Update your code from `options.experimental.enableLogs = true` to `options.enableLogs = true`. Logging is not enabled by default; you must explicitly set this option.
46+
47+
#### HTTP Client Errors
48+
49+
HTTP client errors now mark sessions as errored. This provides better visibility into failed network requests in your release health data.
50+
51+
### Profiling Changes
52+
53+
We removed all deprecated profiling APIs in version [9.0.0](https://github.com/getsentry/sentry-cocoa/releases/tag/9.0.0). The only supported profiling method is now <PlatformLink to="/profiling/#enable-ui-profiling">UI Profiling</PlatformLink> (also known as continuous V2 profiling), which was introduced in [version 8.49.0](https://github.com/getsentry/sentry-cocoa/releases/tag/8.49.0).
54+
55+
**Removed deprecated profiling options from `SentryOptions`:**
56+
- `profilesSampleRate` - used for transaction-based profiling (deprecated)
57+
- `profilesSampler` - used for transaction-based profiling (deprecated)
58+
- `enableAppLaunchProfiling` - used for launch profiling (deprecated)
59+
60+
**Migration to UI Profiling:**
61+
62+
If you were using any of the deprecated profiling options, you need to migrate to UI Profiling. Configure profiling by assigning a closure to `SentryOptions.configureProfiling`:
63+
64+
```swift
65+
import Sentry
66+
67+
SentrySDK.start { options in
68+
options.dsn = "___PUBLIC_DSN___"
69+
options.configureProfiling = {
70+
$0.sessionSampleRate = 1
71+
$0.lifecycle = .manual // or .trace for trace-based lifecycle
72+
}
73+
}
74+
```
75+
76+
For more information, see the <PlatformLink to="/profiling/#enable-ui-profiling">UI Profiling documentation</PlatformLink>.
77+
78+
### Breaking Changes
79+
80+
#### Option Changes
81+
82+
- `enableFileManagerSwizzling` is now a top-level non-experimental option and remains disabled by default.
83+
- `enableDataSwizzling` is now a top-level option and is enabled by default.
84+
- `enableLogs` is now a top-level non-experimental option and remains disabled by default (you must set it to `true` to enable logging).
85+
- We increased the maximum attachment size to 200MB (previously 20MB)
86+
- We removed the following methods and properties:
87+
- `inAppExclude` (it had no effect)
88+
- `integrations`
89+
- `defaultIntegrations()`
90+
- `enableTracing` (use `tracesSampleRate` or `tracesSampler` instead)
91+
- `getStoreEndpoint()`
92+
- `enablePerformanceV2` the behavior of this option is now enabled by default.
93+
94+
#### Behavioral Breaking Changes
95+
96+
- The default trace context status is now `ok` instead of `undefined`.
97+
- The `function` property on `SentryFrame` now defaults to `nil` instead of `"<redacted>"`
98+
- The `value` and `type` properties on `SentryException` are now nullable; when `NSException` has no reason, `type` is set to `nil`
99+
- We changed the type of the `http.response.status_code` attribute for spans to int
100+
101+
#### Renamed APIs
102+
103+
- We renamed `SentryStructuredLogLevel` to `SentryLogLevel`
104+
- We renamed `SentryStructuredLogAttribute` to `SentryLogAttribute`
105+
106+
#### Removed APIs
107+
108+
- We removed the `segment` property from `SentryTraceContext`, `SentryUser`, and `SentryBaggage`
109+
- We removed the initializers from `SentryTraceContext`
110+
- We removed `SentryDsn.getHash()`
111+
- We removed `SentryFrame.instruction`
112+
113+
We removed the following deprecated APIs:
114+
115+
- `SentrySpan.setExtraValue(_:forKey:)`
116+
- User feedback API (use the new <PlatformLink to="/user-feedback/">feedback API</PlatformLink> instead)
117+
- `Scope.useSpan()` (use `Scope.span` instead)
118+
- `SentryDebugMeta.uuid` (use `debugID` instead)
119+
- `SentryDebugMeta.name` (use `codeFile` instead)
120+
121+
We made the following classes and APIs private:
122+
123+
- `SentryEventDecoder` and `SentryEventDecodable`
124+
- `SentryEnvelopeItemHeader`
125+
- `SentryIntegrationProtocol`
126+
- `SentrySession`
127+
- `SentrySDKInfo`
128+
- `SentryDebugImageProvider`
129+
130+
#### Other breaking changes
131+
132+
- We made the following classes `final`: `PreviewRedactOptions`, `SentryProfileOptions`, `SentryRedactViewHelper`, `SentryViewScreenshotOptions`, `SentryReplayOptions`, `SentryUserFeedbackConfiguration`, `SentryUserFeedbackFormConfiguration`, `SentryUserFeedbackThemeConfiguration`, `SentryUserFeedbackWidgetConfiguration`, `SentryFeedback`, and `SentryExperimentalOptions`
133+
134+
For a complete list of changes, see the [Changelog of version 9.0.0](https://github.com/getsentry/sentry-cocoa/releases/tag/9.0.0)
7135

8136
## Migrating From 7.x to 8.x
9137

‎docs/platforms/apple/common/profiling/index.mdx‎

Lines changed: 10 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@ notSupported:
2020

2121
<Alert>
2222

23-
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.
23+
UI Profiling was introduced in SDK version [8.49.0](https://github.com/getsentry/sentry-cocoa/releases/tag/8.49.0). All prior profiling APIs were removed in version [9.0.0](https://github.com/getsentry/sentry-cocoa/releases/tag/9.0.0).
2424

2525
</Alert>
2626

@@ -48,7 +48,7 @@ SentrySDK.start { options in
4848
}];
4949
```
5050
51-
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.
51+
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.
5252
5353
See the subsections below to learn about the various ways the profiler can be started and stopped.
5454
@@ -74,7 +74,7 @@ var tableView: UITableView!
7474
DispatchQueue.main.async {
7575
self.tableView.performBatchUpdates {
7676
// update table view with model
77-
} completion: { finished in
77+
} completion: { finished in
7878
SentrySDK.stopProfiler()
7979
}
8080
}
@@ -124,7 +124,7 @@ Check out the <PlatformLink to="/tracing/">tracing setup documentation</Platform
124124
125125
### App Starts
126126
127-
If configured with manual lifecycle, a profile starts on the next app launch, and continues until you call `SentrySDK.stopProfiler`.
127+
If configured with manual lifecycle, a profile starts on the next app launch, and continues until you call `SentrySDK.stopProfiler`.
128128
129129
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 <PlatformLink to="/tracing/instrumentation/automatic-instrumentation/#time-to-initial-display">Time to Initial Display (TTID)</PlatformLink>/<PlatformLink to="/tracing/instrumentation/automatic-instrumentation/#time-to-full-display">Time to Full Display (TTFD)</PlatformLink> tracking is enabled, when the SDK determines that TTID/TTFD has been reached.
130130
@@ -136,11 +136,11 @@ The SDK must have been started with a call to `SentrySDK.startWithOptions` in or
136136
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.
137137
</Alert>
138138
139-
## Transaction-based Profiling (deprecated)
139+
## Transaction-based Profiling (removed in 9.0.0)
140140
141141
<Alert>
142142
143-
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.
143+
Transaction-based profiling configuration, explained below, was originally introduced in SDK version [8.12.0](https://github.com/getsentry/sentry-cocoa/releases/tag/8.12.0) and was removed in version [9.0.0](https://github.com/getsentry/sentry-cocoa/releases/tag/9.0.0). Use <PlatformLink to="/profiling/#enable-ui-profiling">UI Profiling</PlatformLink> instead, which was introduced in version [8.49.0](https://github.com/getsentry/sentry-cocoa/releases/tag/8.49.0).
144144
145145
</Alert>
146146
@@ -172,11 +172,11 @@ SentrySDK.start { options in
172172
}];
173173
```
174174
175-
## Launch Profiling (deprecated)
175+
## Launch Profiling (removed in 9.0.0)
176176
177177
<Alert>
178178
179-
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.
179+
Launch profiling configuration, explained below, was originally introduced in SDK version [8.21.0](https://github.com/getsentry/sentry-cocoa/releases/tag/8.21.0) and was removed in version [9.0.0](https://github.com/getsentry/sentry-cocoa/releases/tag/9.0.0). Use <PlatformLink to="/profiling/#enable-ui-profiling">UI Profiling</PlatformLink> instead, which was released in version [8.49.0](https://github.com/getsentry/sentry-cocoa/releases/tag/8.49.0).
180180
181181
</Alert>
182182
@@ -210,11 +210,11 @@ SentrySDK.start { options in
210210
}];
211211
```
212212
213-
## Continuous Profiling Beta (deprecated)
213+
## Continuous Profiling Beta (removed in 9.0.0)
214214
215215
<Alert>
216216
217-
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.
217+
Continuous Profiling Beta, explained below, was originally introduced in SDK version [8.36.0](https://github.com/getsentry/sentry-cocoa/releases/tag/8.36.0) and was removed in version [9.0.0](https://github.com/getsentry/sentry-cocoa/releases/tag/9.0.0). Use <PlatformLink to="/profiling/#enable-ui-profiling">UI Profiling</PlatformLink> instead, which was released in version [8.49.0](https://github.com/getsentry/sentry-cocoa/releases/tag/8.49.0).
218218
219219
</Alert>
220220

0 commit comments

Comments
 (0)