Get started with Performance Monitoring for web

Before you begin

If you haven't already, visit Add Firebase to your JavaScript project to learn how to:

Create a Firebase project
Register your web app with Firebase

To use Performance Monitoring in a web app, you must add your app as a Firebase Web App in the Firebase console.

If you already use Firebase products in your existing web app and you want to start using the Performance Monitoring SDK, you must update your Firebase config object to include your appID.

Note that when you add your app to your Firebase project, you might also complete some of the steps in the following guide (for example, adding Firebase SDKs and initializing Firebase).

Step 1: Add Performance Monitoring and initialize Firebase

If you haven’t already, add the Performance Monitoring SDK and initialize Firebase in your app using one of the options below. Consider the following to help you choose among your options (see individual tabs for more detailed information):

From the CDN (standalone SDK) — If Performance Monitoring is the only Firebase product in your app, this option loads a single, lighter-weight SDK from the CDN.
From the CDN (standard SDK) — If you use other Firebase products in your app, this option loads the Performance Monitoring SDK along with other Firebase libraries from the CDN.
From Hosting URLs — If you’re using Firebase Hosting, this option offers a convenience for managing your Firebase configuration when initializing Firebase.
Using module bundlers — If you use a bundler (like Browserify or webpack), use this option to import individual modules when you need them.

After you've added the SDK, Firebase gets started right away monitoring automatic duration traces and automatic HTTP/S network requests.

From the CDN

You can configure partial import of the Firebase JavaScript SDK and only load the Firebase libraries that you need. Firebase stores each library of the Firebase JavaScript SDK on our global CDN (content delivery network).

To include the Performance Monitoring SDK from the CDN, you have two options:

standalone SDK — Performance Monitoring is the only Firebase product that you use in your app.
standard SDK — You’re using Performance Monitoring along with other Firebase products in your app.

standalone SDK

If Performance Monitoring is the only Firebase product in your app, use the standalone Performance Monitoring SDK (and the recommended header script below) if you’re interested in:

reducing your SDK package size
delaying initialization of the SDK until after your page loads

To include the standalone Performance Monitoring SDK in your app and delay its initialization to after your page loads:

Add the following script to the header of your index file.
Make sure to add your app's Firebase project configuration object.

(function(sa,fbc){function load(f,c){var a=document.createElement('script');
a.async=1;a.src=f;var s=document.getElementsByTagName('script')[0];
s.parentNode.insertBefore(a,s);}load(sa);
window.addEventListener('load',function(){firebase.initializeApp(fbc).performance()});
})(performance_standalone, firebaseConfig);

where,

performance_standalone is 'https://www.gstatic.com/firebasejs/7.7.0/firebase-performance-standalone.js'
firebaseConfig is your app's Firebase config object

The above script asynchronously loads the standalone SDK then initializes Firebase after the window's onload event fires. This tactic reduces the impact that the SDK could have on page load metrics since the browser has already reported its loading metrics when you initialize the SDK.

Learn about the standalone Performance Monitoring SDK and the header script

This standalone SDK is optimized for size; Gzipped, it's around 10kb. It has all the functionalities of Firebase Performance Monitoring along with a minimal set of the Firebase core SDK functionalities, as well.

Firebase Performance Monitoring uses fetch and Promise APIs which are not available on older browsers. The polyfills for these APIs are included in the standard Firebase Performance Monitoring JS SDK, but they are omitted from the standalone SDK to reduce size.

The Performance Monitoring SDK relies, in part, upon the Resource Timing API to obtain page load metrics from the browser.

The following snippet breaks down the header script that includes then delays initialization of the SDK:

(function(sdkSource, firebaseConfigObject) {
   function load(f, c) {
       // Creates a script tag to load the standalone SDK
       var sdkScript = document.createElement('script');

       // Sets it to an async script so that it doesn't interfere with page load
       sdkScript.async = 1;

       // Sets the source of the script
       sdkScript.src = f;

       // Inserts the script into the head of the page
       var s = document.getElementsByTagName('script')[0];
       s.parentNode.insertBefore(sdkScript, s);
   }

   // Calls the load method
   load(sdkSource);

   // Initializes the SDK only when the onload method is called
   window.addEventListener('load', function() {
       firebase.initializeApp(firebaseConfigObject).performance();
   });
})(performance_standalone, firebaseConfig);

where,

performance_standalone is 'https://www.gstatic.com/firebasejs/7.7.0/firebase-performance-standalone.js'
firebaseConfig is your app's Firebase config object

standard SDK

If you're using other Firebase products (like Authentication or Cloud Firestore in your app, include the standard Performance Monitoring SDK.

Note that this SDK requires that you include the separate standard Firebase core SDK and initialize Firebase and Performance Monitoring in a separate script.

To include the standard Performance Monitoring SDK, add the following scripts to the bottom of your <body> tag, but before you use any Firebase services:

<body>
  <!-- Insert these scripts at the bottom of the HTML, but before you use any Firebase services -->

  <!-- Firebase App (the core Firebase SDK) is always required and must be listed first -->
  <script src="https://www.gstatic.com/firebasejs/7.7.0/firebase-app.js"></script>

  <!-- Add the standard Performance Monitoring library -->
  <script src="https://www.gstatic.com/firebasejs/7.7.0/firebase-performance.js"></script>
<body>

Initialize Firebase and Performance Monitoring in your app:

