1. Home
  2. Language Guides
  3. Android
  4. Crash Reporting
  5. ProGuard and R8

ProGuard and R8

ProGuard and R8 are free Java code obfuscation tools commonly used in native Android application development.

With code obfuscation enabled for your application, your obfuscated class and method names are going to show up in the stacktraces of exception reports. To convert these back into readable stacktraces, you can upload the associated mapping.txt file to Raygun. This file is produced by ProGuard or R8 when compiling your application. This documentation will show you how to configure obfuscation in your Android application and how to upload the associated mapping files to Raygun.

Add the following lines to your proguard-rules.pro file (both ProGuard and R8 use this file) so that Raygun and obfuscation play nicely together. Each line is explained below so that you can understand what these changes to your rules file will do.

-keep class com.raygun.raygun4android.** { *; }
-keepattributes Exceptions, Signature, InnerClasses, SourceFile, LineNumberTable
-renamesourcefileattribute SourceFile

-keep is required here in order for Raygun4Android to function correctly. This line tells ProGuard/R8 not to obfuscate any of the code in Raygun4Android. Some of the classes are used to build up a JSON payload, which if obfuscated is going to create a payload that Raygun can’t read.

-keepattributes is recommended in order to keep certain bits of information. In particular, Signature is needed to resolve generic type names and LineNumberTable is so that your stack traces have line numbers which is generally what you want. By default, file names will not be available in the stacktraces. The SourceFile entry on the -keepattributes line will cause file names to be available in the stacktraces, but note that they are not obfuscated. Don't include SourceFile on the -keepattributes line if you don't want your file names to be included in your app package.

-renamesourcefileattribute is optional. This causes the file names of your code to all appear as “SourceFile” in the stacktrace. This is for added secrecy so that your actual file names can not be seen in the application package. Even with a mapping file, the original file names can not be resolved, which is not so good for debugging. If you don't mind your file names being kept, then feel free to remove this line for the extra debugging help.

A Gradle Android project will contain a couple of build.gradle files - one for the project, and one for the application. Obfuscation can be enabled by editing the build.gradle file of the application. This can be found in the root of the app directory. The file should already contain "minifyEnabled" fields that are set to false. Setting this to true will enable obfuscation. R8 will be used by default with Gradle 3.4 and above, whereas older versions of Gradle will be using ProGuard. Generally you'll want to enable obfuscation in the "release" build type, but not in "debug".

buildTypes {
  release {
    minifyEnabled true
    proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
  }
  debug {
    minifyEnabled false
    proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
  }
}

When you use Android Studio to build your application package, ProGuard/R8 will write a mapping file to the /app/build/outputs directory of your application project. By uploading the mapping file to Raygun, all your exception reports will be retraced with the mapping file and be presented to you with readable stacktraces. Raygun provides two ways to upload your files - an API end point which is useful for automation, and manual upload from within the Raygun web app.

It's important to note that every time you make changes to your code and then build your application, you'll need to upload the newly generated mapping file if you want readable stacktraces from that build. Raygun is most valuable when your application is out in the wild being used by customers, rather than while debugging. So you generally only need to upload mapping files for builds of your application that get released to your customers. Raygun selects a mapping file you've uploaded based on the versionName of your application (as set in your build.gradle file). Specifying which version that each mapping file is for is explained in the instructions for both of the upload techniques below.

The recommended way of uploading the mapping files to Raygun is by automating a POST to the API endpoint. Below are examples of uploading a mapping file using cURL and different authentication methods. Each needs to be substituted (including the angle brackets) with your own value as described below each code example.

Note that although the endpoint is named proguardsymbols it will also accept R8 mapping files.

Username and password

curl -L
  -u <USERNAME>:<PASSWORD>
  -F "file=@<PATH_TO_MAPPING_FILE>"
  -F "version=<VERSION_NAME>"
  https://app.raygun.com/upload/proguardsymbols/<RAYGUN_APPLICATION_ID>

