Get Started with Firebase Performance Monitoring for Android

This guide shows you how 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 counters in your app
5. (Optional) Add the @AddTrace annotation to trace specific methods
6. (Optional) Use Performance Monitoring with Android vitals
7. Check the Firebase console for Performance Monitoring results
8. Deploy your app and review results in the Firebase console

Performance Monitoring is currently in beta release.

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 10.2.6 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 using other Firebase features in your app, you can 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:

      classpath 'com.google.firebase:firebase-plugins:1.1.0'

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:

      compile 'com.google.firebase:firebase-perf:10.2.6'

   3. If your app uses other Firebase SDKs, you should also change the version to 10.2.6 for those SDKs.
3. Recompile your app. Automatic traces and HTTP/S network requests are now monitored.

(Optional) Define a custom trace and one or more counters 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 counters to count performance-related events in your app, and those counters are associated with the traces that create them.

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

   Java

   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:

   Java

   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:

   Java

   Item item = cache.fetch("item");
   if (item != null) {
       myTrace.incrementCounter("item_cache_hit");
   } else {
       myTrace.incrementCounter("item_cache_miss");
   }

4. Just after the code where you want to stop your trace, add the following line of code:

   Java

   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 counters 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:

import com.google.firebase.perf.metrics.AddTrace;
...
@Override
@AddTrace(name = "onCreateTrace", enabled = true/*Optional*/)
protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        ...
        ...
}

(Optional) Use Performance Monitoring with Android vitals

You can use Performance Monitoring to gain deeper insight into the information provided in the Play Developer console Android vitals dashboard. Performance Monitoring can be especially helpful when you don't know which parts of your app are causing th issues shown in the Android vitals dashboard.

For example, if the Android vitals dashboard indicates that your app is taking longer than expected to generate a frame and display it on the screen, you could use Performance Monitoring to analyze which parts of your app have issues with slow rendering (for example, a specific Activity used for a home screen or contents screen). You could count both slow and frozen frames in your app on devices running API level 24 or higher as follows:

1. Start a custom trace by calling myTrace.start()at the beginning of a user's interaction with an Activity.
2. Call FrameMetricsAggregator() to create an object that captures the TOTAL_DURATION metric for each frame.
3. Shortly before stopping a custom trace by calling myTrace.stop():
   1. Use FrameMetricsAggregator.stop() to get the TOTAL_DURATION values from the FrameMetricsAggregator object.
   2. Increment a frames counter to get the total number of frames. Also, increment a slow_frames counter for each TOTAL_DURATION value greater than 16ms, and increment a frozen_frames counter for each TOTAL_DURATION value greater than 700ms (or set these counters to 0 if no slow rendering occurs).
4. In the Firebase console, look for the devices that show the most slow frames or frozen frames to isolate the cases where slow rendering occurs in your app.

To learn more about using the Android vitals dashboard to detect slow rendering frames, see Slow Rendering.

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 10.2.6 or later, or using a test device with Google Play services 10.2.6 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.

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, 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.
• If your custom trace is used as a Parcelable, it will cause a crash in your app. This can occur if an Intent that includes a custom trace is sent from one Activity to another.

Next steps

• Review and run the Performance Monitoring Android code sample on GitHub.
• Learn more about Automatic Traces.