Add support for capturing web vitals metrics in Firebase performance for Web.

Modifies export to use sendBeacon instead of fetch API, and shifts the upload time to the first time the page is hidden or unloaded.

Author: bryanatkinson

packages/performance/package.json

@@ -14,9 +14,7 @@
     },
     "./package.json": "./package.json"
   },
-  "files": [
-    "dist"
-  ],
+  "files": ["dist"],
   "scripts": {
     "lint": "eslint -c .eslintrc.js '**/*.ts' --ignore-path '../../.gitignore'",
     "lint:fix": "eslint --fix -c .eslintrc.js '**/*.ts' --ignore-path '../../.gitignore'",
@@ -42,7 +40,8 @@
     "@firebase/installations": "0.6.11",
     "@firebase/util": "1.10.2",
     "@firebase/component": "0.6.11",
-    "tslib": "^2.1.0"
+    "tslib": "^2.1.0",
+    "web-vitals": "^4.2.4"
   },
   "license": "Apache-2.0",
   "devDependencies": {
@@ -62,9 +61,7 @@
   },
   "typings": "dist/src/index.d.ts",
   "nyc": {
-    "extension": [
-      ".ts"
-    ],
+    "extension": [".ts"],
     "reportDir": "./coverage/node"
   }
 }

packages/performance/src/constants.ts

@@ -33,6 +33,15 @@ export const FIRST_CONTENTFUL_PAINT_COUNTER_NAME = '_fcp';
 
 export const FIRST_INPUT_DELAY_COUNTER_NAME = '_fid';
 
+export const LARGEST_CONTENTFUL_PAINT_METRIC_NAME = '_lcp';
+export const LARGEST_CONTENTFUL_PAINT_ATTRIBUTE_NAME = 'lcp_element';
+
+export const INTERACTION_TO_NEXT_PAINT_METRIC_NAME = '_inp';
+export const INTERACTION_TO_NEXT_PAINT_ATTRIBUTE_NAME = 'inp_interactionTarget';
+
+export const CUMULATIVE_LAYOUT_SHIFT_METRIC_NAME = '_cls';
+export const CUMULATIVE_LAYOUT_SHIFT_ATTRIBUTE_NAME = 'cls_largestShiftTarget';
+
 export const CONFIG_LOCAL_STORAGE_KEY = '@firebase/performance/config';
 
 export const CONFIG_EXPIRY_LOCAL_STORAGE_KEY =

packages/performance/src/resources/trace.ts

@@ -22,10 +22,16 @@ import {
   OOB_TRACE_PAGE_LOAD_PREFIX,
   FIRST_PAINT_COUNTER_NAME,
   FIRST_CONTENTFUL_PAINT_COUNTER_NAME,
-  FIRST_INPUT_DELAY_COUNTER_NAME
+  FIRST_INPUT_DELAY_COUNTER_NAME,
+  LARGEST_CONTENTFUL_PAINT_METRIC_NAME,
+  LARGEST_CONTENTFUL_PAINT_ATTRIBUTE_NAME,
+  INTERACTION_TO_NEXT_PAINT_METRIC_NAME,
+  INTERACTION_TO_NEXT_PAINT_ATTRIBUTE_NAME,
+  CUMULATIVE_LAYOUT_SHIFT_METRIC_NAME,
+  CUMULATIVE_LAYOUT_SHIFT_ATTRIBUTE_NAME
 } from '../constants';
 import { Api } from '../services/api_service';
