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 traces and 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.onload = function() {firebase.initializeApp(fbc).performance();};
})(performance_standalone, firebaseConfig);

where,

performance_standalone is 'https://www.gstatic.com/firebasejs/6.3.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.onload = function() {
       firebase.initializeApp(firebaseConfigObject).performance();
   };
})(performance_standalone, firebaseConfig);

where,

performance_standalone is 'https://www.gstatic.com/firebasejs/6.3.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/6.3.0/firebase-app.js"></script>

  <!-- Add the standard Performance Monitoring library -->
  <script src="https://www.gstatic.com/firebasejs/6.3.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/6.3.0/firebase-app.js"></script>

  <!-- Add the Performance Monitoring library -->
  <script src="/__/firebase/6.3.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.

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

Step 3: Check that Performance Monitoring is logging data

Refresh your web app in the browser.
After a few seconds, look for a network call to firebaselogging.googleapis.com in the Network tab for Chrome Dev Tools or in the Network Monitor for Firefox.

The presence of that network call shows that the browser is sending performance data to Firebase.
Confirm that Performance Monitoring results display in the Firebase console.

Results usually display within 12 hours.

Step 4: (Optional) Add custom traces and custom metrics

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's 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.

Note that names for custom traces and metrics must meet the following requirements: no leading or trailing whitespace, no leading underscore (_) character, and max length is 32 characters.

To start and stop a custom trace, wrap the code that you want to trace with lines of code similar to the following:
```
const trace = perf.trace('customTraceName');
trace.start();

// code that you want to trace

trace.stop();
```

To add a custom metric, add lines of code similar to the following each time that the event occurs. For example, this custom metric counts performance-related events that occur in your app.

async function getInventory(inventoryIds) {
  const trace = perf.trace('inventoryRetrieval');

  // Tracks the number of IDs fetched (the metric could help you to optimize in the future)
  trace.incrementMetric('numberOfIds', inventoryIds.length);

  // Measures the time it takes to request inventory based on the amount of inventory
  trace.start();
  const inventoryData = await retrieveInventory(inventoryIds);
  trace.stop();

  return inventoryData;
}

Step 5: 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 Firebase console.

Next steps

Get hands-on experience with the Firebase Performance Monitoring for Web Codelab.
Learn more about automatic traces.
Learn more about monitoring custom attributes.