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). Acceptsnull
.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 { ArrayListhighScores = 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.