This document provides a high-level overview of crash and exception measurement using the Google Analytics SDK v4 for Android.
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 | Type | Required | Description |
---|---|---|---|
Description | String |
No | A description of the exception (up to 100 characters). Accepts
null . |
isFatal | 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, such as the occasional timeout of a network connection during a request for data, are errors in your app which you've implemented code to handle.
Measure a caught exception by setting the exception field values on the tracker and sending the hit, as in this example:
// Get tracker. Tracker t = ((AnalyticsSampleApp) getActivity().getApplication()).getTracker(TrackerName.APP_TRACKER); // Build and send exception. t.send(new HitBuilders.ExceptionBuilder() .setDescription(getExceptionMethod() + ":" + getExceptionLocation()) .setFatal(getExceptionFatal()) .build());
See
Advanced Configuration for details on the getTracker
method.
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 setting the ga_reportUncaughtExceptions
configuration value
or by using the ExceptionReporter
class.
Automatic Configuration
To send all uncaught exceptions in your app automatically to Google Analytics, add this line to your XML configuration file:
<bool name="ga_reportUncaughtExceptions">true</bool>
After sending an exception using automatic exception measurement, the
exception will be passed 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 the ga_reportUncaughtExceptions
configuration value.
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.
Thread.UncaughtExceptionHandler myHandler = new ExceptionReporter( myTracker, Thread.getDefaultUncaughtExceptionHandler(), context); // 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:
// Get tracker. Tracker t = ((AnalyticsSampleApp) getActivity().getApplication()).getTracker( TrackerName.APP_TRACKER); // Using StandardExceptionParser to get an Exception description. try { // Request some scores from the network. ArrayList<Integer> highScores = getHighScoresFromCloud(); } catch (IOException e) { t.send(new HitBuilders.ExceptionBuilder() .setDescription(new StandardExceptionParser(this, null) .getDescription(Thread.currentThread().getName(), e)) .setFatal(false) .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.