Crashes & Exceptions - Android SDK

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

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 has these fields:

Field Name Tracker Field Type Required Description
Description Fields.EX_DESCRIPTION String No A description of the exception (up to 100 characters). Accepts null .
isFatal Fields.EX_FATAL boolean Yes 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, such as the occasional timeout of a network connection during a request for data.

Measure a caught exception by setting the exception field values on the tracker and sending the hit, as in this example:

/*
 * An app tries to load a list of high scores from the cloud. If the request
 * times out, an exception is sent to Google Analytics
 */
try {

  // Request some scores from the network.
  ArrayList highScores = getHighScoresFromCloud();

} catch (IOException e) {

  // May return null if EasyTracker has not yet been initialized with a
  // property ID.
  EasyTracker easyTracker = EasyTracker.getInstance(this);

  // StandardExceptionParser is provided to help get meaningful Exception descriptions.
 	easyTracker.send(MapBuilder
      .createException(new StandardExceptionParser(this, null)              // Context and optional collection of package names
                                                                            // to be used in reporting the exception.
                       .getDescription(Thread.currentThread().getName(),    // The name of the thread on which the exception occurred.
                                       e),                                  // The exception.
                       false)                                               // False indicates a nonfatal exception
      .build()
  );


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

Using an Advanced Implementation

Use the ExceptionReporter class to implement automatic uncaught exception measurement if you're using an advanced implementation and not using EasyTracker.

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(
    GoogleAnalytics.getInstance(this).getDefaultTracker(), // Tracker, may return null if not yet initialized.
    GAServiceManager.getInstance(),                        // GAServiceManager singleton.
    Thread.getDefaultUncaughtExceptionHandler());          // Current default uncaught exception handler.

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

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

  • All exceptions sent using automatic exception measurement are reported as fatal in Google Analytics.
  • By default, the description field is automatically set using the exception type, class name, method name and thread name.

Parsing Exception Descriptions

The SDK provides a StandardExceptionParser to simplify the process of getting and sending exception descriptions to Google Analytics: 

// Using StandardExceptionParser to get an Exception description.
try {

  // Request some scores from the network.
  ArrayList highScores = getHighScoresFromCloud();

} catch (IOException e) {

  // May return null if EasyTracker has not yet been initialized with a
  // property ID.
  EasyTracker easyTracker = EasyTracker.getInstance(this);

 	easyTracker.send(MapBuilder
      .createException(new StandardExceptionParser(this, null)              // Context and optional collection of package names
                                                                            // to be used in reporting the exception.
                       .getDescription(Thread.currentThread().getName(),    // The name of the thread on which the exception occurred.
                                       e),                                  // The exception.
	                     false)                                               // False indicates a fatal exception
      .build()
  );

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

You can also implement your own parser by implementing the ExceptionParser interface and calling its setDescription method when sending an exception to Google Analytics.