Crashes and Exceptions

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.

See a Code Snippet from the Sample Application

The following snippet shows an example Fragment that sends an exception:

package com.google.android.apps.mobileplayground;

import android.os.Bundle;
import android.support.v4.app.Fragment;
import android.view.LayoutInflater;
import android.view.View;
import android.view.View.OnClickListener;
import android.view.ViewGroup;
import android.widget.Button;
import android.widget.CheckBox;
import android.widget.EditText;
import com.google.android.apps.mobileplayground.AnalyticsSampleApp.TrackerName;
import com.google.android.gms.analytics.GoogleAnalytics;
import com.google.android.gms.analytics.HitBuilders;
import com.google.android.gms.analytics.Tracker;

/**
 * Class to exercise Exception hits.
 */
public class ExceptionFragment extends Fragment {

  @Override
  public View onCreateView(LayoutInflater inflater, ViewGroup container,
      Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);

    View view = inflater.inflate(R.layout.exception, container, false);

    final Button dispatchBtn = (Button) view.findViewById(R.id.btnDispatch);
    dispatchBtn.setOnClickListener(new OnClickListener() {
      @Override
      public void onClick(View v) {
        dispatch();
      }
    });

    final Button trackBtn = (Button) view.findViewById(R.id.trackBtn);
    trackBtn.setOnClickListener(new OnClickListener() {
      @Override
      public void onClick(View v) {
        track();
      }
    });
    return view;
  }

  private void dispatch() {
    GoogleAnalytics.getInstance(getActivity().getApplicationContext()).dispatchLocalHits();
  }

  private void track() {
    // 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());
  }

  private boolean getExceptionFatal() {
    return ((CheckBox) getView().findViewById(R.id.isFatalChk)).isChecked();
  }

  private String getExceptionLocation() {
    return ((EditText) getView().findViewById(R.id.exceptionLocationEdit)).getText().toString();
  }

  private String getExceptionMethod() {
    return ((EditText) getView().findViewById(R.id.exceptionMethodEdit)).getText().toString();
  }
}

Warning: Never send the exception message (such as e.getMessage()) to Google Analytics as it may contain personally identifiable information.

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.

Note: This value can only be set to true for a single Tracker. If specified for multiple Trackers, then the last one to be initialized will be used.

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.