Skip to content

Commit bea8d64

Browse files
buenaflorcoolguyzone
buenaflor
and
coolguyzone
authored
feat(flutter): improve upload debug symbols (#12356)
* update debug symbols page * Apply suggestions from code review Co-authored-by: Alex Krawiec <[email protected]> * Update upload-debug.mdx * update flutter web --------- Co-authored-by: Alex Krawiec <[email protected]>
1 parent ce1c410 commit bea8d64

File tree

1 file changed

+143
-73
lines changed

1 file changed

+143
-73
lines changed

‎docs/platforms/flutter/upload-debug.mdx‎

Lines changed: 143 additions & 73 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
title: Debug Symbols
3-
description: "Learn more about uploading debug symbols for both Android, iOS/macOS, and Flutter Web."
3+
description: "Learn more about uploading debug symbols for Android, iOS/macOS, and Flutter Web."
44
sidebar_order: 2
55
---
66

@@ -18,56 +18,166 @@ For Flutter Desktop (Windows/Linux) `split-debug-info` and `obfuscate` flags are
1818

1919
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.
2020

21-
## Automatically Upload Debug Symbols
21+
## Sentry Dart Plugin
2222

23-
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.
23+
The easiest way to upload debug symbols, source maps, and use source context is to use the [Sentry Dart Plugin](https://github.com/getsentry/sentry-dart-plugin) which will upload them automatically.
2424

25-
### Install
25+
### 1. Install
2626

2727
In your `pubspec.yaml`, add `sentry_dart_plugin` as a new dev dependency.
2828

29-
```yaml
29+
```yaml {filename: pubspec.yaml}
3030
dev_dependencies:
31-
sentry_dart_plugin: ^2.0.0
31+
sentry_dart_plugin: ^{{@inject packages.version('sentry.dart.plugin', '2.0.0') }}
3232
```
3333
34-
### Build
34+
### 2. Configure
3535
36-
Run
36+
The Sentry Dart Plugin comes with a default configuration but requires you to set the `project`, `org`, and `auth_token` fields to use it.
3737

38-
- `flutter build apk`
39-
- `flutter build ios` (or `macos`), or
40-
- `flutter build web`
38+
Add the following to your `pubspec.yaml` file:
39+
40+
```yaml {filename: pubspec.yaml}
41+
sentry:
42+
project: ___PROJECT_SLUG___
43+
org: ___ORG_SLUG___
44+
auth_token: ___ORG_AUTH_TOKEN___
45+
```
46+
47+
<Note>
4148
42-
before executing the `sentry_dart_plugin` plugin.
49+
The option `upload_debug_symbols` is enabled by default. That means the plugin will automatically upload debug symbols for all platforms except Flutter Web.
4350

44-
This build step outputs the debug symbols and source maps that the plugin will upload.
51+
</Note>
52+
53+
#### Source Maps
54+
55+
By default, source maps are not uploaded. In order to upload source maps, you need to set the `upload_source_maps` field to `true`.
4556

46-
### Configure
57+
```yaml {filename: pubspec.yaml} {5}
58+
sentry:
59+
project: ___PROJECT_SLUG___
60+
org: ___ORG_SLUG___
61+
auth_token: ___ORG_AUTH_TOKEN___
62+
upload_source_maps: true
63+
```
4764
48-
This Sentry Dart Plugin comes with a default configuration.
65+
#### Source Context
4966
50-
To modify this configuration, add a `sentry:` configuration to the end of your `pubspec.yaml` file:
67+
By default, sources are not uploaded. In order to upload sources, you need to set the `upload_sources` field to `true`.
5168

52-
```yaml
69+
```yaml {filename: pubspec.yaml} {5}
5370
sentry:
54-
upload_debug_symbols: true
55-
upload_source_maps: false
56-
upload_sources: false
57-
project: ...
58-
org: ...
59-
auth_token: ...
60-
url: ...
61-
wait_for_processing: false
62-
log_level: error
63-
release: ...
64-
dist: ...
65-
web_build_path: ...
66-
commits: auto
67-
ignore_missing: true
71+
project: ___PROJECT_SLUG___
72+
org: ___ORG_SLUG___
73+
auth_token: ___ORG_AUTH_TOKEN___
74+
upload_sources: true
75+
76+
```
77+
78+
<Note>
79+
80+
This uploads the source files of the Dart/Flutter code, not the native code.
81+
If you want to use source context for native code, you need to setup source context in the respective native platform.
82+
83+
</Note>
84+
85+
In addition to configuring the plugin in the `pubspec.yaml` file, the plugin supports using a properties file or environment variables.
86+
For more information, read the [Sentry Dart Plugin README](https://github.com/getsentry/sentry-dart-plugin/tree/main?tab=readme-ov-file#configuration-optional).
87+
88+
### 3. Build
89+
90+
Run one of the following commands before executing the `sentry_dart_plugin` plugin.
91+
If you choose to obfuscate your build, include the `--obfuscate` flag along with the `--split-debug-info` option to specify the directory for storing debug information.
92+
93+
For a standard build:
94+
- `flutter build apk`
95+
- `flutter build ios`
96+
- `flutter build macos`
97+
98+
For an obfuscated build:
99+
- `flutter build apk --obfuscate --split-debug-info=<output-directory>`
100+
- `flutter build ios --obfuscate --split-debug-info=<output-directory>`
101+
- `flutter build macos --obfuscate --split-debug-info=<output-directory>`
102+
103+
<Note>
104+
105+
For Flutter web run `flutter build web --release --source-maps` to generate source maps.
106+
107+
</Note>
108+
109+
### 4. Run
110+
111+
Now we can run the plugin to upload the debug symbols, source maps, and sources (if enabled).
112+
113+
```bash
114+
flutter packages pub run sentry_dart_plugin
115+
```
116+
117+
<Note>
118+
119+
If you choose not to obfuscate your build, the plugin will not upload debug symbols but will still configure source context if enabled.
120+
121+
</Note>
122+
123+
### Proguard
124+
125+
If you have ProGuard (`minifyEnabled`) enabled, you must upload the [Android Proguard/R8 mapping files](/platforms/android/enhance-errors/proguard) to see complete stack traces.
126+
127+
In order to upload debug symbols for ProGuard obfuscated native Android code you have two options:
128+
1. Use the [Sentry Android Gradle Plugin](/platforms/android/configuration/gradle/)
129+
2. Use the [Sentry CLI](/cli/dif/#uploading-files)
130+
131+
The Sentry Android Gradle Plugin is the simpler and recommended way to upload debug symbols for Android.
132+
133+
After installing the Sentry Android Gradle Plugin, you need to set `autoInstallation` to `false` in your `app/build.gradle` file:
134+
135+
```groovy {filename: app/build.gradle}
136+
sentry {
137+
autoInstallation {
138+
enabled = false
139+
}
140+
}
68141
```
69142

70-
#### Available Configuration Fields
143+
Sentry Flutter already ships with a compatible Sentry Android SDK, so we need to disable the auto-installation which could cause conflicts with the packaged Sentry Android SDK.
144+
145+
After setting up the gradle plugin, follow the [Android Gradle Plugin guide](/platforms/android/configuration/gradle/#proguardr8--dexguard) on how to upload Proguard mapping files.
146+
147+
## Manually Upload Debug Symbols
148+
149+
If you have an obfuscated build and you decide not to use the Sentry Dart Plugin, you can manually upload debug symbols for Android, iOS/macOS, Flutter Web.
150+
151+
You will need to upload the following files:
152+
- [dSYM files](/platforms/android/data-management/debug-files/file-formats/#mach-o-and-dsym) (`*.dSYM`) for iOS and macOS
153+
- [Flutter generated symbols](https://docs.flutter.dev/deployment/obfuscate#obfuscate-your-app) (`*.symbols`) for Android and [ELF](/platforms/android/data-management/debug-files/file-formats/#executable-and-linkable-format-elf) for Android NDK
154+
- Source Maps (`*.map`) for Web
155+
156+
### iOS and macOS
157+
158+
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/).
159+
160+
### Android
161+
162+
See our docs on uploading [Debug Information Files](/cli/dif/#uploading-files) manually with the Sentry CLI.
163+
164+
### Android NDK
165+
166+
See our docs on uploading [Debug Information Files](/cli/dif/#uploading-files) manually with the Sentry CLI.
167+
168+
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/flutter/troubleshooting/#native-symbolication-on-android) for more information.
169+
170+
<Note>
171+
172+
Sentry's Flutter SDK doesn't currently support the `uploadNativeSymbols` flag from the [Sentry Gradle Plugin](/platforms/android/configuration/gradle/).
173+
174+
</Note>
175+
176+
### Web
177+
178+
See our docs on uploading [Source Maps](/cli/releases/#upload-source-maps) manually.
179+
180+
## Configuration Fields
71181

72182
`project`
73183

@@ -139,46 +249,6 @@ Path to the sentry-cli binary to use instead of downloading. Make sure to use th
139249

140250
Alternative place to download sentry-cli. This is a `string` type with default value `https://downloads.sentry-cdn.com/sentry-cli`. Alternatively, this can also be set with the `SENTRYCLI_CDNURL` environment variable.
141251

142-
### Run
143-
144-
```bash
145-
flutter packages pub run sentry_dart_plugin
146-
```
147-
148-
### Troubleshooting
252+
## Troubleshooting
149253

150254
Refer to [Troubleshooting - Sentry Dart Plugin](/platforms/flutter/troubleshooting#sentry-dart-plugin) to resolve potential issues.
151-
152-
## Manually Upload Debug Symbols
153-
154-
### Uploading for iOS and macOS
155-
156-
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/).
157-
158-
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.
159-
160-
### Uploading for Android NDK
161-
162-
The Sentry Dart Plugin will also upload NDK symbols if `upload_debug_symbols` is enabled. Alternatively, see our docs on uploading [Debug Information Files](/cli/dif/#uploading-files) manually with the Sentry CLI.
163-
164-
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.
165-
166-
<Note>
167-
168-
Sentry's Flutter SDK doesn't currently support the `uploadNativeSymbols` flag from the [Sentry Gradle Plugin](/platforms/android/configuration/gradle/).
169-
170-
</Note>
171-
172-
### Uploading with ProGuard
173-
174-
If you have ProGuard (`minifyEnabled`) enabled, you must upload the [Android Proguard/R8 mapping files](/platforms/android/enhance-errors/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](/cli/dif/#proguard-mapping-upload).
175-
176-
### Uploading Source Maps for Flutter Web
177-
178-
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](/cli/releases/#managing-release-artifacts).
179-
180-
### Uploading Source Context
181-
182-
Use the [`upload_sources`](/platforms/flutter/upload-debug/#sentry-dart-plugin) option to enable [Source Context](/platforms/flutter/data-management/debug-files/source-context/). This is available for Flutter Android, iOS, macOS and Web.
183-
184-
For more information, check out the [Native Symbolication on iOS/macOS](/platforms/flutter/troubleshooting/#native-symbolication-on-iosmacos) and [Source Context](/platforms/flutter/troubleshooting/#source-context) troubleshooting guides.

0 commit comments

Comments
 (0)