-import { logTrace } from '../services/perf_logger';
+import { logTrace, flushLogs } from '../services/perf_logger';
 import { ERROR_FACTORY, ErrorCode } from '../utils/errors';
 import {
   isValidCustomAttributeName,
@@ -37,6 +43,7 @@ import {
 } from '../utils/metric_utils';
 import { PerformanceTrace } from '../public_types';
 import { PerformanceController } from '../controllers/perf';
+import { CoreVitalMetric, WebVitalMetrics } from './web_vitals';
 
 const enum TraceState {
   UNINITIALIZED = 1,
@@ -279,6 +286,7 @@ export class Trace implements PerformanceTrace {
     performanceController: PerformanceController,
     navigationTimings: PerformanceNavigationTiming[],
     paintTimings: PerformanceEntry[],
+    webVitalMetrics: WebVitalMetrics,
     firstInputDelay?: number
   ): void {
     const route = Api.getInstance().getUrl();
@@ -340,7 +348,43 @@ export class Trace implements PerformanceTrace {
       }
     }
 
+    this.addWebVitalMetric(
+      trace,
+      LARGEST_CONTENTFUL_PAINT_METRIC_NAME,
+      LARGEST_CONTENTFUL_PAINT_ATTRIBUTE_NAME,
+      webVitalMetrics.lcp
+    );
+    this.addWebVitalMetric(
+      trace,
+      CUMULATIVE_LAYOUT_SHIFT_METRIC_NAME,
+      CUMULATIVE_LAYOUT_SHIFT_ATTRIBUTE_NAME,
+      webVitalMetrics.cls
+    );
+    this.addWebVitalMetric(
+      trace,
+      INTERACTION_TO_NEXT_PAINT_METRIC_NAME,
+      INTERACTION_TO_NEXT_PAINT_ATTRIBUTE_NAME,
+      webVitalMetrics.inp
+    );
+
+    // Page load logs are sent at unload time and so should be logged and
+    // flushed immediately.
     logTrace(trace);
+    flushLogs();
+  }
+
+  static addWebVitalMetric(
+    trace: Trace,
+    metricKey: string,
+    attributeKey: string,
+    metric?: CoreVitalMetric
+  ): void {
+    if (metric) {
+      trace.putMetric(metricKey, Math.floor(metric.value * 1000));
+      if (metric.elementAttribution) {
+        trace.putAttribute(attributeKey, metric.elementAttribution);
+      }
+    }
   }
 
   static createUserTimingTrace(

packages/performance/src/resources/web_vitals.ts

@@ -0,0 +1,27 @@
+/**
+ * @license
+ * Copyright 2024 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+export interface CoreVitalMetric {
+  value: number;
+  elementAttribution?: string;
+}
+
+export interface WebVitalMetrics {
+  cls?: CoreVitalMetric;
+  inp?: CoreVitalMetric;
+  lcp?: CoreVitalMetric;
+}

packages/performance/src/services/oob_resources_service.ts

@@ -21,9 +21,22 @@ import { createNetworkRequestEntry } from '../resources/network_request';
 import { TRACE_MEASURE_PREFIX } from '../constants';
 import { getIid } from './iid_service';
 import { PerformanceController } from '../controllers/perf';
+import { WebVitalMetrics } from '../resources/web_vitals';
+import {
+  onCLS,
+  onLCP,
+  onINP,
+  LCPMetricWithAttribution,
+  CLSMetricWithAttribution,
+  INPMetricWithAttribution
+} from 'web-vitals/attribution';
 
 const FID_WAIT_TIME_MS = 5000;
 
+const webVitalMetrics: WebVitalMetrics = {};
+
+let sentPageLoadTrace: boolean = false;
+
 export function setupOobResources(
   performanceController: PerformanceController
 ): void {
@@ -53,41 +66,40 @@ function setupNetworkRequests(
 
 function setupOobTraces(performanceController: PerformanceController): void {
   const api = Api.getInstance();
-  const navigationTimings = api.getEntriesByType(
-    'navigation'
-  ) as PerformanceNavigationTiming[];
-  const paintTimings = api.getEntriesByType('paint');
-  // If First Input Delay polyfill is added to the page, report the fid value.
-  // https://github.com/GoogleChromeLabs/first-input-delay
-  if (api.onFirstInputDelay) {
-    // If the fid call back is not called for certain time, continue without it.
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    let timeoutId: any = setTimeout(() => {
-      Trace.createOobTrace(
-        performanceController,
-        navigationTimings,
-        paintTimings
-      );
-      timeoutId = undefined;
-    }, FID_WAIT_TIME_MS);
-    api.onFirstInputDelay((fid: number) => {
-      if (timeoutId) {
-        clearTimeout(timeoutId);
-        Trace.createOobTrace(
-          performanceController,
-          navigationTimings,
-          paintTimings,
-          fid
-        );
-      }
-    });
+  // Better support for Safari
+  if ('onpagehide' in window) {
+    api.document.addEventListener('pagehide', () =>
+      sendOobTrace(performanceController)
+    );
   } else {
-    Trace.createOobTrace(
-      performanceController,
-      navigationTimings,
-      paintTimings
+    api.document.addEventListener('unload', () =>
+      sendOobTrace(performanceController)
     );
   }
+  api.document.addEventListener('visibilitychange', () => {
+    if (api.document.visibilityState === 'hidden') {
+      sendOobTrace(performanceController);
+    }
+  });
+
+  onLCP((metric: LCPMetricWithAttribution) => {
+    webVitalMetrics.lcp = {
+      value: metric.value,
+      elementAttribution: metric.attribution.element
+    };
+  });
+  onCLS((metric: CLSMetricWithAttribution) => {
+    webVitalMetrics.cls = {
+      value: metric.value,
+      elementAttribution: metric.attribution.largestShiftTarget
+    };
+  });
+  onINP((metric: INPMetricWithAttribution) => {
+    webVitalMetrics.inp = {
+      value: metric.value,
+      elementAttribution: metric.attribution.interactionTarget
+    };
+  });
 }
 
 function setupUserTimingTraces(
@@ -119,3 +131,48 @@ function createUserTimingTrace(
   }
   Trace.createUserTimingTrace(performanceController, measureName);
 }
+
+function sendOobTrace(performanceController: PerformanceController): void {
+  if (!sentPageLoadTrace) {
+    sentPageLoadTrace = true;
+    const api = Api.getInstance();
+    const navigationTimings = api.getEntriesByType(
+      'navigation'
+    ) as PerformanceNavigationTiming[];
+    const paintTimings = api.getEntriesByType('paint');
+    // If First Input Delay polyfill is added to the page, report the fid value.
+    // https://github.com/GoogleChromeLabs/first-input-delay
+    if (api.onFirstInputDelay) {
+      // If the fid call back is not called for certain time, continue without it.
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      let timeoutId: any = setTimeout(() => {
+        Trace.createOobTrace(
+          performanceController,
+          navigationTimings,
+          paintTimings,
+          webVitalMetrics
+        );
+        timeoutId = undefined;
+      }, FID_WAIT_TIME_MS);
+      api.onFirstInputDelay((fid: number) => {
+        if (timeoutId) {
+          clearTimeout(timeoutId);
+          Trace.createOobTrace(
+            performanceController,
+            navigationTimings,
+            paintTimings,
+            webVitalMetrics,
+            fid
+          );
+        }
+      });
+    } else {
+      Trace.createOobTrace(
+        performanceController,
+        navigationTimings,
+        paintTimings,
+        webVitalMetrics
+      );
+    }
+  }
+}

packages/performance/src/services/perf_logger.ts

@@ -23,14 +23,13 @@ import { SettingsService } from './settings_service';
 import {
   getServiceWorkerStatus,
   getVisibilityState,
-  VisibilityState,
   getEffectiveConnectionType
 } from '../utils/attributes_utils';
 import {
   isPerfInitialized,
   getInitializationPromise
 } from './initialization_service';
-import { transportHandler } from './transport_service';
+import { transportHandler, flushQueuedEvents } from './transport_service';
 import { SDK_VERSION } from '../constants';
 import { FirebaseApp } from '@firebase/app';
 import { getAppId } from '../utils/app_utils';
@@ -85,19 +84,25 @@ interface TraceMetric {
   custom_attributes?: { [key: string]: string };
 }
 
-let logger: (
-  resource: NetworkRequest | Trace,
-  resourceType: ResourceType
-) => void | undefined;
+interface Logger {
+  send: (resource: NetworkRequest | Trace, resourceType: ResourceType) => void | undefined;
+  flush: () => void;
+}
+
+let logger: Logger;
+//
 // This method is not called before initialization.
 function sendLog(
   resource: NetworkRequest | Trace,
   resourceType: ResourceType
 ): void {
   if (!logger) {
-    logger = transportHandler(serializer);
+    logger = {
+      send: transportHandler(serializer),
+      flush: flushQueuedEvents,
+    };
   }
-  logger(resource, resourceType);
+  logger.send(resource, resourceType);
 }
 
 export function logTrace(trace: Trace): void {
@@ -115,11 +120,6 @@ export function logTrace(trace: Trace): void {
     return;
   }
 
-  // Only log the page load auto traces if page is visible.
-  if (trace.isAuto && getVisibilityState() !== VisibilityState.VISIBLE) {
-    return;
-  }
-
   if (isPerfInitialized()) {
     sendTraceLog(trace);
   } else {
@@ -132,6 +132,12 @@ export function logTrace(trace: Trace): void {
   }
 }
 
+export function flushLogs(): void {
+  if (logger) {
+    logger.flush();
+  }
+}
+
 function sendTraceLog(trace: Trace): void {
   if (!getIid()) {
     return;
@@ -145,7 +151,7 @@ function sendTraceLog(trace: Trace): void {
     return;
   }
 
-  setTimeout(() => sendLog(trace, ResourceType.Trace), 0);
+  sendLog(trace, ResourceType.Trace);
 }
 
 export function logNetworkRequest(networkRequest: NetworkRequest): void {
@@ -177,7 +183,7 @@ export function logNetworkRequest(networkRequest: NetworkRequest): void {
     return;
   }
 
-  setTimeout(() => sendLog(networkRequest, ResourceType.NetworkRequest), 0);
+  sendLog(networkRequest, ResourceType.NetworkRequest);
 }
 
 function serializer(