If you are using ProGuard, DexGuard, or R8 to minify and optimize your app this will cause method and class names to become obfuscated in your stacktraces. Upload a mapping.txt file from a Proguard obfuscation build to deobfuscate symbols in your reported stacktraces.
For installation instructions for the BugSnag CLI, please see our Installation guide.
The android-proguard command uploads a mapping.txt generated during an obfuscation build and uploads it to the Android mapping API.
In order to match the uploaded mapping file with errors in your BugSnag dashboard, the command extracts your API key as well as an application ID, version and version code from your app’s manifest file (AndroidManifest.xml) and sends it with the mapping file.
The command attempts to find a merged app manifest file in your project directory, but if you have a non-standard project layout the location can be specified using the --app-manifest option, along with --variant if multiple build flavors exist. All values read from the app manifest can be overridden, or provided entirely, using the --application-id, --version-name and --version-code options.
As an alternative to matching mapping files using the version name and version code, you can also provide a build UUID. This can be useful for development builds, for example.
The easiest way to do this is to add a unique ID to your app manifest meta data under the com.bugsnag.android.BUILD_UUID key. This is read by the upload command as well as by the BugSnag library in your app when reporting errors. Alternatively you can provide the ID in the --build-uuid option and to the BugSnag library configuration, ensuring they are they same.
If you have the BugSnag Android Gradle Plugin enabled in your build, this build UUID is automatically generated and added to your app manifest. Therefore as long as the upload command can read your app manifest, each build will be have a UUID associated. You can check the UUID of the uploaded mapping file within the project settings on the BugSnag dashboard.
The simplest way to run the command is from the root directory of your Android project:
$ bugsnag-cli upload android-proguard
Or by providing a specific mapping file to upload:
$ bugsnag-cli upload android-proguard \
app/build/outputs/proguard/release/mapping.txt
If your build contains multiple variants or has a non-standard project layout, you might need to provide extra options:
$ bugsnag-cli upload android-proguard \
--variant=release \
--app-manifest-path=app/build/intermediates/merged_manifests/release/AndroidManifest.xml
--android-ndk-root) The path to your NDK installation, used to access the objcopy tool for extracting symbol information. This defaults to the path in the $ANDROID_NDK_ROOT environment variable.
--api-key) Your project’s API key. This defaults to the value of com.bugsnag.android.API_KEY in your app’s manifest file, if found.
You can find your API key in Project Settings from your BugSnag dashboard.
--app-manifest) The path to the app’s manifest file (AndroidManifest.xml), which is used to extract app information required for the upload. By default, the command looks for this file in app/build/intermediates/merged_manifests/<variant>/AndroidManifest.xml from your project directory.
--application-id) The unique application ID, usually the package name, of the app. This defaults to the value of Package in your app’s manifest file, if found.
--build-uuid) A unique identifier for the build. This is only required if you have multiple mapping files with the same applicationId and versionCode. This same ID must also be set in the BugSnag configuration in your app, so that errors match the uploaded build. See Unique build identifiers for more information.
--dry-run) Used to see the files and options that would be uploaded without actually sending them to the BugSnag endpoint.
--fail-on-upload) Whether to stop any further uploads if a file fails to upload successfully. By default the command attempts to upload all files.
--overwrite) Whether to ignore and overwrite existing uploads with same identifier. By default the command will fail if a matching file exists.
--project-root) Path to strip from the beginning of source file names referenced in stacktraces when displayed as an error in your dashboard. This will default to your project’s root directory if the command has detected one, otherwise it’s empty.
--retries) The number of retry attempts before failing an upload. By default it is only attempted once.
--timeout) The number of seconds to wait before failing an upload attempt. By default the upload is given 300s (5 mins).
--upload-api-root-url) The BugSnag On-premise upload server hostname, optionally containing port number. The command will append the appropriate path to access the correct BugSnag API upload endpoint.
--variant) The build type/flavor (e.g. ‘debug’ or ‘release’). This is used to disambiguate the between built files when searching your project directory.
--version-code) The version code of this build of the app. This defaults to the value of VersionCode in your app’s manifest file, if found.
--version-name) The version of the app. This defaults to the value of VersionName in your app’s manifest file, if found.