You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 8904049
Browse filesBrowse the repository at this point in the historyBrowse files
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.
Closesgetsentry/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>
Copy file name to clipboardExpand all lines: docs/platforms/dart/guides/flutter/migration/index.mdx
+11-6Lines changed: 11 additions & 6 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,15 +1,20 @@
1
1
---
2
2
title: Migration Guide
3
3
sidebar_order: 8000
4
+
description: "Learn how to migrate your Flutter application between major versions of the Sentry SDK."
4
5
---
5
6
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
+
6
11
## Migrating from `sentry_flutter``8.x` to `sentry_flutter``9.x`
7
12
8
13
### General
9
14
10
15
#### Dart and Flutter versions
11
16
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.
13
18
This change allows us to use safer APIs and better support for features such as Session Replay and WASM compilation.
14
19
15
20
#### Android API version
@@ -18,7 +23,7 @@ The required minimum Android API is now `21`.
18
23
19
24
#### API Removals and Renames
20
25
21
-
- The `beforeScreenshot` method has been replaced by `beforeCaptureScreenshot`.
26
+
- The `beforeScreenshot` method has been replaced by `beforeCaptureScreenshot`.
22
27
- 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.
23
28
-`LoadImagesListIntegration` has been renamed to `LoadNativeDebugImagesIntegration`.
24
29
- 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`.
31
36
32
37
#### Response Body Handling
33
38
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.
35
40
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.
36
41
Response bodies with a size greater than 0.15MB are not added to the hint object.
37
42
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
44
49
45
50
#### Logging
46
51
47
-
The default log level is now `warning` when `debug = true`.
52
+
The default log level is now `warning` when `debug = true`.
48
53
This can be adjusted by setting `options.diagnosticLevel = SentryLevel.info` in `SentryFlutter.init`.
49
54
50
55
#### SDK Data Classes
51
56
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.
53
58
For backwards-compatibility, `copyWith` and `clone` can still be used but are officially deprecated.
Native crash handling is now enabled by default for Flutter Desktop.
76
+
Native crash handling is now enabled by default for Flutter Desktop.
72
77
Windows ARM64 uses [breakpad](https://chromium.googlesource.com/breakpad/breakpad) and all other desktop platforms use [crashpad](https://chromium.googlesource.com/crashpad/crashpad).
73
78
You can disable this feature by setting the `SENTRY_NATIVE_BACKEND` environment variable to "none". e.g `export SENTRY_NATIVE_BACKEND=none`
description: "Migrate from Sentry Flutter SDK 9.x to 10.x with an interactive checklist."
5
+
---
6
+
7
+
<Includename="flutter-v10-agent-migration" />
8
+
9
+
<Includename="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
+
<Alertlevel="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.
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."
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.
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.
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:
|`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.
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.
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.
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