Get Started with Firebase Performance Monitoring for Android

This guide shows you how to use Firebase Performance Monitoring with your app, following these steps:

  1. Prerequisites
  2. Add Firebase to your Android project
  3. Add Performance Monitoring to your app
  4. (Optional) Define a custom trace and one or more metrics in your app
  5. (Optional) Add the @AddTrace annotation to trace specific methods
  6. Check the Firebase console for Performance Monitoring results
  7. Deploy your app and review results in the Firebase console

Prerequisites

Before you begin, you need a few things set up in your environment:

  • A device running Android 4.0 (Ice Cream Sandwich) or newer, and Google Play services 16.2.0 or higher
  • The Google Play services SDK from the Google Repository, available in the Android SDK Manager
  • The latest version of Android Studio, version 2.2 or higher

Add Firebase to your Android project

If you are using other Firebase features, you can add Firebase to your app from Android Studio using the Firebase Assistant.

To open the Firebase Assistant in Android Studio:

  1. Click Tools > Firebase to open the Assistant window.
  2. Click to expand one of the listed features (for example, Analytics), then click the provided tutorial link (for example, Log an Analytics event).
  3. Click the Connect to Firebase button to connect to Firebase and add the necessary code to your app.

If you aren't already using other Firebase features in your app, add Firebase to your app manually.

Add Performance Monitoring to your app

  1. Open the project-level build.gradle file, and add the following:
    1. In the buildscript -> repositories section:
      jcenter()
    2. In the buildscript -> dependencies section, add the Firebase dependency:
      • For Android Studio 2.x:
        classpath 'com.google.firebase:firebase-plugins:1.1.1'
      • For Android Studio 3.x:
        classpath 'com.google.firebase:firebase-plugins:1.1.5'
  2. Open the app-level build.gradle file, and add the following:
    1. Below apply plugin: 'com.android.application', add the following line:
      apply plugin: 'com.google.firebase.firebase-perf'
    2. Add the following to the dependencies section:
      implementation 'com.google.firebase:firebase-perf:16.2.0'
  3. Recompile your app. Automatic traces and HTTP/S network requests are now monitored.

(Optional) Define a custom trace and one or more metrics in your app

A custom trace is a report of performance data associated with some of the code in your app. To learn more about custom traces, see the Performance Monitoring overview. You can have multiple custom traces in your app, and it is possible to have more than one custom trace running at a time. Each custom trace can have one or more metrics to count performance-related events in your app, and those metrics are associated with the traces that create them.

  1. Import these Performance Monitoring classes at the top of your .java file:

    Android

    import com.google.firebase.perf.FirebasePerformance;
    import com.google.firebase.perf.metrics.Trace;

  2. Just before the code where you want to start a trace in your app, add the following line of code to start a trace called test_trace:

    Android

    Trace myTrace = FirebasePerformance.getInstance().newTrace("test_trace");
    myTrace.start();
    
  3. To count performance-related events that occur in your app (such as cache hits and misses), add a line of code similar to the following each time that the event occurs, using a string other than item_cache_hit or item_cache_miss to name that event if you are counting a different type of event:

    Android

    Item item = cache.fetch("item");
    if (item != null) {
        myTrace.incrementMetric("item_cache_hit", 1);
    } else {
        myTrace.incrementMetric("item_cache_miss", 1);
    }
    
  4. Just after the code where you want to stop your trace, add the following line of code:

    Android

    myTrace.stop();
    

(Optional) Add the @AddTrace annotation to trace specific methods

You can add the @AddTrace annotation to methods in your app and provide a string to identify the resulting trace. This causes a trace to start at the beginning of this method, and to stop when the method completes. Traces created in this way do not have metrics available.

For example, to create a trace called onCreateTrace that runs when the onCreate() method is called, you would use code similar to the following:

Android

@Override
@AddTrace(name = "onCreateTrace", enabled = true /* optional */)
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
}

Check the Firebase console for Performance Monitoring results

  1. Build your app in Android Studio.
  2. Test your app using an Android emulator with a recent image and Google Play services 15.0.0 or later, or using a test device with Google Play services 15.0.0 or later.
  3. Confirm that Performance Monitoring results appear in the Firebase console. Results should appear within 12 hours.

