feat(apple): Migration Guide for V9

philipphofmann · philipphofmann · commit 66a676716583 · 2025-11-27T14:01:30.000+01:00
Add the migration guide for major version v9.
diff --git a/docs/platforms/apple/common/configuration/app-hangs.mdx b/docs/platforms/apple/common/configuration/app-hangs.mdx
@@ -134,11 +134,11 @@ SentrySDK.resumeAppHangTracking()
 
 ### App Hangs V2
 
-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.
+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.
 
 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.
 
-To enable the feature:
+To enable the feature in version 8.50.0 and later (enabled by default starting with 9.0.0):
 
 ```swift {tabTitle:Swift}
 import Sentry
@@ -190,7 +190,7 @@ SentrySDK.start { options in
 
 <Alert level="info">
 
-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.
+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.**
 
 </Alert>
 
diff --git a/docs/platforms/apple/common/migration/index.mdx b/docs/platforms/apple/common/migration/index.mdx
@@ -3,7 +3,126 @@ title: Migration Guide
 sidebar_order: 8000
 ---
 
-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.
+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.
+
+## Migrating From 8.x to 9.x
+
+Migrating to 9.x from 8.x includes several breaking changes. We provide this guide to help you update your SDK.
+
+### Changes to Minimum OS Versions and Xcode
+
+We bumped the minimum supported OS versions to:
+- **iOS**: 15.0 (previously 11.0)
+- **macOS**: 10.14 (previously 10.13)
+- **tvOS**: 15.0 (previously 11.0)
+- **visionOS**: 1.0 (unchanged)
+- **watchOS**: 8.0 (previously 4.0)
+
+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.
+
+Additionally, the Package.swift sets `swift-tools-version` to 6.0.
+
+### Features Enabled by Default
+
+We now enabled the following features by default:
+
+- **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.
+- **Pre-warmed app start tracking**: The SDK now collects pre-warmed app starts by default via `enablePreWarmedAppStartTracing`.
+- <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.
+
+### Disable App Hang Tracking for Extensions
+
+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.
+
+### Structured Logging
+
+We moved structured logging options out of experimental and made them part of the main API. We added log APIs to `Hub` and `Client`, and logs now include a `sentry.replay_id` attribute.
+
+#### HTTP Client Errors
+
+HTTP client errors now mark sessions as errored. This provides better visibility into failed network requests in your release health data.
+
+### Profiling Changes
+
+We removed all deprecated profiling APIs in version 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.
+
+**Removed deprecated profiling options from `SentryOptions`:**
+- `profilesSampleRate` - used for transaction-based profiling (deprecated)
+- `profilesSampler` - used for transaction-based profiling (deprecated)
+- `enableAppLaunchProfiling` - used for launch profiling (deprecated)
+
+**Migration to UI Profiling:**
+
+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`:
+
+```swift
+import Sentry
+
+SentrySDK.start { options in
+    options.dsn = "___PUBLIC_DSN___"
+    options.configureProfiling = {
+        $0.sessionSampleRate = 1
+        $0.lifecycle = .manual // or .trace for trace-based lifecycle
+    }
+}
+```
+
+For more information, see the <PlatformLink to="/profiling/#enable-ui-profiling">UI Profiling documentation</PlatformLink>.
+
+### Breaking Changes
+
+#### Option Changes
+
+- `enableFileManagerSwizzling` is now a top-level non-experimental option and remains disabled by default.
+- `enableDataSwizzling` is now a top-level option and is enabled by default.
+- We increased the maximum attachment size to 200MB (previously 20MB)
+- We removed the following methods and properties:
+  - `inAppExclude` (it had no effect)
+  - `integrations`
+  - `defaultIntegrations()`
+  - `enableTracing` (use `tracesSampleRate` or `tracesSampler` instead)
+  - `getStoreEndpoint()`
+
+#### Behavioral Breaking Changes
+
+- The default trace context status is now `ok` instead of `undefined`.
+- The `function` property on `SentryFrame` now defaults to `nil` instead of `"<redacted>"`
+- The `value` and `type` properties on `SentryException` are now nullable; when `NSException` has no reason, `type` is set to `nil`
+
+#### Renamed APIs
+
+- We renamed `SentryStructuredLogLevel` to `SentryLogLevel`
+- We renamed `SentryStructuredLogAttribute` to `SentryLogAttribute`
+
+#### Removed APIs
+
+- We removed the `segment` property from `SentryTraceContext`, `SentryUser`, and `SentryBaggage`
+- We removed the initializers from `SentryTraceContext`
+- We removed `SentryDsn.getHash()`
+- We removed `SentryFrame.instruction`
+
+We removed the following deprecated APIs:
+
+- `SentrySpan.setExtraValue(_:forKey:)`
+- User feedback API (use the new feedback API instead)
+- `Scope.useSpan()` (use `Scope.span` instead)
+- `SentryDebugMeta.uuid` (use `debugID` instead)
+- `SentryDebugMeta.name` (use `codeFile` instead)
+
+We made the following classes and APIs private:
+
+- `SentryEventDecoder` and `SentryEventDecodable`
+- `SentryEnvelopeItemHeader`
+- `SentryIntegrationProtocol`
+- `SentrySession`
+- `SentrySDKInfo`
+- `SentryDebugImageProvider`
+
+#### Other breaking changes
+
+- We made the following classes `final`: `PreviewRedactOptions`, `SentryProfileOptions`, `SentryRedactViewHelper`, `SentryViewScreenshotOptions`, `SentryReplayOptions`, `SentryUserFeedbackConfiguration`, `SentryUserFeedbackFormConfiguration`, `SentryUserFeedbackThemeConfiguration`, `SentryUserFeedbackWidgetConfiguration`, `SentryFeedback`, and `SentryExperimentalOptions`
+
+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)
 
 ## Migrating From 7.x to 8.x
 
