diff --git a/docs/platforms/dart/common/debug-symbols/dart-plugin.mdx b/docs/platforms/dart/common/debug-symbols/dart-plugin.mdx deleted file mode 100644 index 67335d13a51f7..0000000000000 --- a/docs/platforms/dart/common/debug-symbols/dart-plugin.mdx +++ /dev/null @@ -1,9 +0,0 @@ ---- -title: Sentry Dart Plugin -description: "Learn how to use the Sentry Dart Plugin to automatically upload debug symbols for your Dart application." -sidebar_order: 1 ---- - -The [Sentry Dart Plugin](https://github.com/getsentry/sentry-dart-plugin) is the recommended way to upload debug symbols for Dart applications. It automates the upload process for Android, iOS, macOS, and Web, making it seamless to provide Sentry with the necessary files for symbolication. - - \ No newline at end of file diff --git a/docs/platforms/dart/common/debug-symbols/index.mdx b/docs/platforms/dart/common/debug-symbols/index.mdx index 85864c4fa403b..58182538211bc 100644 --- a/docs/platforms/dart/common/debug-symbols/index.mdx +++ b/docs/platforms/dart/common/debug-symbols/index.mdx @@ -1,35 +1,9 @@ --- title: Debug Symbols -description: "Learn about uploading debug symbols to enable symbolication of stack traces in your Dart applications." sidebar_order: 3 --- -Debug symbols are essential for understanding stack traces in your Dart application when errors occur. Without debug symbols, stack traces from minified or obfuscated code can be difficult or impossible to interpret. +Sentry currently does not support symbolication or debug symbol uploads for pure Dart applications. +This feature is being tracked in our GitHub issue: [sentry-dart/#1508](https://github.com/getsentry/sentry-dart/issues/1508). - - -Sentry currently doesn't support uploading debug symbols for pure Dart applications. Please see the [Flutter debug symbols documentation](/platforms/dart/guides/flutter/debug-symbols/) for Flutter applications. This feature is being tracked in our GitHub Issue: [sentry-dart/#1508](https://github.com/getsentry/sentry-dart/issues/1508). - - - -## What Are Debug Symbols? - -Debug symbols provide the necessary information to convert program addresses back to function names, source file names, and line numbers. When you build a Dart application, especially with obfuscation or optimization enabled, this information is typically removed from the main application bundle to reduce size. - -## When to Upload Debug Symbols - -With default settings, complete stack traces are available in your Dart 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. - -## Upload Methods - -Sentry offers several methods to upload debug symbols for Dart applications: - -1. **[Sentry Dart Plugin (Recommended)](/platforms/dart/debug-symbols/dart-plugin)** - The easiest way to automatically upload debug symbols for iOS, Android, Desktop and Web. - -2. **[Manual Upload Options](/platforms/dart/debug-symbols/manual-upload):** - - [iOS and macOS](/platforms/apple/dsym/) - Upload dSYM files for symbolication of Apple platform crashes. - - [Android](/cli/dif/#uploading-files) - Upload mapping files manually using the Sentry CLI. - - [Android NDK](/cli/dif/#uploading-files) - Upload ELF DWARF debug files for native code crashes. - - [Web](/cli/releases/#upload-source-maps) - Upload source maps for Flutter web applications. - -Choose the method that best suits your workflow and platform requirements. For most users, the Sentry Dart Plugin provides the simplest solution across all platforms. \ No newline at end of file +See the [Flutter debug symbols documentation](/platforms/dart/guides/flutter/debug-symbols/) for Flutter applications. diff --git a/docs/platforms/dart/common/debug-symbols/manual-upload.mdx b/docs/platforms/dart/common/debug-symbols/manual-upload.mdx deleted file mode 100644 index 4bce55f591d5c..0000000000000 --- a/docs/platforms/dart/common/debug-symbols/manual-upload.mdx +++ /dev/null @@ -1,9 +0,0 @@ ---- -title: Manual Upload -description: "Learn how to manually upload debug symbols for your Dart applications." -sidebar_order: 2 ---- - -If you choose not to use the Sentry Dart Plugin, you can manually upload debug symbols for your Dart applications. This page provides instructions for different platforms. - - \ No newline at end of file diff --git a/docs/platforms/dart/guides/flutter/debug-symbols/dart-plugin.mdx b/docs/platforms/dart/guides/flutter/debug-symbols/dart-plugin.mdx index 67335d13a51f7..2022554c1e9cd 100644 --- a/docs/platforms/dart/guides/flutter/debug-symbols/dart-plugin.mdx +++ b/docs/platforms/dart/guides/flutter/debug-symbols/dart-plugin.mdx @@ -1,9 +1,9 @@ --- title: Sentry Dart Plugin -description: "Learn how to use the Sentry Dart Plugin to automatically upload debug symbols for your Dart application." +description: "Learn how to use the Sentry Dart Plugin to automatically upload debug symbols for your Flutter application." sidebar_order: 1 --- -The [Sentry Dart Plugin](https://github.com/getsentry/sentry-dart-plugin) is the recommended way to upload debug symbols for Dart applications. It automates the upload process for Android, iOS, macOS, and Web, making it seamless to provide Sentry with the necessary files for symbolication. +The [Sentry Dart Plugin](https://github.com/getsentry/sentry-dart-plugin) is the recommended way to upload debug symbols for Flutter applications. It automates the upload process for Android, iOS, macOS, and Web, making it seamless to provide Sentry with the necessary files for symbolication. \ No newline at end of file diff --git a/docs/platforms/dart/guides/flutter/debug-symbols/index.mdx b/docs/platforms/dart/guides/flutter/debug-symbols/index.mdx index 4d46a7adf08c5..4107587bbe60b 100644 --- a/docs/platforms/dart/guides/flutter/debug-symbols/index.mdx +++ b/docs/platforms/dart/guides/flutter/debug-symbols/index.mdx @@ -1,29 +1,23 @@ --- title: Debug Symbols -description: "Learn about uploading debug symbols to enable symbolication of stack traces in your Dart applications." +description: "Learn about uploading debug symbols to enable symbolication of stack traces in your Flutter applications." sidebar_order: 3 --- -Debug symbols are essential for understanding stack traces in your Dart application when errors occur. Without debug symbols, stack traces from minified or obfuscated code can be difficult or impossible to interpret. +Debug symbols are essential for understanding stack traces in your Flutter application when errors occur. Without debug symbols, stack traces from minified or obfuscated code can be difficult or impossible to interpret. ## What Are Debug Symbols? -Debug symbols provide the necessary information to convert program addresses back to function names, source file names, and line numbers. When you build a Dart application, especially with obfuscation or optimization enabled, this information is typically removed from the main application bundle to reduce size. +Debug symbols provide the necessary information to convert program addresses back to function names, source file names, and line numbers. When you build a Flutter application, especially with obfuscation or optimization enabled, this information is typically removed from the main application bundle to reduce size. ## When to Upload Debug Symbols -With default settings, complete stack traces are available in your Dart 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. +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. ## Upload Methods -Sentry offers several methods to upload debug symbols for Dart applications: +Sentry offers several methods to upload debug symbols for Flutter applications: -1. **[Sentry Dart Plugin (Recommended)](/platforms/dart/guides/flutter/debug-symbols/dart-plugin)** - The easiest way to automatically upload debug symbols for iOS, Android, and Web. +1. **[Sentry Dart Plugin (Recommended)](/platforms/dart/guides/flutter/debug-symbols/dart-plugin)** - The easiest and most reliable way to upload debug symbols for Flutter applications. It automatically processes, filters, and uploads the correct symbol files for iOS, Android, and Web - significantly reducing the chances of misconfiguration. -2. **[Manual Upload Options](/platforms/dart/guides/flutter/debug-symbols/manual-upload):** - - [iOS and macOS](/platforms/apple/dsym/) - Upload dSYM files for symbolication of Apple platform crashes. - - [Android](/cli/dif/#uploading-files) - Upload mapping files manually using the Sentry CLI. - - [Android NDK](/cli/dif/#uploading-files) - Upload ELF DWARF debug files for native code crashes. - - [Web](/cli/releases/#upload-source-maps) - Upload source maps for Flutter web applications. - -Choose the method that best suits your workflow and platform requirements. For most users, the Sentry Dart Plugin provides the simplest solution across all platforms. \ No newline at end of file +2. **[Manual Upload Options](/platforms/dart/guides/flutter/debug-symbols/manual-upload)** - Because this method is more complex, requires additional manual steps, and is not currently documented, we do not recommend using it unless absolutely necessary. diff --git a/docs/platforms/dart/guides/flutter/debug-symbols/manual-upload.mdx b/docs/platforms/dart/guides/flutter/debug-symbols/manual-upload.mdx index 4bce55f591d5c..bb30f91c985fb 100644 --- a/docs/platforms/dart/guides/flutter/debug-symbols/manual-upload.mdx +++ b/docs/platforms/dart/guides/flutter/debug-symbols/manual-upload.mdx @@ -1,9 +1,9 @@ --- title: Manual Upload -description: "Learn how to manually upload debug symbols for your Dart applications." +description: "Learn how to manually upload debug symbols for your Flutter applications." sidebar_order: 2 --- -If you choose not to use the Sentry Dart Plugin, you can manually upload debug symbols for your Dart applications. This page provides instructions for different platforms. +If you choose not to use the Sentry Dart Plugin, you can manually upload debug symbols for your Flutter applications. This page provides instructions for different platforms. \ No newline at end of file diff --git a/platform-includes/debug-symbols/dart-plugin/dart.flutter.mdx b/platform-includes/debug-symbols/dart-plugin/dart.flutter.mdx index 4feac0924eb38..8464a8b484154 100644 --- a/platform-includes/debug-symbols/dart-plugin/dart.flutter.mdx +++ b/platform-includes/debug-symbols/dart-plugin/dart.flutter.mdx @@ -39,6 +39,14 @@ sentry: # ___PRODUCT_OPTION_END___ source-maps ``` + + +For iOS and Android builds, source context is only supported if you build the Flutter app using the `--split-debug-info` flag. + +Additionally source context currently only covers code in the main app package. For example, if your main app package depends on an internal package or a third-party package and an error occurs in that dependency, its source context will not be shown. + + + The `upload_debug_symbols` option defaults to `true` when not specified. diff --git a/platform-includes/debug-symbols/dart-plugin/dart.mdx b/platform-includes/debug-symbols/dart-plugin/dart.mdx deleted file mode 100644 index 4feac0924eb38..0000000000000 --- a/platform-includes/debug-symbols/dart-plugin/dart.mdx +++ /dev/null @@ -1,154 +0,0 @@ -## Installation - -In your `pubspec.yaml`, add `sentry_dart_plugin` as a new dev dependency: - -```yaml {filename: pubspec.yaml} -dev_dependencies: - sentry_dart_plugin: ^{{@inject packages.version('sentry.dart.plugin', '2.0.0') }} -``` - -## Configuration - -The Sentry Dart Plugin requires basic configuration in your `pubspec.yaml` file: - - - -```yaml {filename:pubspec.yaml} -sentry: - project: ___PROJECT_SLUG___ - org: ___ORG_SLUG___ - auth_token: ___ORG_AUTH_TOKEN___ - # Absolute or relative path to the Dart symbol map file - # Used to make obfuscated Flutter issue titles readable on iOS and Android - # See the "Building Your Application" section below for more details on how to generate the symbol map file - # Available since version 3.2.0 of the Sentry Dart Plugin - dart_symbol_map_path: build/app/obfuscation.map.json - # ___PRODUCT_OPTION_START___ source-context - # Enable source context - upload_sources: true - # ___PRODUCT_OPTION_END___ source-context - # ___PRODUCT_OPTION_START___ source-maps - # Enable source maps (only relevant for Flutter Web) - upload_source_maps: true - # ___PRODUCT_OPTION_END___ source-maps -``` - - -The `upload_debug_symbols` option defaults to `true` when not specified. - - -### Alternative Configuration Methods - -In addition to configuring the plugin in `pubspec.yaml`, you can use: -- Environment variables -- Properties file - -For more information, read the [Sentry Dart Plugin README](https://github.com/getsentry/sentry-dart-plugin/tree/main?tab=readme-ov-file#configuration-optional). - -## Building Your Application - -Before running the plugin, build your Flutter application with one of the following commands. Obfuscated is encouraged for production builds, and will make uploading debug symbols necessary to get readable stack traces. - - -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 set the `dart_symbol_map_path` option in your `pubspec.yaml` file to the path of the `obfuscation.map.json` file. - - -```bash {tabTitle: Obfuscated} -flutter build apk --obfuscate --split-debug-info= --extra-gen-snapshot-options=--save-obfuscation-map=build/app/obfuscation.map.json -flutter build ios --obfuscate --split-debug-info= --extra-gen-snapshot-options=--save-obfuscation-map=build/app/obfuscation.map.json -flutter build macos --obfuscate --split-debug-info= --extra-gen-snapshot-options=--save-obfuscation-map=build/app/obfuscation.map.json -flutter build windows --obfuscate --split-debug-info= --extra-gen-snapshot-options=--save-obfuscation-map=build/app/obfuscation.map.json -flutter build linux --obfuscate --split-debug-info= --extra-gen-snapshot-options=--save-obfuscation-map=build/app/obfuscation.map.json -``` - -```bash {tabTitle: Flutter Web} -flutter build web --release --source-maps -``` - -For Flutter web run `flutter build web --release --source-maps` to generate source maps. - - -## Running the Plugin - -After building your application, run the plugin to upload debug symbols: - -```bash -flutter pub run sentry_dart_plugin -``` - - - -If you don't obfuscate your build, the plugin won't upload debug symbols. Additionally, source context (viewing source code in stack trace frames on Sentry) is not currently supported for non-obfuscated builds. GitHub Issue: [sentry-dart/#1314](https://github.com/getsentry/sentry-dart/issues/1314) - - - -## Android ProGuard Integration - -If you have ProGuard (`minifyEnabled`) enabled and you want to see proper native Android stacktraces, you must upload Android Proguard/R8 mapping files. You have two options: - -1. **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 is necessary because Sentry Flutter already ships with a compatible Sentry Android SDK, so we need to avoid conflicts. - - Follow the [Android Gradle Plugin guide](/platforms/android/configuration/gradle/#proguardr8--dexguard) to complete the ProGuard mapping setup. - -2. **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: - -
- -| Option | Type | Default | Description | Environment Variable | -|--------|------|---------|-------------|---------------------| -| `project` | string | | **Required.** Your project's name (e.g., `sentry-flutter`) | `SENTRY_PROJECT` | -| `org` | string | | **Required.** Your organization's slug (e.g., `sentry-sdks`) | `SENTRY_ORG` | -| `auth_token` | string | | **Required.** The Sentry auth token | `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 | | -| `upload_sources` | boolean | `false` | Enables or disables source code upload | | -| `dart_symbol_map_path` | string | | Absolute or relative path to the Dart symbol map file used to make obfuscated Flutter issue titles readable on iOS and Android | | -| `url` | string | | The URL of your Sentry instance | `SENTRY_URL` | -| `url_prefix` | URL prefix for JS source maps | e.g. ~/app/ (string) | no | - | -| `wait_for_processing` | boolean | `false` | Whether to wait for server-side processing of uploaded files | | -| `log_level` | string | `warn` | Configures the log level for sentry-cli (`trace`, `debug`, `info`, `warn`, `error`) | `SENTRY_LOG_LEVEL` | -| `release` | string | `name@version` from pubspec | The release version for source maps | `SENTRY_RELEASE` | -| `dist` | string | | Custom distribution identifier | `SENTRY_DIST` | -| `web_build_path` | string | `build/web` | The web build folder path | | -| `commits` | string | `auto` | Release commits integration | | -| `ignore_missing` | boolean | `false` | Ignore missing commits previously used in the release | | -| `bin_dir` | string | `.dart_tool/pub/bin/sentry_dart_plugin` | The 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` | string | `https://downloads.sentry-cdn.com/sentry-cli` | Alternative place to download sentry-cli | `SENTRYCLI_CDNURL` | - -
- -## Troubleshooting - -If you encounter any issues with the Sentry Dart Plugin, refer to [Troubleshooting - Sentry Dart Plugin](/platforms/dart/guides/flutter/troubleshooting#sentry-dart-plugin) for solutions to common problems.