From d7fc36cda5b2c9a9361b3a8936ad8fa175a98c49 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Denis=20Andra=C5=A1ec?= Date: Tue, 20 Jun 2023 15:44:18 +0000 Subject: [PATCH] Add `sentry-dart-plugin` documentation (#7097) Co-authored-by: Manoel Aranda Neto <5731772+marandaneto@users.noreply.github.com> --- src/platforms/flutter/troubleshooting.mdx | 14 +++ src/platforms/flutter/upload-debug.mdx | 136 +++++++++++++++++++--- 2 files changed, 137 insertions(+), 13 deletions(-) diff --git a/src/platforms/flutter/troubleshooting.mdx b/src/platforms/flutter/troubleshooting.mdx index 56ac60564dc15..b13336f7fb1c5 100644 --- a/src/platforms/flutter/troubleshooting.mdx +++ b/src/platforms/flutter/troubleshooting.mdx @@ -37,3 +37,17 @@ Flutter `split-debug-info` and `obfuscate` flags are supported on iOS/macOS. The ## Source Context Source Context support requires compiling your app using the `split-debug-info` build parameter on Flutter `3.10.0` and above. You must also upload [debug symbols](/platforms/flutter/upload-debug/) with the `upload_sources` option enabled. + +## Sentry Dart Plugin + +If you are using the Sentry Dart Plugin to upload [Debug Symbols](/platforms/flutter/upload-debug/#automatically-upload-debug-symbols), refer to the points below to resolve potential issues. + +Sentry's `auth_token` requires the `project:releases` or `project:write` scope. See [Debug Information Files](/product/cli/dif/#permissions) docs for more information. + +For the `commits` feature, Sentry's `auth_token` also requires the `org:read` scope. See API [Permissions & Scopes](/api/permissions/#releases) docs for more information. + +Dart's `--obfuscate` option is required to be paired with `--split-debug-info` to generate a symbol map. See [Dart docs](https://github.com/flutter/flutter/wiki/Obfuscating-Dart-Code) for more information. + +The `--split-debug-info` option requires setting an output directory. The directory must be an inner folder of the project's folder. See [Flutter docs](https://docs.flutter.dev/deployment/obfuscate#obfuscate-your-app) for more information. + +Flutter's `build web` command requires setting the `--source-maps` parameter to generate source maps. See [Flutter GitHub Issue](https://github.com/flutter/flutter/issues/72150#issuecomment-755541599) for more information. diff --git a/src/platforms/flutter/upload-debug.mdx b/src/platforms/flutter/upload-debug.mdx index 9d9da1d1adaf2..d9b7602234558 100644 --- a/src/platforms/flutter/upload-debug.mdx +++ b/src/platforms/flutter/upload-debug.mdx @@ -1,7 +1,7 @@ --- title: Debug Symbols -sidebar_order: 11 -description: "Learn more about uploading debug symbols for both Android and iOS/macOS." +sidebar_order: 2 +description: "Learn more about uploading debug symbols for both Android, iOS/macOS, and Flutter Web." --- We offer a range of methods to provide Sentry with debug symbols so that you can see symbolicated stack traces and triage issues faster. @@ -18,21 +18,131 @@ For Flutter Desktop (Windows/Linux) `split-debug-info` and `obfuscate` flags are Errors raised from the native layer in Flutter apps require certain debug information files to be uploaded. For example, an Android app can use `proguard` for minification and obfuscation. And when using NDK, dwarf debug files need to be uploaded. Flutter Web requires sourcemaps and iOS apps also require dwarf debug information files. -## Sentry Dart Plugin +## Automatically Upload Debug Symbols -[Try out the Sentry Dart Plugin](https://github.com/getsentry/sentry-dart-plugin), which uploads debug symbols automatically for you, or follow the manual steps below. +The easiest way to upload debug symbols is to use the [Sentry Dart Plugin](https://github.com/getsentry/sentry-dart-plugin) which will upload them automatically. -## Uploading for iOS and macOS +### Install + +In your `pubspec.yaml`, add `sentry_dart_plugin` as a new dev dependency. + +```yaml +dev_dependencies: + sentry_dart_plugin: ^1.0.0 +``` + +### Build + +Run + +- `flutter build apk` +- `flutter build ios` (or `macos`), or +- `flutter build web` + +before executing the `sentry_dart_plugin` plugin. + +This build step outputs the debug symbols and source maps that the plugin will upload. + +### Configure + +This Sentry Dart Plugin comes with a default configuration. + +To modify this configuration, add a `sentry:` configuration to the end of your `pubspec.yaml` file: + +```yaml +sentry: + upload_debug_symbols: true + upload_source_maps: false + upload_sources: false + project: ... + org: ... + auth_token: ... + url: ... + wait_for_processing: false + log_level: error + release: ... + web_build_path: ... + commits: auto + ignore_missing: true +``` + +#### Available Configuration Fields + +`project` + +: The project's name, for example `sentry-flutter`. Required. This is a `string` type. The alternative environmental variable is `SENTRY_PROJECT`. + +`org` + +: Your organization's slug, for example `sentry-sdks`. Required. This is a `string` type. The alternative environmental variable is `SENTRY_ORG`. + +`auth_token` + +: The sentry auth token, which will look like `<64 random characters>`. Required. This is a `string` type. The alternative environmental variable is `SENTRY_AUTH_TOKEN`. + +`upload_debug_symbols` + +: Enables or disables the automatic upload of debug symbols. This is a boolean type with default value `true`. + +`upload_source_maps` + +: Enables or disables the automatic upload of source maps. This is a boolean type with default value `false`. + +`upload_sources` + +: Does or doesn't include the source code of native code. This is a boolean type with default value `false`. + +`url` + +: The URL of your project, for example `https://mysentry.invalid/`. This is a `string` type. The alternative environmental variable is `SENTRY_URL`. + +`wait_for_processing` + +: Wait for server-side processing of uploaded files. This is a boolean type with default value `false`. + +`log_level` + +: Configures the log level for sentry-cli. This is a `string` type with default value `warn`. The alternative environmental variable is `SENTRY_LOG_LEVEL`. Possible values are `trace`, `debug`, `info`, `warn`, and `error`. + +`release` + +: The release version for source maps, it should match the release set by the SDK. This is a `string` type with default value `name@version` from pubspec. The alternative environmental variable is `SENTRY_RELEASE`. + +`web_build_path` + +: The web build folder. This is a `string` type with default value `build/web`. + +`commits` + +: Release commits integration. This is a `string` type with default value `auto`. + +`ignore_missing` + +: Ignore missing commits previously used in the release. This is a boolean type with default value `false`. + +### Run + +```bash +flutter packages pub run sentry_dart_plugin +``` + +### Troubleshooting + +Refer to [Troubleshooting - Sentry Dart Plugin](/platforms/flutter/troubleshooting#sentry-dart-plugin) to resolve potential issues. + +## Manually Upload Debug Symbols + +### Uploading for iOS and macOS Sentry requires a dSYM upload to symbolicate your crash logs. The symbolication process unscrambles Apple’s crash logs to reveal the function, file names, and line numbers of the crash. [Learn how to upload the dSYM files](/platforms/apple/dsym/). If you use the `split-debug-info` and `obfuscate` flags, you need to upload the `*.dSYM` files instead of the `*.symbols` files generated by the Flutter build. The `*.dSYM` files are located in the `build` folder of your project and not the given `split-debug-info` folder. -## Uploading for Android NDK +### Uploading for Android NDK -If you are using `sentry_flutter` version earlier than 5.1, native symbolication on Android requires a specific configuration. For good symbolication, set `android:extractNativeLibs="true"` in your `AndroidManifest.xml` file or `android.bundle.enableUncompressedNativeLibs=false` for [Android App Bundle](https://developer.android.com/guide/app-bundle) in your `gradle.properties` file. +The Sentry Dart Plugin will also upload NDK symbols if `upload_debug_symbols` is enabled. Alternatively, see our docs on uploading [Debug Information Files](/product/cli/dif/#uploading-files) manually with the Sentry CLI. -If you use the [Android NDK](/platforms/android/using-ndk/), you must [upload files manually using our CLI](/product/cli/dif/#uploading-files). +If you are using a version of `sentry_flutter` earlier than 5.1, native symbolication on Android requires a specific configuration. Refer to [Troubleshooting](/platforms/flutter/troubleshooting/#native-symbolication-on-android) for more information. @@ -40,15 +150,15 @@ Sentry's Flutter SDK doesn't currently support the `uploadNativeSymbols` flag fr -## Uploading with ProGuard +### Uploading with ProGuard -To use ProGuard with Sentry, upload the [Android Proguard/R8 mapping files](/platforms/android/proguard/) by either the recommended method of using our Gradle integration or manually by using [sentry-cli](/product/cli/dif/#proguard-mapping-upload). +If you have ProGuard (`minifyEnabled`) enabled, you must upload the [Android Proguard/R8 mapping files](/platforms/android/proguard/) to see complete stack traces. You can upload these files by either using our Gradle integration (recommended) or manually by using the [Sentry CLI](/product/cli/dif/#proguard-mapping-upload). -## Uploading Source Maps for Flutter Web +### Uploading Source Maps for Flutter Web -You can also use our CLI to [upload source maps for Flutter Web](/product/cli/releases/#managing-release-artifacts). This will automatically enable Source Context as well. +The Sentry Dart plugin also uploads source maps if `upload_source_maps` is enabled. Alternatively, you can use the Sentry CLI to upload your source maps for Flutter Web by following the docs on [Managing Release Artifacts](/product/cli/releases/#managing-release-artifacts). This will automatically enable Source Context as well. -## Uploading Source Context for Flutter Android, iOS, and macOS +### Uploading Source Context for Flutter Android, iOS, and macOS Use the [`upload_sources`](/platforms/flutter/upload-debug/#sentry-dart-plugin) option to enable [Source Context](/platforms/flutter/data-management/debug-files/source-context/).