Fireperf web vitals (#8644)

* Add support for capturing web vitals metrics in Firebase performance for Web (Largest Contentful Paint, Interaction to Next Paint, Cumulative Layout Shift)
* 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

.changeset/kind-dingos-work.md

@@ -0,0 +1,6 @@
+---
+'@firebase/performance': minor
+'firebase': minor
+---
+
+Collect web vital metrics (INP,CLS,LCP) as part of page load event.

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.12",
     "@firebase/util": "1.10.3",
     "@firebase/component": "0.6.12",
-    "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/api_service.ts

@@ -18,6 +18,14 @@
 import { ERROR_FACTORY, ErrorCode } from '../utils/errors';
 import { isIndexedDBAvailable, areCookiesEnabled } from '@firebase/util';
 import { consoleLogger } from '../utils/console_logger';
+import {
+  CLSMetricWithAttribution,
+  INPMetricWithAttribution,
+  LCPMetricWithAttribution,
+  onCLS as vitalsOnCLS,
+  onINP as vitalsOnINP,
+  onLCP as vitalsOnLCP
+} from 'web-vitals/attribution';
 
 declare global {
   interface Window {
@@ -47,6 +55,9 @@ export class Api {
   private readonly PerformanceObserver: typeof PerformanceObserver;
   private readonly windowLocation: Location;
   readonly onFirstInputDelay?: (fn: (fid: number) => void) => void;
+  readonly onLCP: (fn: (metric: LCPMetricWithAttribution) => void) => void;
+  readonly onINP: (fn: (metric: INPMetricWithAttribution) => void) => void;
+  readonly onCLS: (fn: (metric: CLSMetricWithAttribution) => void) => void;
   readonly localStorage?: Storage;
   readonly document: Document;
   readonly navigator: Navigator;
@@ -68,6 +79,9 @@ export class Api {
     if (window.perfMetrics && window.perfMetrics.onFirstInputDelay) {
       this.onFirstInputDelay = window.perfMetrics.onFirstInputDelay;
     }
+    this.onLCP = vitalsOnLCP;
+    this.onINP = vitalsOnINP;
+    this.onCLS = vitalsOnCLS;
   }
 
   getUrl(): string {