diff --git a/docs/platforms/apple/common/profiling/index.mdx b/docs/platforms/apple/common/profiling/index.mdx
@@ -20,7 +20,7 @@ notSupported:
 
 <Alert>
 
-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.
+UI Profiling was introduced in SDK version 8.49.0. All prior profiling APIs were removed in version 9.0.0.
 
 </Alert>
 
@@ -48,7 +48,7 @@ SentrySDK.start { options in
 }];
 ```
 
-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, `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.
 
 See the subsections below to learn about the various ways the profiler can be started and stopped.
 
@@ -74,7 +74,7 @@ var tableView: UITableView!
         DispatchQueue.main.async {
             self.tableView.performBatchUpdates {
                 // update table view with model
-            } completion: { finished in 
+            } completion: { finished in
                 SentrySDK.stopProfiler()
             }
         }
@@ -124,7 +124,7 @@ Check out the <PlatformLink to="/tracing/">tracing setup documentation</Platform
 
 ### 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 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 <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.
 
@@ -136,11 +136,11 @@ The SDK must have been started with a call to `SentrySDK.startWithOptions` in or
 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.
 </Alert>
 
-## Transaction-based Profiling (deprecated)
+## Transaction-based Profiling (removed in 9.0.0)
 
 <Alert>
 
-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.
+Transaction-based profiling configuration, explained below, was originally introduced in SDK version 8.12.0 and was removed in version 9.0.0. Use <PlatformLink to="/profiling/#enable-ui-profiling">UI Profiling</PlatformLink> instead, which was introduced in version 8.49.0.
 
 </Alert>
 
@@ -172,11 +172,11 @@ SentrySDK.start { options in
 }];
 ```
 
-## Launch Profiling (deprecated)
+## Launch Profiling (removed in 9.0.0)
 
 <Alert>
 
-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.
+Launch profiling configuration, explained below, was originally introduced in SDK version 8.21.0 and was removed in version 9.0.0. Use <PlatformLink to="/profiling/#enable-ui-profiling">UI Profiling</PlatformLink> instead, which was released in version 8.49.0.
 
 </Alert>
 
@@ -210,11 +210,11 @@ SentrySDK.start { options in
 }];
 ```
 
-## Continuous Profiling Beta (deprecated)
+## Continuous Profiling Beta (removed in 9.0.0)
 
 <Alert>
 
-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.
+Continuous Profiling Beta, explained below, was originally introduced in SDK version 8.36.0 and was removed in version 9.0.0. Use <PlatformLink to="/profiling/#enable-ui-profiling">UI Profiling</PlatformLink> instead, which was released in version 8.49.0.
 
 </Alert>
 
