BugSnag is now Insight Hub – we're making some changes to how the product looks, but this won't impact the way you use BugSnag or any of your integrations.

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.

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=app/build/intermediates/merged_manifests/release/AndroidManifest.xml

Available options

API key (--api-key)

The BugSnag API key for the application.

You can find your API key in Project Settings from your BugSnag dashboard.

Default: the value of com.bugsnag.android.API_KEY in your app’s manifest file, if found.

App manifest (--app-manifest)

The path to a manifest file (AndroidManifest.xml) from which to obtain build information.

Default: app/build/intermediates/merged_manifests/<variant>/AndroidManifest.xml from your project directory. .

Application id (--application-id)

A unique application ID, usually the package name, of the application.

Default: the value of Package in your app’s manifest file, if found.

Build UUID (--build-uuid)

A unique identifier for this build of the application.

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.

Dex files (--dex-files)

The path to classes.dex files or directory used to calculate a build UUID.

Dry run (--dry-run)

Performs a dry-run of the command without sending any information to BugSnag.

Fail on upload error (--fail-on-upload-error)

Stops the upload when a file fails to upload successfully.

Log level (--log-level)

Sets the level of logging to debug, info, warn or fatal.

Default: info.

No build UUID (--no-build-uuid)

Prevents the automatically generated build UUID being uploaded with the build.

Overwrite (--overwrite)

Whether to ignore and overwrite existing uploads with same identifier, rather than failing if a matching file exists.

Port (--port)

The port number for the BugSnag upload server.

Default: 443.

Retries (--retries)

The number of retry attempts before failing an upload request.

Default: 0.

Timeout (--timeout)

The number of seconds to wait before failing an upload request.

Default: 300.

Upload API root URL (--upload-api-root-url)

The upload server hostname, optionally containing port number.

For use in BugSnag On-premise configurations. The command will append the appropriate path to access the correct upload endpoint.

Default: https://upload.bugsnag.com.

Variant (--variant)

The build type/flavor (e.g. debug, release) used to disambiguate the between built files when searching the project directory.

Verbose (--verbose)

Sets the level of the logging to its highest.

This is the equivalent of setting the log level to debug.

Version code (--version-code)

The version code of this build of the application.

Default: the value of VersionCode in your app’s manifest file, if found.

Version name (--version-name)

The version of the application.

Default: the value of VersionName in your app’s manifest file, if found.