From 5c59717e9bf35d50e6c429f682cf5e8ead5959e0 Mon Sep 17 00:00:00 2001 From: Giancarlo Buenaflor Date: Tue, 26 May 2026 16:58:22 +0200 Subject: [PATCH 01/13] docs(flutter): Add ANR and App Hangs guidance Document Flutter responsiveness detection and clarify required debug symbols for readable Android ANR and Apple App Hang stack traces. Co-authored-by: Cursor --- .../flutter/configuration/anr-app-hangs.mdx | 72 +++++++++++++++++++ .../guides/flutter/configuration/options.mdx | 2 +- .../dart/guides/flutter/features/index.mdx | 2 +- .../dart-plugin/dart.flutter.mdx | 8 +++ 4 files changed, 82 insertions(+), 2 deletions(-) create mode 100644 docs/platforms/dart/guides/flutter/configuration/anr-app-hangs.mdx diff --git a/docs/platforms/dart/guides/flutter/configuration/anr-app-hangs.mdx b/docs/platforms/dart/guides/flutter/configuration/anr-app-hangs.mdx new file mode 100644 index 0000000000000..fa6034a7383ff --- /dev/null +++ b/docs/platforms/dart/guides/flutter/configuration/anr-app-hangs.mdx @@ -0,0 +1,72 @@ +--- +title: ANR and App Hangs +description: "Learn how Sentry detects and configures ANRs and app hangs in Flutter apps." +sidebar_order: 45 +--- + +Sentry can report app responsiveness issues when your Flutter app's main thread is blocked for too long. The Flutter SDK uses the native SDK layers to detect these events on mobile and desktop platforms. + +## What Gets Reported + +The event type depends on the platform: + +| Platform | Event | +| -------- | -------------------------------- | +| Android | Application Not Responding (ANR) | +| iOS | App Hang | +| macOS | App Hang | + +Android ANR events can include stack frames from Dart, Kotlin, Java, C, or C++ code, depending on where the app was blocked. On iOS and macOS, App Hang events come from the Apple SDK bundled with the Flutter SDK. + +## Configure Detection + +ANR and App Hang detection are enabled by default. You can disable them or change their timeout thresholds in `SentryFlutter.init`: + +```dart +await SentryFlutter.init( + (options) { + // Android only: ANR + options.anrEnabled = true; // default: true + options.anrTimeoutInterval = const Duration(seconds: 5); // default: 5s + + // iOS/macOS only: App Hang + options.enableAppHangTracking = true; // default: true + options.appHangTimeoutInterval = const Duration(seconds: 2); // default: 2s + }, +); +``` + +See the options documentation for more configuration details. + +## Pause App Hang Tracking + +On iOS and macOS, you can pause App Hang tracking at runtime. Use this when your app intentionally blocks the main thread for work you don't want reported as an app hang. + +```dart +SentryFlutter.pauseAppHangTracking(); + +// Run code that you don't want Sentry to report as an app hang. + +SentryFlutter.resumeAppHangTracking(); +``` + +## Get Readable Stack Traces + +Readable stack traces for ANR and App Hang events require the right debug symbols for each platform: + +| Platform | Required debug files | +| -------- | ------------------------------------------------------------------------------------------------------ | +| Android | Flutter `.symbols` files generated by `--split-debug-info`; `mapping.txt` if R8 or ProGuard is enabled | +| iOS | dSYM files | +| macOS | dSYM files | + +Xcode generates dSYM files when you build your iOS or macOS app. The Sentry Dart Plugin automatically uploads Flutter `.symbols` files and Apple dSYM files. You don't need `--split-debug-info` just to symbolicate App Hang stack traces on iOS or macOS. + +If R8 or ProGuard is enabled for Android, upload `mapping.txt` separately with the Sentry Android Gradle Plugin. See the Android ProGuard Integration section in the Sentry Dart Plugin documentation. + +## Platform Details + +For more details about how each native SDK detects these events, see: + +- [Android ANR documentation](/platforms/android/configuration/app-not-respond/) +- [Apple App Hangs documentation](/platforms/apple/configuration/app-hangs/) diff --git a/docs/platforms/dart/guides/flutter/configuration/options.mdx b/docs/platforms/dart/guides/flutter/configuration/options.mdx index 8250787116a66..2ed76eef88ae4 100644 --- a/docs/platforms/dart/guides/flutter/configuration/options.mdx +++ b/docs/platforms/dart/guides/flutter/configuration/options.mdx @@ -361,7 +361,7 @@ Set this boolean to `false` to disable reporting all the package dependencies. -Set this boolean to `true` to enable ANR (Application Not Responding) detection on Android. +Set this boolean to `true` to enable ANR (Application Not Responding) detection on Android. Learn more in ANR and App Hangs. diff --git a/docs/platforms/dart/guides/flutter/features/index.mdx b/docs/platforms/dart/guides/flutter/features/index.mdx index 7dc0c7e59576b..c137e2b0f8b30 100644 --- a/docs/platforms/dart/guides/flutter/features/index.mdx +++ b/docs/platforms/dart/guides/flutter/features/index.mdx @@ -15,7 +15,7 @@ Sentry's Flutter SDK enables automatic reporting of errors and exceptions, and i - Automatic native crash error tracking (using both Android and iOS), including: - Java, Kotlin, C, and C++ code for Android. - ObjC, Swift, and C for iOS. -- Automatic detection of Application Not Responding (ANR) on Android and App Hangs on iOS. +- Automatic detection of Application Not Responding (ANR) and App Hangs. - Offline storage of events. - Events enriched with device data. - Breadcrumbs automatically captured: diff --git a/platform-includes/debug-symbols/dart-plugin/dart.flutter.mdx b/platform-includes/debug-symbols/dart-plugin/dart.flutter.mdx index b56378a210b36..9799dfabefaf4 100644 --- a/platform-includes/debug-symbols/dart-plugin/dart.flutter.mdx +++ b/platform-includes/debug-symbols/dart-plugin/dart.flutter.mdx @@ -117,6 +117,14 @@ flutter build --obfuscate --split-debug-info= --extra flutter build web --release --source-maps ``` +## Android ANR Symbolication + +On Android, ANR detection happens outside the Dart runtime. If an ANR event includes Dart frames from Flutter AOT code, those frames need the `.symbols` files generated by `--split-debug-info` to be symbolicated in Sentry. + +Without `--split-debug-info`, Dart frames in Android ANR events may appear as unresolved addresses in `libapp.so`. The same `.symbols` files also provide the debug ID Sentry uses to match source bundles for source context. + +`mapping.txt` files only deobfuscate JVM frames from Kotlin or Java code, and native debug symbols only symbolicate NDK frames from C or C++ libraries. They don't replace Flutter `.symbols` files for Dart frames. + ## Running the Plugin After building your application, run the plugin to upload debug symbols: From 31010109534d2c473094097ff2e939ff64fd92c8 Mon Sep 17 00:00:00 2001 From: Giancarlo Buenaflor Date: Thu, 28 May 2026 14:59:17 +0200 Subject: [PATCH 02/13] docs(flutter): Refine ANR symbolication guidance Clarify where ANR and App Hang symbolication details belong and keep the configuration page focused on the feature-level guidance. Co-authored-by: Cursor --- .../flutter/configuration/anr-app-hangs.mdx | 30 ++++++------------- .../dart-plugin/dart.flutter.mdx | 24 ++++++++++----- 2 files changed, 26 insertions(+), 28 deletions(-) diff --git a/docs/platforms/dart/guides/flutter/configuration/anr-app-hangs.mdx b/docs/platforms/dart/guides/flutter/configuration/anr-app-hangs.mdx index fa6034a7383ff..c6bb275a8a4f7 100644 --- a/docs/platforms/dart/guides/flutter/configuration/anr-app-hangs.mdx +++ b/docs/platforms/dart/guides/flutter/configuration/anr-app-hangs.mdx @@ -4,19 +4,15 @@ description: "Learn how Sentry detects and configures ANRs and app hangs in Flut sidebar_order: 45 --- -Sentry can report app responsiveness issues when your Flutter app's main thread is blocked for too long. The Flutter SDK uses the native SDK layers to detect these events on mobile and desktop platforms. +Sentry can detect when your Flutter app's main thread is blocked for too long, causing the app to become unresponsive. The Flutter SDK relies on the underlying native Sentry SDKs to detect these events. -## What Gets Reported +**This feature is available on Android, iOS, and macOS.** -The event type depends on the platform: +## What Gets Reported -| Platform | Event | -| -------- | -------------------------------- | -| Android | Application Not Responding (ANR) | -| iOS | App Hang | -| macOS | App Hang | +On Android, these are reported as Application Not Responding (ANR) events and can include stack frames from Dart, Kotlin, Java, or C/C++ code, depending on where the app was blocked. -Android ANR events can include stack frames from Dart, Kotlin, Java, C, or C++ code, depending on where the app was blocked. On iOS and macOS, App Hang events come from the Apple SDK bundled with the Flutter SDK. +On iOS and macOS, they're reported as App Hang events and can include stack frames from Dart, Swift, Objective-C, or C/C++ code. ## Configure Detection @@ -40,7 +36,7 @@ See the options documentat ## Pause App Hang Tracking -On iOS and macOS, you can pause App Hang tracking at runtime. Use this when your app intentionally blocks the main thread for work you don't want reported as an app hang. +On iOS and macOS, you can pause App Hang tracking at runtime. Use this when you can't avoid a known blocking operation, such as a synchronous database migration during startup, and don't want Sentry to report it as an app hang. ```dart SentryFlutter.pauseAppHangTracking(); @@ -50,19 +46,11 @@ SentryFlutter.pauseAppHangTracking(); SentryFlutter.resumeAppHangTracking(); ``` -## Get Readable Stack Traces - -Readable stack traces for ANR and App Hang events require the right debug symbols for each platform: - -| Platform | Required debug files | -| -------- | ------------------------------------------------------------------------------------------------------ | -| Android | Flutter `.symbols` files generated by `--split-debug-info`; `mapping.txt` if R8 or ProGuard is enabled | -| iOS | dSYM files | -| macOS | dSYM files | +## Readable Stack Traces -Xcode generates dSYM files when you build your iOS or macOS app. The Sentry Dart Plugin automatically uploads Flutter `.symbols` files and Apple dSYM files. You don't need `--split-debug-info` just to symbolicate App Hang stack traces on iOS or macOS. +ANR and App Hang events can include frames from Dart, Java/Kotlin, Swift/Objective-C, and native code. To make those frames readable, Sentry needs the matching debug files for each platform. -If R8 or ProGuard is enabled for Android, upload `mapping.txt` separately with the Sentry Android Gradle Plugin. See the Android ProGuard Integration section in the Sentry Dart Plugin documentation. +See the Sentry Dart Plugin documentation for the debug files required on Android, iOS, and macOS, including Android R8/ProGuard mapping files. ## Platform Details diff --git a/platform-includes/debug-symbols/dart-plugin/dart.flutter.mdx b/platform-includes/debug-symbols/dart-plugin/dart.flutter.mdx index 9799dfabefaf4..e06db55f1f1ec 100644 --- a/platform-includes/debug-symbols/dart-plugin/dart.flutter.mdx +++ b/platform-includes/debug-symbols/dart-plugin/dart.flutter.mdx @@ -117,21 +117,31 @@ flutter build --obfuscate --split-debug-info= --extra flutter build web --release --source-maps ``` -## Android ANR Symbolication +## Running the Plugin + +After building your application, run the plugin to upload debug symbols: + +```bash +flutter pub run sentry_dart_plugin +``` + +## ANR and App Hang Symbolication -On Android, ANR detection happens outside the Dart runtime. If an ANR event includes Dart frames from Flutter AOT code, those frames need the `.symbols` files generated by `--split-debug-info` to be symbolicated in Sentry. +ANR and App Hang detection happens outside the Dart runtime and can include frames from Dart, Java/Kotlin, Swift/Objective-C, and native code. To make stack traces readable, Sentry needs the debug files generated for the platform you're building. + +### Android ANR Symbolication + +If an Android ANR event includes Dart frames from Flutter AOT code, those frames need the `.symbols` files generated by `--split-debug-info` to be symbolicated in Sentry. Without `--split-debug-info`, Dart frames in Android ANR events may appear as unresolved addresses in `libapp.so`. The same `.symbols` files also provide the debug ID Sentry uses to match source bundles for source context. `mapping.txt` files only deobfuscate JVM frames from Kotlin or Java code, and native debug symbols only symbolicate NDK frames from C or C++ libraries. They don't replace Flutter `.symbols` files for Dart frames. -## Running the Plugin +### iOS and macOS App Hang Symbolication -After building your application, run the plugin to upload debug symbols: +For iOS and macOS App Hang events, Sentry needs the dSYM files Xcode generates when building your app. -```bash -flutter pub run sentry_dart_plugin -``` +The Sentry Dart Plugin uploads those dSYM files after your build. You don't need `--split-debug-info` just to symbolicate App Hang stack traces on iOS or macOS. ## Android ProGuard Integration From 3dbfadeab5f94945776d6c9bccfa763d7a4dc36c Mon Sep 17 00:00:00 2001 From: Giancarlo Buenaflor Date: Thu, 28 May 2026 15:09:46 +0200 Subject: [PATCH 03/13] docs(flutter): Capitalize App Hangs description Keep the ANR and App Hangs page metadata consistent with the page title. Co-authored-by: Cursor --- .../dart/guides/flutter/configuration/anr-app-hangs.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/platforms/dart/guides/flutter/configuration/anr-app-hangs.mdx b/docs/platforms/dart/guides/flutter/configuration/anr-app-hangs.mdx index c6bb275a8a4f7..a58b30c6536f7 100644 --- a/docs/platforms/dart/guides/flutter/configuration/anr-app-hangs.mdx +++ b/docs/platforms/dart/guides/flutter/configuration/anr-app-hangs.mdx @@ -1,6 +1,6 @@ --- title: ANR and App Hangs -description: "Learn how Sentry detects and configures ANRs and app hangs in Flutter apps." +description: "Learn how Sentry detects and configures ANRs and App Hangs in Flutter apps." sidebar_order: 45 --- From 6f2b0d1db79656fa0a97c72f5e6d8d537ae529ab Mon Sep 17 00:00:00 2001 From: Giancarlo Buenaflor Date: Thu, 28 May 2026 15:11:33 +0200 Subject: [PATCH 04/13] docs(flutter): Clarify ANR and App Hang event names Consolidate the platform event naming text on the Flutter ANR and App Hangs page. Co-authored-by: Cursor --- .../dart/guides/flutter/configuration/anr-app-hangs.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/platforms/dart/guides/flutter/configuration/anr-app-hangs.mdx b/docs/platforms/dart/guides/flutter/configuration/anr-app-hangs.mdx index a58b30c6536f7..e5900b92b53bb 100644 --- a/docs/platforms/dart/guides/flutter/configuration/anr-app-hangs.mdx +++ b/docs/platforms/dart/guides/flutter/configuration/anr-app-hangs.mdx @@ -10,9 +10,9 @@ Sentry can detect when your Flutter app's main thread is blocked for too long, c ## What Gets Reported -On Android, these are reported as Application Not Responding (ANR) events and can include stack frames from Dart, Kotlin, Java, or C/C++ code, depending on where the app was blocked. - -On iOS and macOS, they're reported as App Hang events and can include stack frames from Dart, Swift, Objective-C, or C/C++ code. +On Android, these are reported as Application Not Responding (ANR) events. +On iOS and macOS, they're reported as App Hang events. +Depending on where the app was blocked, events can include stack frames from Dart, Java/Kotlin, Swift/Objective-C, or C/C++ code. ## Configure Detection From 58c4379fee0a3ad41f9149cf649d94ce73fa1b08 Mon Sep 17 00:00:00 2001 From: Giancarlo Buenaflor Date: Thu, 28 May 2026 15:16:38 +0200 Subject: [PATCH 05/13] docs(flutter): Clarify readable frame wording Tighten the ANR and App Hang stack trace guidance to explain why each platform's debug files are needed. Co-authored-by: Cursor --- .../dart/guides/flutter/configuration/anr-app-hangs.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/platforms/dart/guides/flutter/configuration/anr-app-hangs.mdx b/docs/platforms/dart/guides/flutter/configuration/anr-app-hangs.mdx index e5900b92b53bb..4749dad663afd 100644 --- a/docs/platforms/dart/guides/flutter/configuration/anr-app-hangs.mdx +++ b/docs/platforms/dart/guides/flutter/configuration/anr-app-hangs.mdx @@ -48,7 +48,7 @@ SentryFlutter.resumeAppHangTracking(); ## Readable Stack Traces -ANR and App Hang events can include frames from Dart, Java/Kotlin, Swift/Objective-C, and native code. To make those frames readable, Sentry needs the matching debug files for each platform. +Since ANR and App Hang events can include frames from Dart, Java/Kotlin, Swift/Objective-C, and C/C++ code, Sentry needs the corresponding debug files to make each frame readable. See the Sentry Dart Plugin documentation for the debug files required on Android, iOS, and macOS, including Android R8/ProGuard mapping files. From 359133302f1d4e1aeaaeeeb3cfee5681d555b91f Mon Sep 17 00:00:00 2001 From: Giancarlo Buenaflor Date: Thu, 28 May 2026 15:22:15 +0200 Subject: [PATCH 06/13] Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- .../dart/guides/flutter/configuration/anr-app-hangs.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/platforms/dart/guides/flutter/configuration/anr-app-hangs.mdx b/docs/platforms/dart/guides/flutter/configuration/anr-app-hangs.mdx index 4749dad663afd..15dc7d242d08d 100644 --- a/docs/platforms/dart/guides/flutter/configuration/anr-app-hangs.mdx +++ b/docs/platforms/dart/guides/flutter/configuration/anr-app-hangs.mdx @@ -32,7 +32,7 @@ await SentryFlutter.init( ); ``` -See the options documentation for more configuration details. +For more configuration details, see the Android ANR documentation and the Apple App Hangs documentation. ## Pause App Hang Tracking From 84e3839b26e1d0bf41bebbd3c9b239f960dacd9a Mon Sep 17 00:00:00 2001 From: Giancarlo Buenaflor Date: Thu, 28 May 2026 15:37:29 +0200 Subject: [PATCH 07/13] docs(flutter): Fix docs lint formatting Apply Prettier formatting to the touched Flutter docs files so the PR lint checks pass. Co-authored-by: Cursor --- .../guides/flutter/configuration/options.mdx | 2 +- .../dart/guides/flutter/features/index.mdx | 49 ++++++++--- .../dart-plugin/dart.flutter.mdx | 83 ++++++++++--------- 3 files changed, 79 insertions(+), 55 deletions(-) diff --git a/docs/platforms/dart/guides/flutter/configuration/options.mdx b/docs/platforms/dart/guides/flutter/configuration/options.mdx index 2ed76eef88ae4..fe969649980f2 100644 --- a/docs/platforms/dart/guides/flutter/configuration/options.mdx +++ b/docs/platforms/dart/guides/flutter/configuration/options.mdx @@ -34,7 +34,7 @@ Enabling `debug` mode makes the SDK generate as much diagnostic data as possible - `debug`: The most verbose mode - `info`: Informational messages -- `warning`: **default** Warning that something might not be right +- `warning`: **default** Warning that something might not be right - `error`: Only SDK internal errors are printed - `fatal`: Only critical errors are printed diff --git a/docs/platforms/dart/guides/flutter/features/index.mdx b/docs/platforms/dart/guides/flutter/features/index.mdx index c137e2b0f8b30..fa1dd06a366f7 100644 --- a/docs/platforms/dart/guides/flutter/features/index.mdx +++ b/docs/platforms/dart/guides/flutter/features/index.mdx @@ -25,23 +25,46 @@ Sentry's Flutter SDK enables automatic reporting of errors and exceptions, and i - Integrations for sqflite, routing and more. For a complete list, see integrations. - Release Health tracks crash free users and sessions. -- Attachments that - can enrich your event by storing additional files, such as config or log +- Attachments + that can enrich your event by storing additional files, such as config or log files. -- Tracing that can track: - - App start time - - Time to Initial Display and Time to Full Display - - Slow and Frozen Frames - - User Interaction which include clicks, long clicks, taps and so on. - - For a complete list see automatic instrumentations. +- Tracing that can track + + app start time + + , + + Time to Initial Display and Time to Full Display + + , + + Slow and Frozen Frames + + , and + + User Interaction + + . For a complete list, see + + automatic instrumentations + + . - User Feedback, providing the ability to collect user feedback when an unexpected event occurs. -- Screenshot and View Hierarchy attachments for errors. +- Screenshot and + + View Hierarchy + + attachments for errors. - Profiling collects detailed - information about your code at the function level. - - Profiling is currently supported on **iOS** and **macOS**. - - It captures profiles across multiple language layers, including native languages (such as Swift and Objective-C) as well as Dart. -- Source Context shows snippets of code around the location of stack frames. + information about your code at the function level. Profiling is currently + supported on **iOS** and **macOS**, and captures profiles across multiple + language layers, including native languages (such as Swift and Objective-C) as + well as Dart. +- + Source Context + + shows snippets of code around the location of stack frames. - Sentry Dart Plugin makes uploading debug symbols easy and automatic. - Metrics allow you to send counters, diff --git a/platform-includes/debug-symbols/dart-plugin/dart.flutter.mdx b/platform-includes/debug-symbols/dart-plugin/dart.flutter.mdx index e06db55f1f1ec..d36d9ad644099 100644 --- a/platform-includes/debug-symbols/dart-plugin/dart.flutter.mdx +++ b/platform-includes/debug-symbols/dart-plugin/dart.flutter.mdx @@ -15,9 +15,9 @@ The Sentry Dart Plugin requires basic configuration in your `pubspec.yaml` file: @@ -104,8 +104,9 @@ Before running the plugin, build your Flutter application. Obfuscation is encour The `--extra-gen-snapshot-options=--save-obfuscation-map=build/app/obfuscation.map.json` option is required to generate the symbol map file which is used to make the - obfuscated Flutter issue titles readable on iOS and Android. Make sure to point - the `dart_symbol_map_path` option to the location of the `obfuscation.map.json` file. + obfuscated Flutter issue titles readable on iOS and Android. Make sure to + point the `dart_symbol_map_path` option to the location of the + `obfuscation.map.json` file. ```bash {tabTitle: Mobile & Desktop} @@ -185,31 +186,31 @@ The **Key** column refers to the option name used in: When available, environment variable names are listed in the **Environment Variable** column. -| Key | Environment Variable | Type | Default | Description | -| -------------------------- | ------------------- | ------- | --------------------------------------------- | ---------------------------------------------------------------------------------- | -| `project` | `SENTRY_PROJECT` | string | | **(Required)** Your project's name (e.g., `sentry-flutter`) | -| `org` | `SENTRY_ORG` | string | | **(Required)** Your organization's slug (e.g., `sentry-sdks`) | -| `auth_token` | `SENTRY_AUTH_TOKEN` | string | | **(Required)** The Sentry auth token | -| `upload_debug_symbols` | — | boolean | `true` | Enables or disables automatic upload of debug symbols | -| `upload_source_maps` | — | boolean | `false` | Enables or disables automatic upload of source maps (Flutter Web) | -| `upload_sources` | — | boolean | `false` | Enables or disables source code upload | -| `dart_symbol_map_path` | — | string | | Path to the Dart symbol map file for readable obfuscated issue titles | -| `release` | `SENTRY_RELEASE` | string | `name@version` from pubspec | The release version for source maps | -| `dist` | `SENTRY_DIST` | string | Build number (after `+` in version) | Custom distribution identifier | -| `build_path` | — | string | `build` | Base build directory | -| `web_build_path` | — | string | `web` | The web build folder path relative to `build_path` | -| `symbols_path` | — | string | `.` | The directory containing debug symbols. This recursively searches for debug files. | -| `url` | `SENTRY_URL` | string | | The URL of your Sentry instance (for self-hosted) | -| `url_prefix` | — | string | | URL prefix for JS source maps (e.g., `~/`). Required for non-root web deployments | -| `legacy_web_symbolication` | — | boolean | `false` | Uses legacy symbolication for Flutter Web. See [Debug IDs](#debug-ids-flutter-web) | -| `commits` | — | string | `auto` | Release commits integration | -| `ignore_missing` | — | boolean | `false` | Ignore missing commits previously used in the release | -| `wait_for_processing` | — | boolean | `false` | Whether to wait for server-side processing of uploaded files | -| `log_level` | `SENTRY_LOG_LEVEL` | string | `warn` | Log level for sentry-cli: `trace`, `debug`, `info`, `warn`, `error` | -| `bin_dir` | — | string | `.dart_tool/pub/bin/sentry_dart_plugin` | Folder where the plugin downloads the sentry-cli binary | -| `bin_path` | — | string | | Path to a sentry-cli binary to use instead of downloading | -| `sentry_cli_cdn_url` | `SENTRYCLI_CDNURL` | string | `https://downloads.sentry-cdn.com/sentry-cli` | Alternative place to download sentry-cli | -| `sentry_cli_version` | — | string | | Override the sentry-cli version to download | +| Key | Environment Variable | Type | Default | Description | +| -------------------------- | -------------------- | ------- | --------------------------------------------- | ---------------------------------------------------------------------------------- | +| `project` | `SENTRY_PROJECT` | string | | **(Required)** Your project's name (e.g., `sentry-flutter`) | +| `org` | `SENTRY_ORG` | string | | **(Required)** Your organization's slug (e.g., `sentry-sdks`) | +| `auth_token` | `SENTRY_AUTH_TOKEN` | string | | **(Required)** The Sentry auth token | +| `upload_debug_symbols` | — | boolean | `true` | Enables or disables automatic upload of debug symbols | +| `upload_source_maps` | — | boolean | `false` | Enables or disables automatic upload of source maps (Flutter Web) | +| `upload_sources` | — | boolean | `false` | Enables or disables source code upload | +| `dart_symbol_map_path` | — | string | | Path to the Dart symbol map file for readable obfuscated issue titles | +| `release` | `SENTRY_RELEASE` | string | `name@version` from pubspec | The release version for source maps | +| `dist` | `SENTRY_DIST` | string | Build number (after `+` in version) | Custom distribution identifier | +| `build_path` | — | string | `build` | Base build directory | +| `web_build_path` | — | string | `web` | The web build folder path relative to `build_path` | +| `symbols_path` | — | string | `.` | The directory containing debug symbols. This recursively searches for debug files. | +| `url` | `SENTRY_URL` | string | | The URL of your Sentry instance (for self-hosted) | +| `url_prefix` | — | string | | URL prefix for JS source maps (e.g., `~/`). Required for non-root web deployments | +| `legacy_web_symbolication` | — | boolean | `false` | Uses legacy symbolication for Flutter Web. See [Debug IDs](#debug-ids-flutter-web) | +| `commits` | — | string | `auto` | Release commits integration | +| `ignore_missing` | — | boolean | `false` | Ignore missing commits previously used in the release | +| `wait_for_processing` | — | boolean | `false` | Whether to wait for server-side processing of uploaded files | +| `log_level` | `SENTRY_LOG_LEVEL` | string | `warn` | Log level for sentry-cli: `trace`, `debug`, `info`, `warn`, `error` | +| `bin_dir` | — | string | `.dart_tool/pub/bin/sentry_dart_plugin` | Folder where the plugin downloads the sentry-cli binary | +| `bin_path` | — | string | | Path to a sentry-cli binary to use instead of downloading | +| `sentry_cli_cdn_url` | `SENTRYCLI_CDNURL` | string | `https://downloads.sentry-cdn.com/sentry-cli` | Alternative place to download sentry-cli | +| `sentry_cli_version` | — | string | | Override the sentry-cli version to download | ## Features @@ -217,28 +218,28 @@ The Sentry Dart Plugin uploads debug symbols and source maps to make your Flutte ### Mobile & Desktop — Non-Obfuscated Builds -| Feature | iOS | Android | macOS | Windows | Linux | -| -------------------- | --- | ------- | ----- | ------- | ----- | +| Feature | iOS | Android | macOS | Windows | Linux | +| ------------------------ | --- | ------- | ----- | ------- | ----- | | Symbolicated Stacktrace | ✓ | ✓ | ✓ | ✓ | ✓ | -| Source Context | ✓\* | ✓\* | ✓\* | ✓\* | ✓\* | +| Source Context | ✓\* | ✓\* | ✓\* | ✓\* | ✓\* | | Symbolicated Issue Title | ✓ | ✓ | ✓ | ✓ | ✓ | ### Mobile & Desktop — Obfuscated Builds (`--obfuscate`) -| Feature | iOS | Android | macOS | Windows | Linux | -| -------------------- | ------- | ------- | ------------- | ------------- | ------------- | -| Symbolicated Stacktrace | ✓ | ✓ | ✓ | ✓ | ✓ | -| Source Context | ✓\* | ✓\* | ✓\* | ✓\* | ✓\* | -| Symbolicated Issue Title | ✓ | ✓ | Not Supported | Not Supported | Not Supported | +| Feature | iOS | Android | macOS | Windows | Linux | +| ------------------------ | --- | ------- | ------------- | ------------- | ------------- | +| Symbolicated Stacktrace | ✓ | ✓ | ✓ | ✓ | ✓ | +| Source Context | ✓\* | ✓\* | ✓\* | ✓\* | ✓\* | +| Symbolicated Issue Title | ✓ | ✓ | Not Supported | Not Supported | Not Supported | \*Requires `--split-debug-info` build flag supplied to the `flutter build` command ### Web (Always Minified) -| Feature | Support | -| -------------------- | ------------- | +| Feature | Support | +| ------------------------ | ------------- | | Symbolicated Stacktrace | ✓ | -| Source Context | ✓ | +| Source Context | ✓ | | Symbolicated Issue Title | Not Supported | ## Troubleshooting From dcd4d592d20470318e1e28111285a659884c10fe Mon Sep 17 00:00:00 2001 From: Giancarlo Buenaflor Date: Thu, 28 May 2026 15:50:33 +0200 Subject: [PATCH 08/13] docs(flutter): Fix cross-platform ANR links Use regular links for Android and Apple docs from the Flutter ANR and App Hangs page. Co-authored-by: Cursor --- .../dart/guides/flutter/configuration/anr-app-hangs.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/platforms/dart/guides/flutter/configuration/anr-app-hangs.mdx b/docs/platforms/dart/guides/flutter/configuration/anr-app-hangs.mdx index 15dc7d242d08d..16b4e0b670f4f 100644 --- a/docs/platforms/dart/guides/flutter/configuration/anr-app-hangs.mdx +++ b/docs/platforms/dart/guides/flutter/configuration/anr-app-hangs.mdx @@ -32,7 +32,7 @@ await SentryFlutter.init( ); ``` -For more configuration details, see the Android ANR documentation and the Apple App Hangs documentation. +For more configuration details, see the Android ANR documentation and the Apple App Hangs documentation. ## Pause App Hang Tracking From da87cc4637f2f0c4da9158b6ca4e8349aaaf2260 Mon Sep 17 00:00:00 2001 From: Giancarlo Buenaflor Date: Mon, 1 Jun 2026 14:58:35 +0200 Subject: [PATCH 09/13] docs(flutter): Reorder Dart Plugin symbolication setup Move the Android Gradle Plugin configuration ahead of the build step since it runs during the Android build, add an iOS/macOS dSYM upload note, and simplify the ANR and App Hangs symbolication pointer. Co-authored-by: Cursor --- .../flutter/configuration/anr-app-hangs.mdx | 4 +- .../dart-plugin/dart.flutter.mdx | 88 +++++++++---------- 2 files changed, 42 insertions(+), 50 deletions(-) diff --git a/docs/platforms/dart/guides/flutter/configuration/anr-app-hangs.mdx b/docs/platforms/dart/guides/flutter/configuration/anr-app-hangs.mdx index 16b4e0b670f4f..cc3058838a62b 100644 --- a/docs/platforms/dart/guides/flutter/configuration/anr-app-hangs.mdx +++ b/docs/platforms/dart/guides/flutter/configuration/anr-app-hangs.mdx @@ -48,9 +48,9 @@ SentryFlutter.resumeAppHangTracking(); ## Readable Stack Traces -Since ANR and App Hang events can include frames from Dart, Java/Kotlin, Swift/Objective-C, and C/C++ code, Sentry needs the corresponding debug files to make each frame readable. +Since ANR and App Hang events can include frames from Dart, Java/Kotlin, Swift/Objective-C, and C/C++ code, some frames require platform-specific debug files to appear readable in Sentry. -See the Sentry Dart Plugin documentation for the debug files required on Android, iOS, and macOS, including Android R8/ProGuard mapping files. +See the Sentry Dart Plugin documentation for the debug files required on Android, iOS, and macOS. ## Platform Details diff --git a/platform-includes/debug-symbols/dart-plugin/dart.flutter.mdx b/platform-includes/debug-symbols/dart-plugin/dart.flutter.mdx index d36d9ad644099..44a5b249d3139 100644 --- a/platform-includes/debug-symbols/dart-plugin/dart.flutter.mdx +++ b/platform-includes/debug-symbols/dart-plugin/dart.flutter.mdx @@ -96,6 +96,40 @@ When the same value is set in multiple places, the highest priority wins in this For the full list of configuration options, see the [Configuration Reference](#configuration-reference) section. +## Configure the Android Gradle Plugin + +For Android, the Sentry Android Gradle Plugin uploads the files needed to symbolicate JVM and native frames. It runs automatically during your Android build, so configure it before building your app. + +After installing the [Sentry Android Gradle Plugin](/platforms/android/configuration/gradle/), configure it in your `app/build.gradle.kts` file: + +```kotlin {filename: app/build.gradle.kts} +sentry { + // Disable auto-installation of the Sentry Android SDK since it's already installed by the Sentry Flutter SDK + autoInstallation { + enabled.set(false) + } + + // Enable native symbol upload. This allows Sentry to symbolicate + // stack traces that occur in the native Android layer, such as ANR events. + uploadNativeSymbols.set(true) + + // The slug of the Sentry organization to use for uploading native symbols and proguard mappings/source contexts. + org.set("___ORG_SLUG___") + + // The slug of the Sentry project to use for uploading proguard mappings/source contexts. + projectName.set("___PROJECT_SLUG___") + + // The authentication token to use for uploading proguard mappings/source contexts. + // WARNING: Do not expose this token in your build.gradle files, but rather set an environment + // variable and read it into this property. + authToken.set(System.getenv("SENTRY_AUTH_TOKEN")) +} +``` + +ProGuard and R8 mapping upload is enabled automatically by the Sentry Android Gradle Plugin. The `uploadNativeSymbols` option enables uploading native symbols for native Android stack frames. + +Alternatively, you can use the [Sentry CLI](/cli/dif/#uploading-files) to manually upload mapping files. For more information, see the [Android Gradle Plugin guide](/platforms/android/configuration/gradle). + ## Building Your Application Before running the plugin, build your Flutter application. Obfuscation is encouraged for production builds, and will make uploading debug symbols necessary to get readable stack traces. @@ -118,6 +152,12 @@ flutter build --obfuscate --split-debug-info= --extra flutter build web --release --source-maps ``` + + +For iOS and macOS, we recommend running the Sentry Dart Plugin even for non-obfuscated builds to upload the dSYM files Xcode generates. This lets Sentry symbolicate native Swift, Objective-C, and C/C++ stack traces. + + + ## Running the Plugin After building your application, run the plugin to upload debug symbols: @@ -126,54 +166,6 @@ After building your application, run the plugin to upload debug symbols: flutter pub run sentry_dart_plugin ``` -## ANR and App Hang Symbolication - -ANR and App Hang detection happens outside the Dart runtime and can include frames from Dart, Java/Kotlin, Swift/Objective-C, and native code. To make stack traces readable, Sentry needs the debug files generated for the platform you're building. - -### Android ANR Symbolication - -If an Android ANR event includes Dart frames from Flutter AOT code, those frames need the `.symbols` files generated by `--split-debug-info` to be symbolicated in Sentry. - -Without `--split-debug-info`, Dart frames in Android ANR events may appear as unresolved addresses in `libapp.so`. The same `.symbols` files also provide the debug ID Sentry uses to match source bundles for source context. - -`mapping.txt` files only deobfuscate JVM frames from Kotlin or Java code, and native debug symbols only symbolicate NDK frames from C or C++ libraries. They don't replace Flutter `.symbols` files for Dart frames. - -### iOS and macOS App Hang Symbolication - -For iOS and macOS App Hang events, Sentry needs the dSYM files Xcode generates when building your app. - -The Sentry Dart Plugin uploads those dSYM files after your build. You don't need `--split-debug-info` just to symbolicate App Hang stack traces on iOS or macOS. - -## Android ProGuard Integration - -Uploading ProGuard mapping files is recommended in order to see symbolicated stack traces for errors that occur in the native Android layer: - -- **Use the Sentry Android Gradle Plugin (Recommended).** - - After installing the [Sentry Android Gradle Plugin](/platforms/android/configuration/gradle/), set `autoInstallation` to `false` in your `app/build.gradle` file: - - ```groovy {filename: app/build.gradle} - sentry { - autoInstallation { - enabled = false - } - } - ``` - - This avoids conflicts because Sentry Flutter already ships with a compatible Sentry Android SDK. - - Follow the [Android Gradle Plugin guide](/platforms/android/configuration/gradle/#proguardr8--dexguard) to complete the ProGuard mapping setup. - -- **Use the Sentry CLI.** - - Alternatively, you can use the [Sentry CLI](/cli/dif/#uploading-files) to manually upload mapping files. - - - -Sentry's Flutter SDK doesn't currently support the `uploadNativeSymbols` flag from the Sentry Gradle Plugin. - - - ## Configuration Reference The following table lists all available configuration options for the Sentry Dart Plugin. From 2282b3378278c10bb43b76e861ed23db94fefc8c Mon Sep 17 00:00:00 2001 From: Giancarlo Buenaflor Date: Tue, 2 Jun 2026 10:53:34 +0200 Subject: [PATCH 10/13] Update pauseAppHangTracking to use await --- .../dart/guides/flutter/configuration/anr-app-hangs.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/platforms/dart/guides/flutter/configuration/anr-app-hangs.mdx b/docs/platforms/dart/guides/flutter/configuration/anr-app-hangs.mdx index cc3058838a62b..e36cb47f49f5b 100644 --- a/docs/platforms/dart/guides/flutter/configuration/anr-app-hangs.mdx +++ b/docs/platforms/dart/guides/flutter/configuration/anr-app-hangs.mdx @@ -39,11 +39,11 @@ For more configuration details, see the Date: Tue, 2 Jun 2026 16:22:47 +0200 Subject: [PATCH 13/13] docs(flutter): Make Android Gradle Plugin setup an optional step Wrap the Sentry Android Gradle Plugin configuration in an Expandable since it is only required when R8 or ProGuard is enabled. This keeps the debug symbols guide focused for the common case where JVM stack traces are already readable. Co-Authored-By: Claude Co-authored-by: Cursor --- .../debug-symbols/dart-plugin/dart.flutter.mdx | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/platform-includes/debug-symbols/dart-plugin/dart.flutter.mdx b/platform-includes/debug-symbols/dart-plugin/dart.flutter.mdx index 46c5f2d79ef89..47b9baf0c0e89 100644 --- a/platform-includes/debug-symbols/dart-plugin/dart.flutter.mdx +++ b/platform-includes/debug-symbols/dart-plugin/dart.flutter.mdx @@ -98,13 +98,11 @@ For the full list of configuration options, see the [Configuration Reference](#c ## Configure the Android Gradle Plugin -For Android, the Sentry Android Gradle Plugin uploads the files needed to symbolicate JVM frames. It runs automatically during your Android build, so configure it before building your app. - - +This step is only required if R8 or ProGuard is enabled for your Android build. Without it, JVM stack traces are already readable and no mapping file upload is required. -You only need to configure the Sentry Android Gradle Plugin if R8 or ProGuard is enabled for your Android build. Without it, JVM stack traces are already readable and no mapping file upload is required. + - +For Android, the Sentry Android Gradle Plugin uploads the files needed to symbolicate JVM frames. It runs automatically during your Android build, so configure it before building your app. After installing the [Sentry Android Gradle Plugin](/platforms/android/configuration/gradle/), configure it in your `app/build.gradle.kts` file: @@ -132,6 +130,8 @@ ProGuard mapping upload is enabled automatically by the Sentry Android Gradle Pl Alternatively, you can use the [Sentry CLI](/cli/dif/#proguard-mapping-upload) to manually upload ProGuard mapping files. For more information, see the [Android Gradle Plugin guide](/platforms/android/configuration/gradle). + + ## Building Your Application Before running the plugin, build your Flutter application. Obfuscation is encouraged for production builds, and will make uploading debug symbols necessary to get readable stack traces. @@ -156,7 +156,8 @@ flutter build web --release --source-maps -For iOS and macOS, we recommend running the Sentry Dart Plugin even for non-obfuscated builds to upload the dSYM files Xcode generates. This lets Sentry symbolicate native Swift, Objective-C, and C/C++ stack traces. +Even if you don't use `split-debug-info` or `obfuscate`, we recommend uploading all available debug files with the Sentry Dart Plugin. +The more you upload, the more Sentry can symbolicate out of the box — including native frames (for example, on iOS) that aren't readable otherwise.