USERNAME and PASSWORD are your Raygun account credentials.
PATH_TO_MAPPING_FILE is an absolute or relative path to your mapping file including the file name and .txt extension.
VERSION_NAME is the version name of your application as set in your build.gradle file. This is needed to select the correct mapping file for each of your exception reports.
RAYGUN_APPLICATION_ID is available in the URL of your Raygun application dashboard.

Basic authentication

curl -L
  -H "Authorization: Basic <BASIC_AUTH_TOKEN>"
  -F "file=@<PATH_TO_MAPPING_FILE>"
  -F "version=<VERSION_NAME>"
  https://app.raygun.com/upload/proguardsymbols/<RAYGUN_APPLICATION_ID>

BASIC_AUTH_TOKEN can be generated by taking your Raygun account credentials in the format username:password and then using the base 64 result.
PATH_TO_MAPPING_FILE is an absolute or relative path to your mapping file including the file name and .txt extension.
VERSION_NAME is the version name of your application as set in your build.gradle file. This is needed to select the correct mapping file for each of your exception reports.
RAYGUN_APPLICATION_ID is available in the URL of your Raygun application dashboard.

External access token

curl -L
  -F "file=@<PATH_TO_MAPPING_FILE>"
  -F "version=<VERSION_NAME>"
  https://app.raygun.com/upload/proguardsymbols/<RAYGUN_APPLICATION_ID>?authToken=<EXTERNAL_ACCESS_TOKEN>

PATH_TO_MAPPING_FILE is an absolute or relative path to your mapping file including the file name and .txt extension.
VERSION_NAME is the version name of your application as set in your build.gradle file. This is needed to select the correct mapping file for each of your exception reports.
RAYGUN_APPLICATION_ID is available in the URL of your Raygun application dashboard.
EXTERNAL_ACCESS_TOKEN can be obtained from Raygun by clicking your name in the top right corner, select "My settings" and then hit "Generate external access token" or copy it if you already have one.

Additional options

By default, the upload will fail if the version you specify has previously had a mapping file uploaded. If you do want to overwrite existing version names with the new mapping file, add the following to the cURL POST:

-F "overwrite=true"

If the upload is clearly not working, add the verbose option to get more information about what's wrong.

-v

Possible results

200 if the upload was successul.

302 if you don't provide any form of authentication.

400 if the version is not provided. If the file does not have a .txt extension. If a file is already mapped to the given version and overwrite is false.

401 if credentials are incorrect, or you don't have access to the application.

404 if the url or app id is incorrect.

curl (26) if the path to the mapping file is incorrect.

A drag and drop zone is available in the Raygun web application for manually uploading ProGuard/R8 mapping files. This can be found by first visiting the desired application in your Raygun account, selecting "Application settings" from the side menu, and then clicking "ProGuard/R8 map center". Before uploading a mapping file manually, you'll need to rename it to be the same as the versionName of your application as set in your build.gradle file (but keep the .txt extension). This is so that for each exception report, Raygun can use the correct mapping file that was generated from the same version of your application.

Regardless of how you upload your mapping files, they will all be listed in the ProGuard/R8 Mapping Center as seen in the image above. You can find the ProGuard/R8 Mapping Center by first visiting the desired application in your Raygun account, selecting "Application settings" from the side menu, and then clicking "ProGuard/R8 map center". Each listed mapping file includes a button to delete the file. When uploading a file manually, the upload will fail if the same version is already listed. Delete the existing file first if you wish to upload a new mapping file for that version.

With your mapping file uploaded, Raygun will retrace the stacktraces of all exception reports flowing into your Raygun dashboard. If any exceptions came into your Raygun account before you uploaded the mapping file for that version, then you can manually trigger a reprocessing of an exception report. To do this, navigate to an exception report instance in your Raygun dashboard that needs reprocessing. While on the Summary tab (default) scroll to the bottom to find a "Reprocess crash report" button. Click this and refresh the page a little later to see the reprocessed stacktrace.

On this page: