✨ [RUMF-777] implement Cumulative Layout Shift

packages/rum/src/browser/performanceCollection.ts

@@ -68,19 +68,26 @@ export interface RumFirstInputTiming {
   processingStart: number
 }
 
+export interface RumLayoutShiftTiming {
+  entryType: 'layout-shift'
+  value: number
+  hadRecentInput: boolean
+}
+
 export type RumPerformanceEntry =
   | RumPerformanceResourceTiming
   | RumPerformanceLongTaskTiming
   | RumPerformancePaintTiming
   | RumPerformanceNavigationTiming
   | RumLargestContentfulPaintTiming
   | RumFirstInputTiming
+  | RumLayoutShiftTiming
 
 function supportPerformanceObject() {
   return window.performance !== undefined && 'getEntries' in performance
 }
 
-function supportPerformanceTimingEvent(entryType: string) {
+export function supportPerformanceTimingEvent(entryType: string) {
   return (
     (window as BrowserWindow).PerformanceObserver &&
     PerformanceObserver.supportedEntryTypes !== undefined &&
@@ -100,7 +107,15 @@ export function startPerformanceCollection(lifeCycle: LifeCycle, configuration:
     const observer = new PerformanceObserver(
       monitor((entries) => handlePerformanceEntries(lifeCycle, configuration, entries.getEntries()))
     )
-    const entryTypes = ['resource', 'navigation', 'longtask', 'paint', 'largest-contentful-paint', 'first-input']
+    const entryTypes = [
+      'resource',
+      'navigation',
+      'longtask',
+      'paint',
+      'largest-contentful-paint',
+      'first-input',
+      'layout-shift',
+    ]
 
     observer.observe({ entryTypes })
 
@@ -267,7 +282,8 @@ function handlePerformanceEntries(lifeCycle: LifeCycle, configuration: Configura
       entry.entryType === 'paint' ||
       entry.entryType === 'longtask' ||
       entry.entryType === 'largest-contentful-paint' ||
-      entry.entryType === 'first-input'
+      entry.entryType === 'first-input' ||
+      entry.entryType === 'layout-shift'
     ) {
       handleRumPerformanceEntry(lifeCycle, configuration, entry as RumPerformanceEntry)
     }

packages/rum/src/domain/rumEventsCollection/view/trackViews.spec.ts

@@ -885,4 +885,66 @@ describe('rum view measures', () => {
       expect(getHandledCount()).toEqual(3)
     })
   })
+
+  describe('cumulativeLayoutShift', () => {
+    let isLayoutShiftSupported: boolean
+    beforeEach(() => {
+      if (!('PerformanceObserver' in window) || !('supportedEntryTypes' in PerformanceObserver)) {
+        pending('No PerformanceObserver support')
+      }
+      isLayoutShiftSupported = true
+      spyOnProperty(PerformanceObserver, 'supportedEntryTypes', 'get').and.callFake(() => {
+        return isLayoutShiftSupported ? ['layout-shift'] : []
+      })
+    })
+
+    it('should be initialized to 0', () => {
+      setupBuilder.build()
+      expect(getHandledCount()).toEqual(1)
+      expect(getViewEvent(0).cumulativeLayoutShift).toBe(0)
+    })
+
+    it('should be initialized to undefined if layout-shift is not supported', () => {
+      isLayoutShiftSupported = false
+      setupBuilder.build()
+      expect(getHandledCount()).toEqual(1)
+      expect(getViewEvent(0).cumulativeLayoutShift).toBe(undefined)
+    })
+
+    it('should accmulate layout shift values', () => {
+      const { lifeCycle, clock } = setupBuilder.withFakeClock().build()
+
+      lifeCycle.notify(LifeCycleEventType.PERFORMANCE_ENTRY_COLLECTED, {
+        entryType: 'layout-shift',
+        hadRecentInput: false,
+        value: 0.1,
+      })
+
+      lifeCycle.notify(LifeCycleEventType.PERFORMANCE_ENTRY_COLLECTED, {
+        entryType: 'layout-shift',
+        hadRecentInput: false,
+        value: 0.2,
+      })
+
+      clock.tick(THROTTLE_VIEW_UPDATE_PERIOD)
+
+      expect(getHandledCount()).toEqual(2)
+      expect(getViewEvent(1).cumulativeLayoutShift).toBe(0.1 + 0.2)
+    })
+
+    it('should ignore entries with recent input', () => {
+      const { lifeCycle, clock } = setupBuilder.withFakeClock().build()
+
+      lifeCycle.notify(LifeCycleEventType.PERFORMANCE_ENTRY_COLLECTED, {
+        entryType: 'layout-shift',
+        hadRecentInput: true,
+        value: 0.1,
+      })
+
+      clock.tick(THROTTLE_VIEW_UPDATE_PERIOD)
+
+      expect(getHandledCount()).toEqual(1)
+      expect(getViewEvent(0).cumulativeLayoutShift).toBe(0)
+    })
+  })
 })

packages/rum/src/domain/rumEventsCollection/view/trackViews.ts

