Add time to first byte collection (#7)

* add adr and ttfb collection

* update tests for ttfb

documents/adr/001-web-vitals.md

@@ -0,0 +1,17 @@
+# 001-web-vitals
+
+## Status
+
+Approved
+
+## Context
+
+There is good adoption of synthetic performance testing tools, particularly Google Lighthouse and [Page Speed Insights](https://pagespeed.web.dev). There are not as many widely deployed tools to anonymously collect field measurements of  page speed performance from real users in a way that adequately captures their experience when using federal web properties.    
+
+## Decision
+
+Google Analytics through the Digital Analytics Program within the federal government already has good adoption within the federal government. The `web-vitals.js` library from Google was selected as a way to instrument a website or application with performance collection. This library was chosen for its stability, as well as its completeness, as it is the basis of many commercial offerings (e.g. DataDog, Sentry) and its wide deployment through the Chrome Devtools Performance Panel. 
+
+## Consequences
+
+This proposes an optional add-on for teams to be able to add and collect metrics on what a real user experiences as it relates to the universal performance indicators known as Core Web Vitals.

src/format-event-data.ts

@@ -3,14 +3,16 @@ import type {
   FCPAttribution,
   INPAttribution,
   LCPAttribution,
+  TTFBAttribution,
 } from 'web-vitals';
 
-export type WebVitalsName = 'CLS' | 'FCP' | 'INP' | 'LCP';
+export type WebVitalsName = 'CLS' | 'FCP' | 'INP' | 'LCP' | 'TTFB';
 export type WebVitalsAttribution =
   | CLSAttribution
   | FCPAttribution
   | INPAttribution
-  | LCPAttribution;
+  | LCPAttribution
+  | TTFBAttribution;
 
 export const formatEventData = (
   name: WebVitalsName,
@@ -69,6 +71,18 @@ export const formatEventData = (
         debug_target: (attribution as LCPAttribution).element || '(not set)',
       };
     }
+    if (name === 'TTFB') {
+      return {
+        debug_waiting_duration: (attribution as TTFBAttribution)
+          .waitingDuration,
+        debug_dns_duration: (attribution as TTFBAttribution).dnsDuration,
+        debug_connection_duration: (attribution as TTFBAttribution)
+          .connectionDuration,
+        debug_cache_duration: (attribution as TTFBAttribution).cacheDuration,
+        debug_request_duration: (attribution as TTFBAttribution)
+          .requestDuration,
+      };
+    }
   }
   // Return default/empty params in case there is no attribution.
   return {

src/index.ts

@@ -1,11 +1,12 @@
-import { onCLS, onINP, onFCP, onLCP } from './web-vitals.js';
+import { onCLS, onINP, onFCP, onLCP, onTTFB } from './web-vitals.js';
 import { sendToAnalytics } from './send-to-analytics.js';
 
 const initWebVitalsEvents = () => {
   onCLS(sendToAnalytics);
   onFCP(sendToAnalytics);
   onINP(sendToAnalytics);
   onLCP(sendToAnalytics);
+  onTTFB(sendToAnalytics);
 };
 
 if (typeof window !== 'undefined' && 'gas4' in window) {

src/send-to-analytics.ts

@@ -3,6 +3,7 @@ import type {
   FCPMetricWithAttribution,
   INPMetricWithAttribution,
   LCPMetricWithAttribution,
+  TTFBMetricWithAttribution,
 } from 'web-vitals';
 
 import { formatEventData, type WebVitalsName } from './format-event-data.js';
@@ -11,7 +12,8 @@ export type WebVitalsWithAttribution =
   | CLSMetricWithAttribution
   | FCPMetricWithAttribution
   | INPMetricWithAttribution
-  | LCPMetricWithAttribution;
+  | LCPMetricWithAttribution
+  | TTFBMetricWithAttribution;
 
 declare const gas4: unknown;
 

src/web-vitals.ts

@@ -1,3 +1,3 @@
-import { onCLS, onINP, onFCP, onLCP } from 'web-vitals/attribution';
+import { onCLS, onINP, onFCP, onLCP, onTTFB } from 'web-vitals/attribution';
 
-export { onCLS, onINP, onFCP, onLCP };
+export { onCLS, onINP, onFCP, onLCP, onTTFB };

test/unit/dap-performance-addon.test.ts

@@ -1,11 +1,12 @@
 import { it, describe, expect } from 'vitest';
-import { onCLS, onFCP, onINP, onLCP } from '../../src/web-vitals.js';
+import { onCLS, onFCP, onINP, onLCP, onTTFB } from '../../src/web-vitals.js';
 
 describe('DAP Performance Addon', () => {
   it('defines methods to track Core Web Vitals', () => {
     expect(typeof onCLS).toBe('function');
     expect(typeof onFCP).toBe('function');
     expect(typeof onINP).toBe('function');
     expect(typeof onLCP).toBe('function');
+    expect(typeof onTTFB).toBe('function');
   });
 });

test/unit/format-event-data.test.ts

@@ -5,6 +5,7 @@ import type {
   FCPAttribution,
   INPAttribution,
   LCPAttribution,
+  TTFBAttribution,
 } from 'web-vitals';
 
 describe('formatEventData', () => {
@@ -91,6 +92,26 @@ describe('formatEventData', () => {
     });
   });
 
+  it('should format TTFB data correctly', () => {
+    const attribution = {
+      waitingDuration: 0,
+      cacheDuration: 0,
+      dnsDuration: 0,
+      connectionDuration: 2015,
+      requestDuration: 47,
+    } as TTFBAttribution;
+
+    const result = formatEventData('TTFB', attribution);
+
+    expect(result).toEqual({
+      debug_cache_duration: attribution.cacheDuration,
+      debug_connection_duration: attribution.connectionDuration,
+      debug_dns_duration: attribution.dnsDuration,
+      debug_request_duration: attribution.requestDuration,
+      debug_waiting_duration: attribution.waitingDuration,
+    });
+  });
+
   it('should return default/empty params if no attribution data is provided', () => {
     // @ts-expect-error - unknown is not valid
     const result = formatEventData('unknown', null);
@@ -460,3 +481,93 @@ describe('formatEventData', () => {
 //     }
 //   }
 // }
+
+// {
+//   "name": "TTFB",
+//   "value": 2062,
+//   "rating": "poor",
+//   "delta": 2062,
+//   "entries": [
+//     {
+//       "name": "http://localhost:8000/demo/",
+//       "entryType": "navigation",
+//       "startTime": 0,
+//       "duration": 4181,
+//       "initiatorType": "navigation",
+//       "nextHopProtocol": "http/1.1",
+//       "workerStart": 0,
+//       "redirectStart": 0,
+//       "redirectEnd": 0,
+//       "fetchStart": -21,
+//       "domainLookupStart": -21,
+//       "domainLookupEnd": -21,
+//       "connectStart": -21,
+//       "connectEnd": 2015,
+//       "secureConnectionStart": 0,
+//       "requestStart": 2016,
+//       "responseStart": 2062,
+//       "responseEnd": 2062,
+//       "transferSize": 4277,
+//       "encodedBodySize": 3977,
+//       "decodedBodySize": 3977,
+//       "responseStatus": 200,
+//       "contentType": "text/html",
+//       "serverTiming": [],
+//       "unloadEventStart": 0,
+//       "unloadEventEnd": 0,
+//       "domInteractive": 2126,
+//       "domContentLoadedEventStart": 2199,
+//       "domContentLoadedEventEnd": 2200,
+//       "domComplete": 4180,
+//       "loadEventStart": 4180,
+//       "loadEventEnd": 4181,
+//       "type": "navigate",
+//       "redirectCount": 0
+//     }
+//   ],
+//   "id": "v4-1732826806920-8943990242578",
+//   "navigationType": "navigate",
+//   "attribution": {
+//     "waitingDuration": 0,
+//     "cacheDuration": 0,
+//     "dnsDuration": 0,
+//     "connectionDuration": 2015,
+//     "requestDuration": 47,
+//     "navigationEntry": {
+//       "name": "http://localhost:8000/demo/",
+//       "entryType": "navigation",
+//       "startTime": 0,
+//       "duration": 4181,
+//       "initiatorType": "navigation",
+//       "nextHopProtocol": "http/1.1",
+//       "workerStart": 0,
+//       "redirectStart": 0,
+//       "redirectEnd": 0,
+//       "fetchStart": -21,
+//       "domainLookupStart": -21,
+//       "domainLookupEnd": -21,
+//       "connectStart": -21,
+//       "connectEnd": 2015,
+//       "secureConnectionStart": 0,
+//       "requestStart": 2016,
+//       "responseStart": 2062,
+//       "responseEnd": 2062,
+//       "transferSize": 4277,
+//       "encodedBodySize": 3977,
+//       "decodedBodySize": 3977,
+//       "responseStatus": 200,
+//       "contentType": "text/html",
+//       "serverTiming": [],
+//       "unloadEventStart": 0,
+//       "unloadEventEnd": 0,
+//       "domInteractive": 2126,
+//       "domContentLoadedEventStart": 2199,
+//       "domContentLoadedEventEnd": 2200,
+//       "domComplete": 4180,
+//       "loadEventStart": 4180,
+//       "loadEventEnd": 4181,
+//       "type": "navigate",
+//       "redirectCount": 0
+//     }
+//   }
+// }