Upload Android Proguard mappings

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.

Overview

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.

Unique build identifiers

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.

Compatibility

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.

Example usage

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

Available options

Android NDK root (--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 (--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 (--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 (--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 (--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 (--dry-run)

Used to see the files and options that would be uploaded without actually sending them to the BugSnag endpoint.

Log Level (--log-level)

Used to set the level of the logging. The available levels are debug, info, warn, and fatal. The default level is info.

Overwrite (--overwrite)

Whether to ignore and overwrite existing uploads with same identifier. By default the command will fail if a matching file exists.

Project root (--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 (--retries)

The number of retry attempts before failing an upload. By default it is only attempted once.

Timeout (--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 (--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 (--variant)

The build type/flavor (e.g. ‘debug’ or ‘release’). This is used to disambiguate the between built files when searching your project directory.

Verbose (--verbose)

Used to set the level of the logging to its highest. This is the equivalent of setting log-level to debug.

Version code (--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 (--version-name)

The version of the app. This defaults to the value of VersionName in your app’s manifest file, if found.