Advanced Setup

Storing crash reports on the device

If the device can't connect, Raygun4Android will save the crash report to disk. At the next start of the application (and therefore the provider) it will check if the internet is now available, and if it is, send the cached messages. A maximum of 64 messages will be cached and you can change the amount by calling:

RaygunClient.setMaxReportsStoredOnDevice(amount)

Version tracking

Raygun4Android supports tracking the version of your application that a crash occurred on in a few different ways.

Inside the manifest

Set the versionName attribute on <manifest> in your AndroidManifest.xml to be of the form x.x.x.x, where x is a positive integer.

When initialising the Raygun client

Set the version in the overloaded init method when initialising the Raygun client.

RaygunClient.init(this, "YOUR_RAYGUN_API_KEY", "YOUR_APP_VERSION");

When configuring the Raygun client

Use the static setVersion method on RaygunClient class.

RaygunClient.setVersion("YOUR_APP_VERSION");

The application's version will then be sent with each message, and you can then filter by version in the Raygun dashboard.

Tags and custom data

Raygun supports attaching tags and custom data for specific errors. You can read more about Tags and custom data here.

Adding tags

Tags can be set using the following method:

RaygunClient.setTags(List tags)

Adding custom data

Custom data can be set using the following method:

RaygunClient.setCustomData(Map customData)

Manually sending errors

Raygun4Android automatically captures and send all unhandled exceptions. However, there may be times you will want to send custom handled errors manually. The following methods are available for sending errors manually:

RaygunClient.send(Throwable throwable)

// Include a list of tags with the error.
// This is in *addition* to any tags set via the `setTags` method
RaygunClient.send(Throwable throwable, List tags)

// Include a list of tags and custom data with the error. 
// This is in *addition* to any tags or custom data set by the `setTags` and `setCustomData` methods
RaygunClient.send(Throwable throwable, List tags, Map customData)

Modifying or cancelling error reports

This provider has an onBeforeSend API to support accessing or mutating the candidate error payload immediately before it is sent, or cancelling the send outright. This is provided as the public method RaygunClient.setOnBeforeSend(RaygunOnBeforeSend), which takes an instance of a class that implements the CrashReportingOnBeforeSend interface. Your class needs a public onBeforeSend method that takes a RaygunMessage parameter, and returns the same.

Override the onBeforeSend method and log an info message every time an error is sent.

class BeforeSendImplementation implements CrashReportingOnBeforeSend {
    @Override
    public RaygunMessage onBeforeSend(RaygunMessage message) {
        Log.i("onBeforeSend", "About to post to Raygun, returning the payload as is...");
        return message;
    }
}

public class SomeActivity extends Activity {
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        // Initialize the activity as normal
        ...
        // Initialize Raygun
        ...
        RaygunClient.setOnBeforeSend(new BeforeSendImplementation());
    }
}

Mutate the error payload, changing the message:

@Override
public RaygunMessage onBeforeSend(RaygunMessage message) {
    Log.i("onBeforeSend", "Changing the message...");

    RaygunMessageDetails details = message.getDetails();
    RaygunErrorMessage error = details.getError();
    error.setMessage("Mutated message");

    return message;
}

To cancel the send (prevent the error from reaching the Raygun dashboard) by returning null:

@Override
public RaygunMessage onBeforeSend(RaygunMessage message) {
    Log.i("onBeforeSend", "Cancelling sending message to Raygun...");

    return null;
}

Custom error grouping

You can override Raygun's default grouping logic for Android exceptions by setting the grouping key manually in onBeforeSend (see above):

@Override
public RaygunMessage onBeforeSend(RaygunMessage message) {
    RaygunMessageDetails details = message.getDetails();
    details.setGroupingKey("foo");

    return message;
}

Any error instances with a certain key will be grouped together. The example above will place all errors within one group (as the key is hardcoded to 'foo'). The grouping key is a String and must be between 1 and 100 characters long. You should send all data you care about (for instance, parts of the exception message, stacktrace frames, class names etc) to a hash function (for instance MD5), then pass that to setGroupingKey.

Breadcrumbs

With breadcrumbs, you can attach an accurate trail of events through your system leading up to the moment a report was generated. This helps to gain more insight into why the application crashed when it did, making prioritization of fixes much easier.

The easiest way to record a breadcrumb is by calling the recordBreadcrumb method on the Raygun client:

RaygunClient.recordBreadcrumb("User entered screen");

Alternatively you can provide more details by constructing a RaygunBreadcrumbMessage object and passing it to the Raygun client:

WeakHashMap customData = new WeakHashMap<String, Object>();
customData.put("someKey", "someValue");

RaygunBreadcrumbMessage crumb = new RaygunBreadcrumbMessage.Builder("Entered another screen")
    .level(RaygunBreadcrumbLevel.INFO)
    .category("Launch")
    .methodName("onCreate")
    .customData(customData)
    .build();

RaygunClient.recordBreadcrumb(crumb);

Internal logging

For debugging purposes the provider will log information alongside the system messages. These messages can be viewed with Logcat under the tag Raygun4Android.

Raygun4Android uses Timber for internal logging. This requires some language features that are only available with Java 8. Make sure that your project using the library has set compilation compatibility to Java 8. Google's documentation has more information on the reasons and implications of this requirement.

android {  
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }
}