Deploy your app and review results in the Firebase console

After you have validated Performance Monitoring using one or more test devices, you can deploy the updated version of your app to your users and use the Firebase console to monitor performance data.

(Optional) Add monitoring for specific network requests

Performance Monitoring collects network requests automatically. Although this includes most network requests for your app, some might not be reported. To include specific network requests in Performance Monitoring, add the following code to your app:

Android
HttpMetric metric =
        FirebasePerformance.getInstance().newHttpMetric("https://www.google.com",
                FirebasePerformance.HttpMethod.GET);
final URL url = new URL("https://www.google.com");
metric.start();
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
conn.setDoOutput(true);
conn.setRequestProperty("Content-Type", "application/json");
try {
    DataOutputStream outputStream = new DataOutputStream(conn.getOutputStream());
    outputStream.write(data);
} catch (IOException ignored) {
}
metric.setRequestPayloadSize(data.length);
metric.setHttpResponseCode(conn.getResponseCode());
printStreamContent(conn.getInputStream());

conn.disconnect();
metric.stop();

The HTTP/s network requests you specifically capture this way appear in the Firebase console along with the network requests Performance Monitoring captures automatically.

(Optional) Review a sample of traces and network requests

You can deep dive into segments of specific traces or network requests in the Firebase console. A random sampling of recorded sessions shows the following information:

an image of the Firebase Performance Monitoring sessions page

  • CPU: The Performance Monitoring SDK captures how much user time and system time your app consumes.
  • Memory: The Performance Monitoring SDK captures how much heap memory your app uses. Heap memory is the memory used for dynamic allocations, including objects created, objects deallocated, and objects that the app is actively using.
  • Individual information: Detailed information about a single instance of a trace or network request, including start time, end time, duration, request size, and response size.
  • Concurrent instances: Information about traces or network requests that happened at the same time.
  • Device attributes: Information about the device, including app version, model, OS version, radio, and custom attributes.

To see these detailed samples in the Firebase console, open one of your app's traces or network requests and click See sessions. Alternatively, click the link for an attribute's sessions from the specific attribute.

an image of the Firebase Performance Monitoring trace with a link to sessions

The sessions Performance Monitoring collects are distributed into percentiles for each metric. Sessions in lower percentile ranges have a lower value for the metric than sessions in higher percentile ranges. To filter the available sessions by percentile, use the percentiles dropdown above the sessions details.

an image of the Firebase Performance Monitoring sessions page

Known Issues

  • Firebase Plugin version 1.1.0 can cause a mismatch in Guava dependencies, resulting in the following error:

    Error:Execution failed for task ':app:packageInstantRunResourcesDebug'.
    > com.google.common.util.concurrent.MoreExecutors.directExecutor()Ljava/util/concurrent/Executor;

    If you see this error, upgrade to 1.1.1 or replace the classpath statement shown above with the following in the buildscript -> dependencies section of your project-level build.gradle file:

    classpath ('com.google.firebase:firebase-plugins:1.1.0') {
                exclude group: 'com.google.guava', module: 'guava-jdk5'
    }
  • Performance Monitoring only supports monitoring HTTP/S network requests made using the OkHttp HTTP client version 3.x.x.
  • Performance Monitoring reports the total payload size for HTTP/S network requests based on the value set in the HTTP content-length header. This value might not always be accurate.
  • Performance Monitoring only supports the main process in multi-process Android apps.
  • The com.google.firebase.firebase-perf gradle plugin is not compatible with DexGuard, which disables automatic traces and HTTP/S network request monitoring. Custom traces added using the SDK behave normally if your app uses DexGuard.
  • The com.google.firebase.firebase-perf gradle plugin is not compatible with Jack which has been deprecated.

Debugging integration

You can enable debug logging for Performance Monitoring at build time, by adding a <meta-data> element to the <application> element of your app's AndroidManifest.xml file, as follows:

<meta-data
  android:name="firebase_performance_logcat_enabled"
  android:value="true" />

You can view Trace and HTTP/S network request logging using logcat filtering. Performance Monitoring log messages are tagged with FirebasePerformance and can be filtered using following command:

adb logcat -s FirebasePerformance

Next steps

Send feedback about...

Need help? Visit our support page.