<body>
<!-- Previously loaded Firebase SDKs -->

<script>
  // TODO: Replace the following with your app's Firebase project configuration
  var firebaseConfig = {
    // ...
  };

  // Initialize Firebase
  firebase.initializeApp(firebaseConfig);

  // Initialize Performance Monitoring and get a reference to the service
  var perf = firebase.performance();
</script>
</body>

From Hosting URLs

When you use Firebase Hosting, you can configure your app to load the Firebase JavaScript SDK libraries dynamically from reserved URLs. Learn more about adding SDKs via reserved Hosting URLs.

With this setup option, after you deploy to Firebase, your app automatically pulls the Firebase configuration object from the Firebase project to which you've deployed. You can deploy the same codebase to multiple Firebase projects, but you don't have to track the Firebase configuration that you're using for firebase.initializeApp().

To include the Performance Monitoring SDK, add the following scripts to the bottom of your <body> tag, but before you use any Firebase services:

<body>
  <!-- Insert these scripts at the bottom of the HTML, but before you use any Firebase services -->

  <!-- Firebase App (the core Firebase SDK) is always required and must be listed first -->
  <script src="/__/firebase/7.7.0/firebase-app.js"></script>

  <!-- Add the Performance Monitoring library -->
  <script src="/__/firebase/7.7.0/firebase-performance.js"></script>
</body>

Initialize Firebase and Performance Monitoring in your app (no need to include your Firebase config object when using reserved Hosting URLs):

<body>
  <!-- Previously loaded Firebase SDKs -->

  <!-- Initialize Firebase -->
  <script src="/__/firebase/init.js"></script>

  <!-- Initialize Performance Monitoring and get a reference to the service -->
  <script>
    var perf = firebase.performance();
    // ...
  </script>
</body>

Locally test your Performance Monitoring integration when using reserved Hosting URLs

To locally test your Performance Monitoring integration, firebase serve currently does not support initializing Firebase for Performance Monitoring via the /__/firebase/init.js URL. Instead, include your Firebase config object and initialize Firebase like so:

  <body>
    <!-- Previously loaded Firebase SDKs (via Hosting URLs) -->

    <script>
      // TODO: Replace the following with your app's Firebase project configuration
      var firebaseConfig = {
        // ...
      };

      // Initialize Firebase
      firebase.initializeApp(firebaseConfig);

      // Initialize Performance Monitoring and get a reference to the service
      var perf = firebase.performance();
    </script>
  </body>

Using module bundler

You can configure partial import of the Firebase JavaScript SDK and only load the Firebase products that you need. If you're using a bundler (like Browserify or webpack), you can import individual Firebase products when you need them.

Install the firebase npm package and save it to your package.json file by running:
```
npm install --save firebase
```

To include the Performance Monitoring SDK, import the Firebase modules:

// Firebase App (the core Firebase SDK) is always required and must be listed first
import * as firebase from "firebase/app";

// Add the Performance Monitoring library
import "firebase/performance";

Initialize Firebase and Performance Monitoring in your app:

// TODO: Replace the following with your app's Firebase project configuration
const firebaseConfig = {
  // ...
};

// Initialize Firebase
firebase.initializeApp(firebaseConfig);

// Initialize Performance Monitoring and get a reference to the service
const perf = firebase.performance();

Step 2: Add the first input delay polyfill library

To measure the first input delay metric, you need to add the polyfill library for this metric. For installation instructions, refer to the library's documentation.

Adding this polyfill library is not required for Performance Monitoring to report the other web app metrics.

Step 3: Generate performance events for initial data display

Firebase can detect that you've successfully added the SDK to your app when it receives event information (like app interactions) from your app. If you're still developing locally, generate events for initial data collection and processing.

Serve and view your web app in a local environment.
Generate events by loading subpages for your site, interacting with your app, and/or triggering network requests. Make sure to keep the browser tab open for at least 10 seconds after the page loads.
Within 2 hours of adding the SDK to your app, the Performance section of the Firebase console should display an "SDK detected" message.

If you don't see the SDK detection message, review the troubleshooting tips.
Performance Monitoring processes performance event data before displaying it in the Performance dashboard. You should see your initial data display within 24 hours of seeing the SDK detection message.

If you don't see a display of your initial data, review the troubleshooting tips.

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

Open your browser's developer tools (for example, Network tab for Chrome Dev Tools or in the Network Monitor for Firefox).
Refresh your web app in the browser.
Check your log messages for any error messages.
After a few seconds, look for a network call to firebaselogging.googleapis.com in your browser's developer tools. The presence of that network call shows that the browser is sending performance data to Firebase.

If your app isn't logging performance events, review the troubleshooting tips.

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

You can create custom traces to monitor performance data associated with specific code in your app.

With a custom trace, you can measure how long it takes your app to complete a specific task or set of tasks, such as loading a set of images or querying your database. The default metric for a custom trace is its duration, but you 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 trace (and add any desired custom metrics) using the API provided by the Performance Monitoring SDK.

Visit Add custom monitoring for specific app code to learn more about these features and how to add them to your app.

Step 6: Deploy your app then review results

After you've validated Performance Monitoring, you can deploy the updated version of your app to your users.

You can monitor performance data in the Performance dashboard of the Firebase console.

Next steps

Get hands-on experience with the Firebase Performance Monitoring for Web Codelab.
Learn more about: