Raygun error reporting with ProGuard enabled

ProGuard is a technology that’s well known amongst native Java Android developers. It mainly makes it easy to obfuscate code for security reasons.

It wasn’t built for Android specifically, but it’s so useful for Android applications that it’s included with Android Studio.

How ProGuard will obfuscate code results in class and method names being replaced with much smaller names like ‘a’ and ‘b’.

This shrinks the size of the resulting app package, making the application next to impossible to reverse engineer. Obfuscation also produces a ProGuard mapping file, which you can use to convert ‘a’ and ‘b’ back into their familiar names.

Raygun includes an exception/error reporting service that integrates into many platforms, including native Java Android applications. A small client library added to your application causes crash reports to automatically be sent to your Raygun dashboard where they are grouped. Raygun then presents valuable debugging information including the stacktrace.

Using these two technologies together means exception reports sent to Raygun end up with obfuscated stacktraces (ultimately making them more difficult to read and fix.)

By uploading your ProGuard mapping file, Raygun will retrace your exception reports to display human readable stacktraces. You’ll be able to work with them much easier.

Here’s how to set up Raygun and Proguard together:

Setting up

If you haven’t done so already, enable Raygun exception reporting in your Android application by following the instructions here.

Enable ProGuard  in your app which can be done by setting ‘minifyEnabled’ to true in your application’s build.gradle file.

To get started with Raygun and ProGuard working together, make some changes to your proguard-rules.pro file so that they play nicely together. Next, add the following lines to your ProGuard rules file, or integrate them into your existing rules:

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

It’s best to understand the changes that you make to files in your project:

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

-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 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 ignore this line for the extra debugging help.

-keepattributes is recommended in order to keep certain bits of information. In particular, Signature is needed to resolve generic type names, SourceFile is to keep your file names (optional) and LineNumberTable is so that your stack traces have line numbers which is generally what you want.

Upload your ProGuard mapping file

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.

Upload this mapping file whenever you build your application in order for Raygun to retrace your exception reports into readable stacktraces. Raygun provides two ways to upload your mapping files – POSTing to an API endpoint which is great for automation, or by manually drag and dropping them into the ProGuard Mapping Center.

API endpoint

Below is an example of uploading a ProGuard mapping file to the Raygun API endpoint using cURL and basic authentication. The values in the <ANGLE_BRACKETS> need to be substituted (including the angle brackets) with your own values as described below.

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

and is your Raygun account credentials.

<PATH_TO_MAPPING_FILE> is a relative or absolute path to the mapping file that you wish to upload.

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

Manual upload

The contents of the mapping file have no way of correlating back to the particular version/build of your application that it maps to. Let Raygun know which version of your application you want this mapping file to be used in.

This is as simple as renaming the ProGuard mapping.txt file to be the versionName of your application (as set in your build.gradle file).

Then, upload it through the Raygun web application. While viewing your Android application in Raygun, click the ‘Application Settings’ item in the side menu.

Next, click the ‘ProGuard Map Center’ that appears in the side menu under the settings. On the ProGuard Mapping Center page, click the blue button, or drag and drop your renamed mapping file for it to be uploaded to Raygun.

This page also keeps a list of all the mapping files you’ve uploaded.

Retracing your stacktraces

With the mapping file now uploaded, the stacktrace from any exception report sent to Raygun from your application will be retraced using the appropriate mapping file. (Which is based on the version name.) Such reports will be displayed with their resulting human readable stacktraces so you can get right onto fixing the problems.

These stacktraces will also be used in the grouping logic. Issues in your application coming from the same point will be grouped together.

If any exceptions were sent from your application before you had uploaded the relevant renamed mapping file, they’ll be displayed with the obfuscated names in them.

Not to worry though, once you have uploaded the mapping file,  click the ‘Reprocess Crash Report’ button in the summary tab of an exception report. It can then be retraced. (There is a shortcut link to the ProGuard Mapping Centre near the reprocess button for convenience.)

Try Raygun and Proguard together

You can find full documentation of ProGuard support for Raygun here.

I hope that this support proves useful to everyone using ProGuard and Raygun together in their native Android applications. If you have an Android App and obfuscate code using ProGuard, this process will make it easier to understand the stacktrace inside Raygun.

We’d love to hear any feedback. Post us a message in the forums, or use the ‘Feedback’ button in the side menu of the Raygun application.

Start a free trial of Raygun now to get exception reporting in your Android or any other application.