Skip to content

Commit 8904049

Browse files
buenaflorcodex
andauthored
docs(flutter): Add v10 migration guide and interactive checklist (#19390)
Document the Flutter v9-to-v10 migration with a dedicated full guide and a companion interactive checklist, matching the JavaScript migration experience. The guide covers platform requirements, removed APIs, and telemetry behavior changes for v10. Closes getsentry/sentry-dart#4023 ## IS YOUR CHANGE URGENT? Help us prioritize incoming PRs by letting us know when the change needs to go live. Select exactly one option. For deadlines, replace `YYYY-MM-DD` with the due date. You can update this information later by editing the PR description. - [ ] Urgent deadline (GA date, etc.): YYYY-MM-DD - [ ] Other deadline: YYYY-MM-DD - [x] No deadline: Not urgent, can wait up to 1 week+ ## SLA - Teamwork makes the dream work, so please add a reviewer to your PRs. - Please give the docs team up to 1 week to review your PR unless you've supplied a deadline. Thanks in advance for your help! ## PRE-MERGE CHECKLIST _Make sure you've checked the following before merging your changes:_ - [ ] Checked Vercel preview for correctness, including links - [ ] PR was reviewed and approved by any necessary SMEs (subject matter experts) - [ ] PR was reviewed and approved by a member of the [Sentry docs team](https://github.com/orgs/getsentry/teams/docs) ## LEGAL BOILERPLATE <!-- Sentry employees and contractors can delete or ignore this section. --> Look, I get it. The entity doing business as "Sentry" was incorporated in the State of Delaware in 2015 as Functional Software, Inc. and is gonna need some rights from me in order to utilize my contributions in this here PR. So here's the deal: I retain all rights, title and interest in and to my contributions, and by keeping this boilerplate intact I confirm that Sentry can use, modify, copy, and redistribute my contributions, under Sentry's choice of terms. ## EXTRA RESOURCES - [Sentry Docs contributor guide](https://docs.sentry.io/contributing/) --------- Co-authored-by: Codex <noreply@openai.com>
1 parent 3e5106a commit 8904049

29 files changed

Lines changed: 664 additions & 30 deletions

docs/platforms/dart/guides/flutter/migration.mdx renamed to docs/platforms/dart/guides/flutter/migration/index.mdx

Lines changed: 11 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,20 @@
11
---
22
title: Migration Guide
33
sidebar_order: 8000
4+
description: "Learn how to migrate your Flutter application between major versions of the Sentry SDK."
45
---
56

7+
## Migrating From `sentry_flutter` `9.x` to `sentry_flutter` `10.x`
8+
9+
See the [v9 to v10 migration guide](/platforms/dart/guides/flutter/migration/v9-to-v10/) for all changes, or use the [interactive migration checklist](/platforms/dart/guides/flutter/migration/v9-to-v10/interactive/) to track your progress.
10+
611
## Migrating from `sentry_flutter` `8.x` to `sentry_flutter` `9.x`
712

813
### General
914

1015
#### Dart and Flutter versions
1116

12-
The required minimum Dart and Flutter versions are now `3.5.0` and `3.24.0` respectively.
17+
The required minimum Dart and Flutter versions are now `3.5.0` and `3.24.0` respectively.
1318
This change allows us to use safer APIs and better support for features such as Session Replay and WASM compilation.
1419

1520
#### Android API version
@@ -18,7 +23,7 @@ The required minimum Android API is now `21`.
1823

1924
#### API Removals and Renames
2025

21-
- The `beforeScreenshot` method has been replaced by `beforeCaptureScreenshot`.
26+
- The `beforeScreenshot` method has been replaced by `beforeCaptureScreenshot`.
2227
- Manual TTID implementation has been removed as the automatic TTID instrumentation has proven to be accurate enough so a manual one is not needed anymore.
2328
- `LoadImagesListIntegration` has been renamed to `LoadNativeDebugImagesIntegration`.
2429
- The `enableTracing` option has been removed. Use `options.traceSampleRate` or `options.tracesSampler` instead.
@@ -31,7 +36,7 @@ The required minimum Android API is now `21`.
3136

3237
#### Response Body Handling
3338

34-
Due to PII concerns, response bodies will no longer be added to Sentry events by the SDK automatically.
39+
Due to PII concerns, response bodies will no longer be added to Sentry events by the SDK automatically.
3540
Responses are now attached to the `Hint` object, which can be read in `beforeSend`/`beforeSendTransaction` callbacks via `hint.response` so you can manually attach the response to your event.
3641
Response bodies with a size greater than 0.15MB are not added to the hint object.
3742
Currently as of version `9.0.0`, only the `dio` integration is supported.
@@ -44,12 +49,12 @@ Read the guide [here](/platforms/dart/guides/flutter/enriching-events/screenshot
4449

4550
#### Logging
4651

47-
The default log level is now `warning` when `debug = true`.
52+
The default log level is now `warning` when `debug = true`.
4853
This can be adjusted by setting `options.diagnosticLevel = SentryLevel.info` in `SentryFlutter.init`.
4954

5055
#### SDK Data Classes
5156

52-
SDK data classes are now mutable which makes it easier to manipulate them.
57+
SDK data classes are now mutable which makes it easier to manipulate them.
5358
For backwards-compatibility, `copyWith` and `clone` can still be used but are officially deprecated.
5459

5560
```dart
@@ -68,7 +73,7 @@ options.beforeSend = (event, hint) {
6873

6974
### Flutter Desktop
7075

71-
Native crash handling is now enabled by default for Flutter Desktop.
76+
Native crash handling is now enabled by default for Flutter Desktop.
7277
Windows ARM64 uses [breakpad](https://chromium.googlesource.com/breakpad/breakpad) and all other desktop platforms use [crashpad](https://chromium.googlesource.com/crashpad/crashpad).
7378
You can disable this feature by setting the `SENTRY_NATIVE_BACKEND` environment variable to "none". e.g `export SENTRY_NATIVE_BACKEND=none`
7479

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
---
2+
title: Migrate from 9.x to 10.x
3+
sidebar_order: 1
4+
description: "Learn how to migrate your Flutter application from Sentry SDK 9.x to 10.x."
5+
---
6+
7+
<Include name="flutter-v10-agent-migration" />
8+
9+
<Include name="flutter-v10-migration-overview" />
10+
11+
<Alert title="Prefer a checklist?" level="info">
12+
13+
The [Interactive v10 Migration Guide](./interactive/) lets you check off completed migration steps.
14+
15+
</Alert>
16+
17+
## Minimum Supported Versions
18+
19+
<Include name="migration/flutter-v10/minimum-versions" />
20+
21+
## Update Sentry Packages
22+
23+
<Include name="migration/flutter-v10/sentry-packages" />
24+
25+
## Android Builds Use Flutter's Kotlin Support
26+
27+
<Include name="migration/flutter-v10/android-kotlin" />
28+
29+
## Apple Builds Use Swift Package Manager
30+
31+
<Include name="migration/flutter-v10/apple-swift-package-manager" />
32+
33+
## Logs and Metrics Are Always Enabled
34+
35+
<Include name="migration/flutter-v10/logs-and-metrics" />
36+
37+
## Telemetry Callbacks Receive a Hint
38+
39+
<Include name="migration/flutter-v10/telemetry-callbacks" />
40+
41+
## Stream Mode Is the Default
42+
43+
<Include name="migration/flutter-v10/stream-default" />
44+
45+
## App Start Is a Standalone Trace
46+
47+
<Include name="migration/flutter-v10/app-start" />
48+
49+
## Native Failed Requests Are Opt-In
50+
51+
<Include name="migration/flutter-v10/native-failed-requests" />
52+
53+
## Profiling and Deprecated APIs Are Removed
54+
55+
<Include name="migration/flutter-v10/removed-apis" />
56+
57+
## Feature Flags Use the Current Scope
58+
59+
<Include name="migration/flutter-v10/feature-flags" />
60+
61+
## Span Attribute Names Have Changed
62+
63+
<Include name="migration/flutter-v10/span-attributes" />
64+
65+
## Throwing Callbacks Drop Telemetry
66+
67+
<Include name="migration/flutter-v10/callback-failures" />
68+
69+
## Error Processing and Release Health
70+
71+
<Include name="migration/flutter-v10/error-processing" />
72+
73+
## HTTP Error Capture and Grouping
74+
75+
<Include name="migration/flutter-v10/http-error-capture" />
76+
77+
## Sensitive Content Masking
78+
79+
<Include name="migration/flutter-v10/sensitive-content" />
80+
81+
## Desktop Crash Reporting Uses Breakpad
82+
83+
<Include name="migration/flutter-v10/desktop-crash-reporting" />
84+
85+
## Flutter Web Uses JavaScript SDK v11
86+
87+
<Include name="migration/flutter-v10/flutter-web" />
Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
---
2+
title: Interactive v10 Migration Guide
3+
sidebar_order: 1
4+
description: "Migrate from Sentry Flutter SDK 9.x to 10.x with an interactive checklist."
5+
---
6+
7+
<Include name="flutter-v10-agent-migration" />
8+
9+
<Include name="flutter-v10-migration-overview" />
10+
11+
This checklist covers the Flutter v10 migration. Some steps only apply to specific target platforms, integrations, or configuration options. Check off a step after completing it or confirming that it doesn't apply to your app. Your progress is saved in this browser.
12+
13+
For details about each change, see the [migration guide](../).
14+
15+
<Alert level="warning">
16+
17+
The Dart analyzer won't catch every behavior change. Read through the steps before upgrading, including changes to telemetry defaults, error grouping, and release health.
18+
19+
</Alert>
20+
21+
## Your Migration Steps
22+
23+
<MigrationGuide migration="flutter-v10" />
Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
<AgentMigrationCallout
2+
guideUrl="/platforms/dart/guides/flutter/migration/v9-to-v10.md"
3+
prompt="Upgrade this project from Sentry Flutter SDK v9 to v10. Inspect its Sentry packages and integrations, Dart and Flutter versions, target platforms, build configuration, and SDK initialization. Apply every migration step that applies to this project. Preserve the intended telemetry collection and privacy behavior, including logging integration defaults, native failed-request capture, and Flutter web sendDefaultPii. Review Apple Swift Package Manager setup, app-start tracing, callback failures, and desktop crash reporting where applicable. Use the project's package manager to update dependencies and its existing analysis, tests, and platform build checks to verify the migration. Summarize the changes and any remaining manual steps."
4+
description="Copy this prompt into your AI agent to migrate to v10."
5+
/>
Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
Version 10 raises the minimum supported platform versions, removes deprecated APIs, and changes several telemetry defaults. The biggest changes are:
2+
3+
- **Platform and build requirements:** Dart 3.12 and Flutter 3.44 are the new minimums, along with Android API 26, iOS 15, and macOS 12. Apple builds use Swift Package Manager instead of CocoaPods, and Android builds use Flutter's Kotlin support.
4+
- **API removals:** Profiling and deprecated APIs, including `copyWith` and `SentryFeedbackWidget`, are removed. Logs and metrics no longer need enable flags.
5+
- **Telemetry behavior:** The logging integration forwards Sentry logs by default, native failed-request capture becomes opt-in, and throwing filtering callbacks drop the affected telemetry.
6+
- **Tracing:** Stream mode is now the default. Migrate custom transaction instrumentation, filtering callbacks, and samplers, or explicitly select `SentryTraceLifecycle.static` to retain transaction mode.
7+
- **App-start tracing:** App start is a standalone `app.start` trace with its own sampling decision and a revised frame-span breakdown. Review custom sampling rules, dashboards, and alerts.
8+
- **Desktop crash reporting:** Windows and Linux default to Breakpad, with native crash reports uploaded after an application restart. A build-time override retains Crashpad.
9+
- **Flutter web:** The bundled JavaScript SDK moves to v11, and browser sessions report unhandled errors as `unhandled` rather than `crashed`. Flutter's `sendDefaultPii` option remains supported.
10+
11+
The guide includes core Dart SDK changes that affect Flutter applications.
Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
---
2+
id: android-kotlin
3+
title: "Android Builds Use Flutter's Kotlin Support"
4+
phase: prerequisites
5+
category: version-support
6+
severity: action-required
7+
frameworks: all
8+
platformCategory: all
9+
order: 30
10+
---
11+
12+
The Sentry Flutter plugin no longer applies or bundles its own Kotlin Gradle Plugin. It relies on Flutter 3.44's Kotlin support. If you customize Android build configuration, update it for Flutter 3.44 rather than relying on Sentry to supply Kotlin. This change does not require upgrading your app to AGP 9.
Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
---
2+
id: app-start
3+
title: "App Start Is a Standalone Trace"
4+
phase: code-changes
5+
category: behavior
6+
severity: action-required
7+
frameworks: all
8+
platformCategory: all
9+
order: 70
10+
---
11+
12+
On Android and iOS, app start is now reported as its own `app.start` root when tracing is enabled. It is no longer attached to the initial `ui.load` transaction and has its own sampling decision.
13+
14+
Remove `options.enableStandaloneAppStartTracing` assignments. The standalone path is now the default, and the option has been removed. Update custom sampling rules, dashboards, and alerts that assume app start belongs to the first navigation transaction. A sampler that only accepts `ui.load` roots may exclude app start.
15+
16+
If startup work continues past the first frame, call `SentryFlutter.extendAppStart()` before the first frame renders and `await SentryFlutter.finishExtendedAppStart()` when that work finishes. An extension that reaches the 30-second app-start deadline is dropped, and the reported duration falls back to the first frame.
17+
18+
The app-start breakdown also changes in v10. Update queries, dashboards, and `beforeSendSpan` callbacks that match `app.start.plugin_registration`, `app.start.sentry_setup`, or `app.start.first_frame_render`. These operations are no longer emitted. The SDK records measured startup work using:
19+
20+
| Operation | Measured Work |
21+
| ---------------------------------- | --------------------------------------------- |
22+
| `app.start.root_widget_attachment` | Attachment of the root widget |
23+
| `app.start.frame_build` | Flutter framework frame builds during startup |
24+
| `app.start.frame_raster` | Rasterization of the first frame |
25+
26+
These spans are not one-to-one replacements for the previous broad intervals. Frame-build spans include `flutter.frame.warm_up` and `flutter.frame.deferred` attributes. A frame-build span does not by itself mean that the frame was submitted to the engine or displayed.
27+
28+
Startup frame builds that begin at or after the first frame's rasterization starts are also excluded.
Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
---
2+
id: apple-swift-package-manager
3+
title: "Apple Builds Use Swift Package Manager"
4+
phase: prerequisites
5+
category: package
6+
severity: action-required
7+
frameworks: all
8+
platformCategory: all
9+
order: 40
10+
---
11+
12+
The Sentry Flutter plugin no longer supports CocoaPods. On iOS and macOS, it uses Swift Package Manager to install the native Sentry Cocoa SDK, which has been upgraded to v9. If you initialize Sentry separately in native code or call its Swift/Objective-C APIs directly, also review the [Sentry Cocoa v8-to-v9 migration guide](/platforms/apple/migration/v8-to-v9/).
13+
14+
Flutter 3.44 enables Swift Package Manager by default and migrates your project when you run the app. If you previously disabled it, re-enable it and remove any project-level `enable-swift-package-manager: false` setting:
15+
16+
```bash
17+
flutter config --enable-swift-package-manager
18+
flutter pub get
19+
```
20+
21+
Set the iOS and macOS deployment targets in Xcode to the minimum versions listed in [Minimum Supported Versions](/platforms/dart/guides/flutter/migration/v9-to-v10/#minimum-supported-versions). For custom targets, flavors, or projects that don't migrate automatically, follow [Flutter's Swift Package Manager migration instructions](https://docs.flutter.dev/packages-and-plugins/swift-package-manager/for-app-developers/).
22+
23+
Other Flutter plugins may still require CocoaPods. Only remove your application's CocoaPods integration once all of its dependencies support Swift Package Manager.
Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
---
2+
id: callback-failures
3+
title: "Throwing Callbacks Drop Telemetry"
4+
phase: code-changes
5+
category: behavior
6+
severity: behavior-change
7+
frameworks: all
8+
platformCategory: all
9+
order: 115
10+
---
11+
12+
In v10, an exception in an event processor or a filtering callback drops the affected telemetry item instead of sending the item through unchanged.
13+
14+
This applies to event processors, `beforeSend`, `beforeSendTransaction`, `beforeSendFeedback`, `beforeBreadcrumb`, `beforeSendLog`, and `beforeSendMetric`. Review callbacks that can throw, especially custom filtering and scrubbing logic. Handle expected failures inside the callback and return the intended item or `null` explicitly.
15+
16+
In transaction mode, a throwing `tracesSampler` uses the inherited sampling decision when available, then falls back to `tracesSampleRate`. In stream mode, it falls back to `tracesSampleRate`. Do not rely on throwing an exception to reject a trace; return `0.0` to reject it explicitly.
Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
---
2+
id: desktop-crash-reporting
3+
title: "Desktop Crash Reporting Uses Breakpad"
4+
phase: verify
5+
category: behavior
6+
severity: behavior-change
7+
frameworks: all
8+
platformCategory: all
9+
order: 150
10+
---
11+
12+
On Windows and Linux, the default native crash backend changes to Breakpad. Native crash reports are uploaded when the application starts again, rather than by a separate Crashpad handler at crash time.
13+
14+
Breakpad handles crashes in the application process, without Crashpad's out-of-process isolation. It also lacks Crashpad's Windows Error Reporting (WER) and fast-fail coverage. Review crash-delivery expectations and test a crash followed by an application restart.
15+
16+
To retain Crashpad, set the `SENTRY_NATIVE_BACKEND` environment variable to `crashpad` in your local build environment and CI before building the application. For example:
17+
18+
```bash {tabTitle:Linux} {mdExpandTabs}
19+
SENTRY_NATIVE_BACKEND=crashpad flutter build linux
20+
```
21+
22+
```powershell {tabTitle:Windows}
23+
$env:SENTRY_NATIVE_BACKEND = "crashpad"
24+
flutter build windows
25+
```
26+
27+
This is a build-time setting, not a Dart SDK initialization option.

0 commit comments

Comments
 (0)