Debug Symbols
Learn more about uploading debug symbols for 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.
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.
The easiest way to upload debug symbols, source maps, and use source context is to use the Sentry Dart Plugin which will upload them automatically.
In your pubspec.yaml
, add sentry_dart_plugin
as a new dev dependency.
pubspec.yaml
dev_dependencies:
sentry_dart_plugin: ^2.2.1
The Sentry Dart Plugin comes with a default configuration but requires you to set the project
, org
, and auth_token
fields to use it.
Add the following to your pubspec.yaml
file:
pubspec.yaml
sentry:
project: example-project
org: example-org
auth_token: sntrys_YOUR_TOKEN_HERE
The option upload_debug_symbols
is enabled by default. That means the plugin will automatically upload debug symbols for all platforms except Flutter Web.
By default, source maps are not uploaded. In order to upload source maps, you need to set the upload_source_maps
field to true
.
pubspec.yaml
sentry:
project: example-project
org: example-org
auth_token: sntrys_YOUR_TOKEN_HERE
upload_source_maps: true
By default, sources are not uploaded. In order to upload sources, you need to set the upload_sources
field to true
.
pubspec.yaml
sentry:
project: example-project
org: example-org
auth_token: sntrys_YOUR_TOKEN_HERE
upload_sources: true
This uploads the source files of the Dart/Flutter code, not the native code. If you want to use source context for native code, you need to setup source context in the respective native platform.
In addition to configuring the plugin in the pubspec.yaml
file, the plugin supports using a properties file or environment variables. For more information, read the Sentry Dart Plugin README.
Run one of the following commands before executing the sentry_dart_plugin
plugin. 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.
For a standard build:
flutter build apk
flutter build ios
flutter build macos
For an obfuscated build:
flutter build apk --obfuscate --split-debug-info=<output-directory>
flutter build ios --obfuscate --split-debug-info=<output-directory>
flutter build macos --obfuscate --split-debug-info=<output-directory>
For Flutter web run flutter build web --release --source-maps
to generate source maps.
Now we can run the plugin to upload the debug symbols, source maps, and sources (if enabled).
flutter packages pub run sentry_dart_plugin
If you choose not to obfuscate your build, the plugin will not upload debug symbols but will still configure source context if enabled.
If you have ProGuard (minifyEnabled
) enabled, you must upload the Android Proguard/R8 mapping files to see complete stack traces.
In order to upload debug symbols for ProGuard obfuscated native Android code you have two options:
- Use the Sentry Android Gradle Plugin
- Use the Sentry CLI
The Sentry Android Gradle Plugin is the simpler and recommended way to upload debug symbols for Android.
After installing the Sentry Android Gradle Plugin, you need to set autoInstallation
to false
in your app/build.gradle
file:
app/build.gradle
sentry {
autoInstallation {
enabled = false
}
}
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.
After setting up the gradle plugin, follow the Android Gradle Plugin guide on how to upload Proguard mapping files.
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.
You will need to upload the following files:
- dSYM files (
*.dSYM
) for iOS and macOS - Flutter generated symbols (
*.symbols
) for Android and ELF for Android NDK - Source Maps (
*.map
) for Web
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.
See our docs on uploading Debug Information Files manually with the Sentry CLI.
See our docs on uploading Debug Information Files manually with the Sentry CLI.
If you're 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.
See our docs on uploading Source Maps manually.
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<area>://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, which should match the release set by the SDK. This is a string
type with default value name@version
from pubspec. If a build number is included in the version, it is utilized as dist. The alternative environmental variable is SENTRY_RELEASE
.
Setting a custom release can be specified via an environment variable or plugin configuration. Once set, it is used as is without further modification.
dist
Custom dist can also be set via the environment variable SENTRY_DIST
or via plugin configuration. It replaces or adds to the build number in the default 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
.
bin_dir
The folder where the plugin downloads the sentry-cli binary. This is a string
type with default value .dart_tool/pub/bin/sentry_dart_plugin
.
bin_path
Path to the sentry-cli binary to use instead of downloading. Make sure to use the correct version. This is a string
type and is empty by default.
sentry_cli_cdn_url
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.
Refer to Troubleshooting - Sentry Dart Plugin to resolve potential issues.
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").