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 00000000000000..e36cb47f49f5b3 --- /dev/null +++ b/docs/platforms/dart/guides/flutter/configuration/anr-app-hangs.mdx @@ -0,0 +1,60 @@ +--- +title: ANR and App Hangs +description: "Learn how Sentry detects and configures ANRs and App Hangs in Flutter apps." +sidebar_order: 45 +--- + +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. + +**This feature is available on Android, iOS, and macOS.** + +## What Gets Reported + +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 + +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 + }, +); +``` + +For more configuration details, see the Android ANR documentation and the Apple App Hangs documentation. + +## Pause App Hang Tracking + +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 +await SentryFlutter.pauseAppHangTracking(); + +// Run code that you don't want Sentry to report as an app hang. + +await 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, 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. + +## 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 8250787116a662..fe969649980f2e 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 @@ -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/debug-symbols/index.mdx b/docs/platforms/dart/guides/flutter/debug-symbols/index.mdx index a5c47aadb4af87..b1347b9c252586 100644 --- a/docs/platforms/dart/guides/flutter/debug-symbols/index.mdx +++ b/docs/platforms/dart/guides/flutter/debug-symbols/index.mdx @@ -15,6 +15,9 @@ Debug symbols provide the necessary information to convert program addresses bac With default settings, complete stack traces are available in your Flutter errors out of the box, unless you use [`split-debug-info`](https://flutter.dev/docs/perf/app-size#reducing-app-size) and [`obfuscate`](https://flutter.dev/docs/deployment/obfuscate) flags. In these cases, you must upload the debug information files generated by the build, so Sentry can show proper 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. + ## Upload Methods Sentry offers several methods to upload debug symbols for Flutter applications: diff --git a/docs/platforms/dart/guides/flutter/features/index.mdx b/docs/platforms/dart/guides/flutter/features/index.mdx index 7dc0c7e59576b1..fa1dd06a366f76 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: @@ -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 b56378a210b36e..47b9baf0c0e899 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: @@ -96,6 +96,42 @@ 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 + +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. + + + +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: + +```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) + } + + // The slug of the Sentry organization to use for uploading ProGuard mappings. + org.set("___ORG_SLUG___") + + // The slug of the Sentry project to use for uploading ProGuard mappings. + projectName.set("___PROJECT_SLUG___") + + // The authentication token to use for uploading ProGuard mappings. + // 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 mapping upload is enabled automatically by the Sentry Android Gradle Plugin. +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. @@ -104,8 +140,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} @@ -117,6 +154,13 @@ flutter build --obfuscate --split-debug-info= --extra flutter build web --release --source-maps ``` + + +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. + + + ## Running the Plugin After building your application, run the plugin to upload debug symbols: @@ -125,36 +169,6 @@ After building your application, run the plugin to upload debug symbols: flutter pub run sentry_dart_plugin ``` -## 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. @@ -167,31 +181,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 @@ -199,28 +213,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 diff --git a/platform-includes/debug-symbols/manual-upload/dart.mdx b/platform-includes/debug-symbols/manual-upload/dart.mdx index f197e7fb3c1a16..51c4d47c09f4f4 100644 --- a/platform-includes/debug-symbols/manual-upload/dart.mdx +++ b/platform-includes/debug-symbols/manual-upload/dart.mdx @@ -18,14 +18,8 @@ For native code crashes in Android applications, you need to upload ELF DWARF de If you're using a version of `sentry_flutter` earlier than 5.1, native symbolication on Android requires a specific configuration. Refer to [Troubleshooting](/platforms/dart/guides/flutter/troubleshooting/#native-symbolication-on-android) for more information. - - -Sentry's Flutter SDK doesn't currently support the `uploadNativeSymbols` flag from the [Sentry Gradle Plugin](/platforms/android/configuration/gradle/). - - - ## Web For web applications, you need to upload source maps to get readable stack traces. -[Learn how to upload Source Maps](/cli/releases/#upload-source-maps) \ No newline at end of file +[Learn how to upload Source Maps](/cli/releases/#upload-source-maps)