Before you begin

If you haven't already,add Firebase to your Android project.

Step 1: Add thePerformance Monitoring SDK to your app

After you've added thePerformance Monitoring SDK, Firebase automatically starts collectingdata for your app'sscreen rendering and datarelated to your app's lifecycle (likeapp start time). Toenable Firebase to monitor network requests, you mustalso add thePerformance MonitoringGradle plugin (next step).

1. In yourmodule (app-level) Gradle file(usually<project>/<app-module>/build.gradle.kts or<project>/<app-module>/build.gradle),add the dependency for thePerformance Monitoring library for Android. We recommend using theFirebase Android BoMto control library versioning.

   dependencies{// Import theBoM for the Firebase platformimplementation(platform("com.google.firebase:firebase-bom:34.7.0"))// Add the dependency for thePerformance Monitoring library// When using theBoM, you don't specify versions in Firebase library dependenciesimplementation("com.google.firebase:firebase-perf")}

   By using theFirebase Android BoM, your app will always use compatible versions of Firebase Android libraries.

   (Alternative)  Add Firebase library dependencies without using theBoM

   If you choose not to use theFirebase BoM, you must specify each Firebase library version in its dependency line.

   Note that if you usemultiple Firebase libraries in your app, we strongly recommend using theBoM to manage library versions, which ensures that all versions are compatible.

   dependencies{// Add the dependency for thePerformance Monitoring library// When NOT using theBoM, you must specify versions in Firebase library dependenciesimplementation("com.google.firebase:firebase-perf:22.0.4")}

2. Recompile your app.

Note: When you add thePerformance Monitoring SDK to your app, theRemote Config SDK isincluded as a dependency. If you already useRemote Config, you won't seeany difference. However, if you're new toRemote Config, explore theRemote Config documentation to learn moreabout the various features you'll be able to access in your app.

Step 2: Add thePerformance Monitoring Gradle plugin to your app

After you've added thePerformance Monitoring Gradle plugin, Firebase automatically startscollecting data forHTTP/S network requests. Theplugin also enables you to instrument custom code traces using@AddTrace annotation.

How thePerformance Monitoring plugin works

Before your code is converted to DEX files, thePerformance Monitoring plugin uses theTransform API and theASM bytecode instrumentation framework to visit your app's compiled class files and to instrument the code (to measure performance). The time it takes to instrument your code largely depends on the number and size of your classes.

If your app takes more time to compile than you'd like, consider the following options:

• Disable thePerformance Monitoring plugin for your debug builds at compile time
• Modularize your code to optimize your build speed

1. In yourroot-level (project-level) Gradle file(<project>/build.gradle.kts or<project>/build.gradle), add thePerformance Monitoring Gradle plugin:

   Kotlin

   Are you still using thebuildscriptsyntax? Learn how toadd Firebase pluginsusing that syntax.

   plugins{// To benefit from the latestPerformance Monitoring plugin features,// update your Android Gradle plugin dependency to at least v3.4.0id("com.android.application")version"7.3.0"applyfalse// Make sure that you have the Google services Gradle plugin dependencyid("com.google.gms.google-services")version"4.4.4"applyfalse// Add the dependency for thePerformance Monitoring Gradle pluginid("com.google.firebase.firebase-perf")version"2.0.2"applyfalse}

   Groovy

   Are you still using thebuildscriptsyntax? Learn how toadd Firebase pluginsusing that syntax.

   plugins{// To benefit from the latestPerformance Monitoring plugin features,// update your Android Gradle plugin dependency to at least v3.4.0id'com.android.application'version'7.3.0'applyfalse// Make sure that you have the Google services Gradle plugin dependencyid'com.google.gms.google-services'version'4.4.4'applyfalse// Add the dependency for thePerformance Monitoring Gradle pluginid'com.google.firebase.firebase-perf'version'2.0.2'applyfalse}

2. In yourmodule (app-level) Gradle file(usually<project>/<app-module>/build.gradle.kts or<project>/<app-module>/build.gradle), add thePerformance MonitoringGradle plugin:

   Kotlin

   plugins{id("com.android.application")// Make sure that you have the Google services Gradle pluginid("com.google.gms.google-services")// Add thePerformance Monitoring Gradle pluginid("com.google.firebase.firebase-perf")...}

   Groovy

   plugins{id'com.android.application'// Make sure that you have the Google services Gradle pluginid'com.google.gms.google-services'// Add thePerformance Monitoring Gradle pluginid'com.google.firebase.firebase-perf'...}

3. Recompile your app.

Step 3: Generate performance events for initial data display

Firebase starts processing the events when you successfully add the SDK to yourapp. If you're still developing locally, interact with your app to generateevents for initial data collection and processing.

Note: ThePerformance Monitoring SDK batches events locally then sends them to Firebaseperiodically (every 30 seconds). So, there's a delay between an app interactionand when Firebase receives the event information from your app.

1. Generate events by switching your app between background and foregroundseveral times, interacting with your app by navigating across screens,and/or triggering network requests.

2. Go to thePerformance dashboard of theFirebase console. You should see your initial data display withina few minutes.

   If you don't see a display of your initial data, review thetroubleshootingtips.

Step 4:(Optional) View log messages for performance events

1. Enable debug logging forPerformance Monitoring at build time by adding a<meta-data>element to your app'sAndroidManifest.xml file, like so:

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

2. Check your log messages for any error messages.

3. Performance Monitoring tags its log messages withFirebasePerformance. Using logcatfiltering, you can specifically view duration trace and HTTP/S networkrequest logging by running the following command:

   adb logcat -s FirebasePerformance

4. Check for the following types of logs which indicate thatPerformance Monitoring islogging performance events:

   • Logging trace metric:TRACE_NAME,FIREBASE_PERFORMANCE_CONSOLE_URL
   • Logging network request trace:URL

5. Click on the URL to view your data in the Firebase console. It may take a fewmoments for the data to update in the dashboard.

If your app isn't logging performance events, review thetroubleshootingtips.

Step 5:(Optional) Add custom monitoring for specific code

To monitor performance data associated with specific code in your app, you caninstrumentcustom code traces.

With a custom code trace, you can measure how long it takes your app to completea specific task or set of tasks, such as loading a set of images or queryingyour database. The default metric for a custom code trace is its duration, butyou can also add custom metrics, such as cache hits and memory warnings.

In your code, you define the beginning and the end of a custom code trace (andadd any desired custom metrics) using the API provided by thePerformance Monitoring SDK.For Android apps, you can also monitor the duration ofspecific methods using@AddTrace annotation.

VisitAdd monitoring for specific codeto learn more about these features and how to add them to your app.

Step 6: Deploy your app then review results

After you've validatedPerformance Monitoring using one or more test devices, you candeploy the updated version of your app to your users.

You can monitor performance data in thePerformance dashboard of theFirebase console.

Known issues

• ThePerformance Monitoring Gradle plugin v1.1.0 can cause a mismatch in Guavadependencies, 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, you can either:

  • Upgrade thePerformance Monitoring plugin to v1.1.1 or later (the most recent isv2.0.2).

  • Replace thePerformance Monitoring plugin dependency line in yourroot-level (project-level) Gradle file (<project>/build.gradle.ktsor<project>/build.gradle), as follows:

    Kotlin

    buildscript{// ...dependencies{// ...// Replace the standardPerformance Monitoring plugin dependency line, as follows:classpath("com.google.firebase:perf-plugin:1.1.0"){exclude(group="com.google.guava",module="guava-jdk5")}}}

    Groovy

    buildscript{// ...dependencies{// ...// Replace the standardPerformance Monitoring plugin dependency line, as follows:classpath('com.google.firebase:perf-plugin:1.1.0'){excludegroup:'com.google.guava',module:'guava-jdk5'}}}

• Performance Monitoring reports the total payload size for HTTP network requests basedon the value set in the HTTP content-length header. This value might notalways be accurate.

• Performance Monitoring only supports the main process in multi-process Android apps.

Next steps

• Review and run thePerformance Monitoring Android code sample on GitHub.

• Learn more about data automatically collected byPerformance Monitoring:

  • Data related to your app's lifecycle, likeapp start time
  • Data forscreen rendering in your app
  • Data forHTTP/S network requests issuedby your app

• View, track, and filter yourperformance data in theFirebase console.

• Add monitoring for specific tasks or workflows in your app byinstrumenting custom code traces.

• Use attributes to filter performance data.