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.
The command extracts your API key, application ID, version and version code from your app’s manifest file (AndroidManifest.xml) and sends it with the mapping file. To do this, it 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.
In order to match the uploaded mapping file with errors in your BugSnag dashboard, the command also computes a build ID using headers in the ProGuard files. This will be unique for each change in the source code and so should be sufficiently unique for most use cases.
If you wish to control this ID yourself, 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.
Prior to v6 of the BugSnag Android SDK, the build ID was not generated deterministically. Matching of the mapping files to an event will therefore use the app ID, app version and version code. This will be correct in most cases, but if you wish to support multiple builds with the same version code (e.g. separate builds for development or QA) you will need to set the build UUID value yourself or use the legacy BugSnag Android Gradle Plugin which generates a random UUID for you.
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.
--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.