Debug Symbols
We offer a range of methods to provide Sentry with debug symbols so that you can see symbolicated stack traces and triage issues faster.
When to Upload
With default settings, complete stack traces are available in your Dart error, out of the box, unless you use split-debug-info
and obfuscate
. In those cases, you need to upload the debug information files generated by the flutter
build, so Sentry can show you proper stack traces.
For Flutter Desktop (Windows/Linux) split-debug-info
and obfuscate
flags are not supported yet. See this issue.
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.
Automatically Upload Debug Symbols
The easiest way to upload debug symbols is to use the Sentry Dart Plugin which will upload them automatically.
Install
In your pubspec.yaml
, add sentry_dart_plugin
as a new dev dependency.
dev_dependencies:
sentry_dart_plugin: ^1.0.0
Build
Run
flutter build apk
flutter build ios
(ormacos
), orflutter 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:
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 projectRepresents your service in Sentry and allows you to scope events to a distinct application.'s name, for example
sentry-flutter
. Required. This is astring
type. The alternative environmental variable isSENTRY_PROJECT
.
org
- Your organization's slug, for example
sentry-sdks
. Required. This is astring
type. The alternative environmental variable isSENTRY_ORG
.
auth_token
- The Sentry auth tokenIn search, a key-value pair or raw search term. Also, a value used for authorization., which will look like
<64 random characters>
. Required. This is astring
type. The alternative environmental variable isSENTRY_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<area>://mysentry.invalid/
. This is astring
type. The alternative environmental variable isSENTRY_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 valuewarn
. The alternative environmental variable isSENTRY_LOG_LEVEL
. Possible values aretrace
,debug
,info
,warn
, anderror
.
release
- The release version for source maps, it should match the release set by the SDK. This is a
string
type with default valuename@version
from pubspec. The alternative environmental variable isSENTRY_RELEASE
.
web_build_path
- The web build folder. This is a
string
type with default valuebuild/web
.
commits
- Release commits integration. This is a
string
type with default valueauto
.
ignore_missing
- Ignore missing commits previously used in the release. This is a boolean type with default value
false
.
Run
flutter packages pub run sentry_dart_plugin
Troubleshooting
Refer to 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.
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
split-debug-info
folder.Uploading for Android NDK
The Sentry Dart Plugin will also upload NDK symbols if upload_debug_symbols
is enabled. Alternatively, see our docs on uploading Debug Information Files manually with the Sentry CLI.
If you are using a version of sentry_flutter
earlier than 5.1, native symbolication on Android requires a specific configuration. Refer to Troubleshooting for more information.
Sentry's Flutter SDK doesn't currently support the uploadNativeSymbols
flag from the Sentry Gradle Plugin.
Uploading with ProGuard
If you have ProGuard (minifyEnabled
) enabled, you must upload the Android Proguard/R8 mapping files to see complete stack traces. You can upload these files by either using our Gradle integration (recommended) or manually by using the Sentry CLI.
Uploading Source Maps for Flutter Web
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. This will automatically enable Source Context as well.
Uploading Source Context for Flutter Android, iOS, and macOS
Use the upload_sources
option to enable Source Context.
For more information, check out the Native Symbolication on iOS/macOS and Source Context troubleshooting guides.
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) or suggesting an update ("yeah, this would be better").
- Package:
- pub:sentry_flutter
- Version:
- 7.15.0
- Repository:
- https://github.com/getsentry/sentry-dart
- API Documentation:
- https://pub.dev/documentation/sentry_flutter/latest/