Crashes & Exceptions - Android SDK v2 (Legacy)

This document provides a high-level overview of crash and exception measurement using the Google Analytics SDK for Android v2.

Overview

Crash and exception measurement allows you to measure the number and type of caught and uncaught crashes and exceptions that occur in your app. An exception in Google Analytics consists of:

  • String (Optional) Description – a description of the exception (up to 100 characters). Accepts null .
  • boolean isFatal – indicates whether the exception was fatal. true indicates fatal.

Crash and exception data is available primarily in the Crash and Exceptions report.

Caught Exceptions

Caught exceptions are errors in your app for which you've defined exception handling code. These are generally errors you would anticipate to occur during normal use of your app, and from which you'd like your app to be able to recover, such as the occasional timeout of a network connection during a request for data.

You can measure caught exceptions by adding sendException() to the catch block of your exception handling code.

In the following example, an app tries to load a list of high scores from the cloud. If the request times out, perhaps due to a slow network connection, we'll send the exception to Google Analytics before handling it for the user:

try {
  ArrayList highScores = getHighScores();            // Get scores from the cloud.
} catch (IOException e) {
  Tracker myTracker = EasyTracker.getTracker();      // Get a reference to tracker.
  myTracker.sendException(e.getMessage(), false);    // false indicates non-fatal exception.

  ... // Display alert to user that high scores are currently unavailable.
}

Uncaught Exception Measurement

Uncaught exceptions represent instances where your app encountered unexpected conditions at runtime and are often fatal, causing the app to crash as a result. Uncaught exceptions can be sent to Google Analytics automatically by using EasyTracker or the ExceptionReporter class.

Using EasyTracker

To automatically send all uncaught exceptions in your app using EasyTracker, add this line to your analytics.xml file: 

<bool name="ga_reportUncaughtExceptions">true</bool>

After sending an exception using automatic exception measurement, EasyTracker will pass the exception on to the Thread's default exception handler.

When using automatic exception measurement, keep in mind the following:

  • All exceptions sent using automatic exception measurement are reported as fatal in Google Analytics.
  • The description field is automatically populated using the stack trace.

Using ExceptionReporter

Use the ExceptionReporter class to implement automatic uncaught exception measurement if you're not using EasyTracker. This is the same class that EasyTracker implements to handle its automatic exception reporting.

ExceptionReporter can serve as the default uncaught exception handler for either a specific thread or all threads in your app. After sending an exception to Google Analytics, the ExceptionReporter class can optionally pass the exception on to an uncaught exception handler you provide.

The following code creates a new ExceptionReporter object and sets it as the new default uncaught exception handler. As a result, every uncaught exception will be sent to Google Analytics and then passed on to the previous uncaught exception handler. For most applications, the default handler will log the exception to the log and terminate the application.

UncaughtExceptionHandler myHandler = new ExceptionReporter(
    myTracker,                                        // Currently used Tracker.
    GAServiceManager.getInstance(),                   // GAServiceManager singleton.
    Thread.getDefaultUncaughtExceptionHandler());     // Current default uncaught exception handler.

 // Make myHandler the new default uncaught exception handler.
Thread.setDefaultUncaughtExceptionHandler(myHandler);

Using ExceptionParser

The SDK provides an ExceptionParser interface that you can implement to get the most relevant descriptions from your stack traces when sending uncaught exceptions to Google Analytics. The ExceptionParser interface has one method: getDescription(String threadName, Throwable t).

You can set your Tracker to use your ExceptionParser when sending uncaught exceptions to Google Analytics by calling setExceptionParser(ExceptionParser parser) as in this example:

// Where myParser represents your implementation of ExceptionParser.
ExceptionParser parser = new myParser(context);

// Where myTracker is an instance of Tracker.
myTracker.setExceptionParser(parser);

Your Tracker will then use your parser's getDescription() method to populate the description field of any uncaught exceptions sent to Google Analytics.