ProGuard

ProGuard support for Raygun

What is ProGuard?

ProGuard is a free Java tool for obfuscation, class file shrinking, optimizing and preverifying. When enabling ProGuard in a native Android application that also uses Raygun, the obfuscation feature requires a bit of attention. By default, your obfuscated class and method names will show up in the stacktraces of exception/error reports submitted to Raygun. This makes the stacktraces difficult to read when looking into the cause of the issues.

ProGuard produces a mapping.txt file that can be used to restore the original class and method names. Such files can be uploaded to Raygun to automatically process all of your exception reports into readable stacktraces. The documentation on this page contains everything you need to know about using ProGuard with Raygun in your native Android applications.

If you haven't set up Raygun in your Android application yet, you can find the documentation to do so here.

Enable ProGuard in a Gradle Android project

A Gradle Android project will contain a couple of build.gradle files - one for the project, and one for the application. ProGuard 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 ProGuard. Generally you'll want to enable ProGuard 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'
  }
}

Update your pro file

Also in the app folder, you'll find a proguard-rules.pro file which is where you can configure ProGuard settings. You'll need to add the following lines to this file in order for Raygun and ProGuard to play nicely together. Each line is explained below so that you can understand what these changes to your pro file will do.

-keep class main.java.com.mindscapehq.android.raygun4android.** { *; }
-keepattributes Exceptions, Signature, InnerClasses, SourceFile, LineNumberTable
-renamesourcefileattribute SourceFile

-keep is required here in order for Raygun4Android to function correctly. This line tells ProGuard 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.

Upload your ProGuard mapping files

When you use Android Studio to build your application package, ProGuard 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.

API endpoint

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 <VARIABLE> needs to be substituted (including the angle brackets) with your own value as described below each code example.

Username and password

curl
  -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
  -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
  -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.

Manual upload

A drag and drop zone is available in the Raygun web application for manually uploading ProGuard 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 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.

Managing your uploaded mapping files

Regardless of how you upload your mapping files, they will all be listed in the PrGuard Mapping Center as seen in the image above. You can find the ProGuard Mapping Center by first visiting the desired application in your Raygun account, selecting "Application settings" from the side menu, and then clicking "ProGuard 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.

Processing your error reports

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.

Documentation missing?

If we don't have documentation about your desired topic, send us a message and we'll create it for you.