@@ -1,5 +1,6 @@
-import { addEventListener, DOM_EVENT, generateUUID, monitor, ONE_MINUTE, throttle } from '@datadog/browser-core'
+import { addEventListener, DOM_EVENT, generateUUID, monitor, noop, ONE_MINUTE, throttle } from '@datadog/browser-core'
 
+import { supportPerformanceTimingEvent } from '../../../browser/performanceCollection'
 import { LifeCycle, LifeCycleEventType } from '../../lifeCycle'
 import { EventCounts, trackEventCounts } from '../../trackEventCounts'
 import { waitIdlePageActivity } from '../../trackPageActivities'
@@ -16,6 +17,7 @@ export interface View {
   duration: number
   loadingTime?: number | undefined
   loadingType: ViewLoadingType
+  cumulativeLayoutShift?: number
 }
 
 export interface ViewCreatedEvent {
@@ -105,6 +107,7 @@ function newView(
   }
   let timings: Timings = {}
   let documentVersion = 0
+  let cumulativeLayoutShift: number | undefined
   let loadingTime: number | undefined
   let endTime: number | undefined
   let location: Location = { ...initialLocation }
@@ -132,12 +135,24 @@ function newView(
 
   const { stop: stopActivityLoadingTimeTracking } = trackActivityLoadingTime(lifeCycle, setActivityLoadingTime)
 
+  let stopCLSTracking: () => void
+  if (isLayoutShiftSupported()) {
+    cumulativeLayoutShift = 0
+    ;({ stop: stopCLSTracking } = trackLayoutShift(lifeCycle, (layoutShift) => {
+      cumulativeLayoutShift! += layoutShift
+      scheduleViewUpdate()
+    }))
+  } else {
+    stopCLSTracking = noop
+  }
+
   // Initial view update
   triggerViewUpdate()
 
   function triggerViewUpdate() {
     documentVersion += 1
     lifeCycle.notify(LifeCycleEventType.VIEW_UPDATED, {
+      cumulativeLayoutShift,
       documentVersion,
       eventCounts,
       id,
@@ -157,6 +172,7 @@ function newView(
       endTime = performance.now()
       stopEventCountsTracking()
       stopActivityLoadingTimeTracking()
+      stopCLSTracking()
     },
     isDifferentView(otherLocation: Location) {
       return (
@@ -250,3 +266,31 @@ function trackActivityLoadingTime(lifeCycle: LifeCycle, callback: (loadingTimeVa
 
   return { stop: stopWaitIdlePageActivity }
 }
+
+/**
+ * Track layout shifts (LS) occuring during the Views.  This yields multiple values that can be
+ * added up to compute the cumulated layout shift (CLS).
+ *
+ * See isLayoutShiftSupported to check for browser support.
+ *
+ * Documentation: https://web.dev/cls/
+ * Reference implementation: https://github.com/GoogleChrome/web-vitals/blob/master/src/getCLS.ts
+ */
+function trackLayoutShift(lifeCycle: LifeCycle, callback: (layoutShift: number) => void) {
+  const { unsubscribe: stop } = lifeCycle.subscribe(LifeCycleEventType.PERFORMANCE_ENTRY_COLLECTED, (entry) => {
+    if (entry.entryType === 'layout-shift' && !entry.hadRecentInput) {
+      callback(entry.value)
+    }
+  })
+
+  return {
+    stop,
+  }
+}
+
+/**
+ * Check whether `layout-shift` is supported by the browser.
+ */
+function isLayoutShiftSupported() {
+  return supportPerformanceTimingEvent('layout-shift')
+}

packages/rum/src/domain/rumEventsCollection/view/viewCollection.spec.ts

@@ -99,6 +99,7 @@ describe('viewCollection V2', () => {
   it('should create view from view update', () => {
     const { lifeCycle, rawRumEventsV2 } = setupBuilder.build()
     const view = {
+      cumulativeLayoutShift: 1,
       documentVersion: 3,
       duration: 100,
       eventCounts: {
@@ -136,6 +137,7 @@ describe('viewCollection V2', () => {
         action: {
           count: 10,
         },
+        cumulativeLayoutShift: 1,
         domComplete: 10 * 1e6,
         domContentLoaded: 10 * 1e6,
         domInteractive: 10 * 1e6,

packages/rum/src/domain/rumEventsCollection/view/viewCollection.ts

@@ -54,6 +54,7 @@ function processViewUpdateV2(view: View) {
       action: {
         count: view.eventCounts.userActionCount,
       },
+      cumulativeLayoutShift: view.cumulativeLayoutShift,
       domComplete: msToNs(view.timings.domComplete),
       domContentLoaded: msToNs(view.timings.domContentLoaded),
       domInteractive: msToNs(view.timings.domInteractive),

packages/rum/src/typesV2.ts

@@ -58,6 +58,7 @@ export interface RumViewEventV2 {
     loadingType: ViewLoadingType
     firstContentfulPaint?: number
     firstInputDelay?: number
+    cumulativeLayoutShift?: number
     largestContentfulPaint?: number
     domInteractive?: number
     domContentLoaded?: number