✨[PANA-3817] Add telemetry for initial view metrics (#3788)

Author: sethfowler-datadog

packages/rum-core/src/boot/startRum.ts

@@ -56,6 +56,7 @@ import { startTrackingConsentContext } from '../domain/contexts/trackingConsentC
 import type { Hooks } from '../domain/hooks'
 import { createHooks } from '../domain/hooks'
 import { startEventCollection } from '../domain/event/eventCollection'
+import { startInitialViewMetricsTelemetry } from '../domain/view/viewMetrics/startInitialViewMetricsTelemetry'
 import type { RecorderApi, ProfilerApi } from './rumPublicApi'
 
 export type StartRum = typeof startRum
@@ -180,6 +181,13 @@ export function startRum(
 
   cleanupTasks.push(stopViewCollection)
 
+  const { stop: stopInitialViewMetricsTelemetry } = startInitialViewMetricsTelemetry(
+    configuration,
+    lifeCycle,
+    telemetry
+  )
+  cleanupTasks.push(stopInitialViewMetricsTelemetry)
+
   const { stop: stopResourceCollection } = startResourceCollection(lifeCycle, configuration, pageStateHistory)
   cleanupTasks.push(stopResourceCollection)
 

packages/rum-core/src/domain/configuration/configuration.ts

@@ -247,6 +247,7 @@ export interface RumConfiguration extends Configuration {
   trackBfcacheViews: boolean
   subdomain?: string
   customerDataTelemetrySampleRate: number
+  initialViewMetricsTelemetrySampleRate: number
   segmentTelemetrySampleRate: number
   traceContextInjection: TraceContextInjection
   plugins: RumPlugin[]
@@ -319,6 +320,7 @@ export function validateAndBuildRumConfiguration(
       : DefaultPrivacyLevel.MASK,
     enablePrivacyForActionName: !!initConfiguration.enablePrivacyForActionName,
     customerDataTelemetrySampleRate: 1,
+    initialViewMetricsTelemetrySampleRate: 1,
     segmentTelemetrySampleRate: 1,
     traceContextInjection: objectHasValue(TraceContextInjection, initConfiguration.traceContextInjection)
       ? initConfiguration.traceContextInjection

packages/rum-core/src/domain/view/viewMetrics/startInitialViewMetricsTelemetry.spec.ts

@@ -0,0 +1,127 @@
+import type { Telemetry, RelativeTime, Duration, RawTelemetryEvent } from '@datadog/browser-core'
+import type { MockTelemetry } from '@datadog/browser-core/test'
+import { registerCleanupTask, startMockTelemetry } from '@datadog/browser-core/test'
+import type { RumConfiguration } from '@datadog/browser-rum-core'
+import { LifeCycle, LifeCycleEventType } from '../../lifeCycle'
+import { mockRumConfiguration } from '../../../../test'
+import type { ViewEvent } from '../trackViews'
+import { startInitialViewMetricsTelemetry } from './startInitialViewMetricsTelemetry'
+import type { InitialViewMetrics } from './trackInitialViewMetrics'
+
+const VIEW_METRICS: Partial<InitialViewMetrics> = {
+  largestContentfulPaint: {
+    value: 100 as RelativeTime,
+  },
+  navigationTimings: {
+    domComplete: 10 as Duration,
+    domContentLoaded: 20 as Duration,
+    domInteractive: 30 as Duration,
+    firstByte: 40 as Duration,
+    loadEvent: 50 as Duration,
+  },
+}
+
+const TELEMETRY_FOR_VIEW_METRICS: RawTelemetryEvent = {
+  type: 'log',
+  status: 'debug',
+  message: 'Initial view metrics',
+  metrics: {
+    lcp: {
+      value: 100,
+    },
+    navigation: {
+      domComplete: 10,
+      domContentLoaded: 20,
+      domInteractive: 30,
+      firstByte: 40,
+      loadEvent: 50,
+    },
+  },
+}
+
+describe('startInitialViewMetricsTelemetry', () => {
+  const lifeCycle = new LifeCycle()
+  let telemetry: MockTelemetry
+
+  const config: Partial<RumConfiguration> = {
+    maxTelemetryEventsPerPage: 2,
+    initialViewMetricsTelemetrySampleRate: 100,
+    telemetrySampleRate: 100,
+  }
+
+  function generateViewUpdateWithInitialViewMetrics(initialViewMetrics: Partial<InitialViewMetrics>) {
+    lifeCycle.notify(LifeCycleEventType.VIEW_UPDATED, { initialViewMetrics } as ViewEvent)
+  }
+
+  function startInitialViewMetricsTelemetryCollection(partialConfig: Partial<RumConfiguration> = config) {
+    const configuration = mockRumConfiguration(partialConfig)
+    telemetry = startMockTelemetry()
+    const { stop: stopInitialViewMetricsTelemetryCollection } = startInitialViewMetricsTelemetry(
+      configuration,
+      lifeCycle,
+      {
+        enabled: true,
+      } as Telemetry
+    )
+    registerCleanupTask(stopInitialViewMetricsTelemetryCollection)
+  }
+
+  it('should collect initial view metrics telemetry', async () => {
+    startInitialViewMetricsTelemetryCollection()
+    generateViewUpdateWithInitialViewMetrics(VIEW_METRICS)
+    expect(await telemetry.getEvents()).toEqual([jasmine.objectContaining(TELEMETRY_FOR_VIEW_METRICS)])
+  })
+
+  it('should not collect initial view metrics telemetry twice', async () => {
+    startInitialViewMetricsTelemetryCollection()
+
+    generateViewUpdateWithInitialViewMetrics(VIEW_METRICS)
+    expect(await telemetry.getEvents()).toEqual([jasmine.objectContaining(TELEMETRY_FOR_VIEW_METRICS)])
+    telemetry.reset()
+
+    generateViewUpdateWithInitialViewMetrics({
+      ...VIEW_METRICS,
+      largestContentfulPaint: {
+        value: 1000 as RelativeTime,
+      },
+    })
+    expect(await telemetry.hasEvents()).toBe(false)
+  })
+
+  it('should not collect initial view metrics telemetry until LCP is known', async () => {
+    startInitialViewMetricsTelemetryCollection()
+
+    generateViewUpdateWithInitialViewMetrics({
+      ...VIEW_METRICS,
+      largestContentfulPaint: undefined,
+    })
+    expect(await telemetry.hasEvents()).toBe(false)
+    telemetry.reset()
+
+    generateViewUpdateWithInitialViewMetrics(VIEW_METRICS)
+    expect(await telemetry.getEvents()).toEqual([jasmine.objectContaining(TELEMETRY_FOR_VIEW_METRICS)])
+  })
+
+  it('should not collect initial view metrics telemetry until navigation timings are known', async () => {
+    startInitialViewMetricsTelemetryCollection()
+
+    generateViewUpdateWithInitialViewMetrics({
+      ...VIEW_METRICS,
+      navigationTimings: undefined,
+    })
+    expect(await telemetry.hasEvents()).toBe(false)
+    telemetry.reset()
+
+    generateViewUpdateWithInitialViewMetrics(VIEW_METRICS)
+    expect(await telemetry.getEvents()).toEqual([jasmine.objectContaining(TELEMETRY_FOR_VIEW_METRICS)])
+  })
+
+  it('should not collect initial view metrics telemetry when telemetry is disabled', async () => {
+    startInitialViewMetricsTelemetryCollection({
+      telemetrySampleRate: 100,
+      initialViewMetricsTelemetrySampleRate: 0,
+    })
+    generateViewUpdateWithInitialViewMetrics(VIEW_METRICS)
+    expect(await telemetry.hasEvents()).toBe(false)
+  })
+})

packages/rum-core/src/domain/view/viewMetrics/startInitialViewMetricsTelemetry.ts

@@ -0,0 +1,79 @@
+import type { Context, Telemetry } from '@datadog/browser-core'
+import { performDraw, addTelemetryMetrics, noop } from '@datadog/browser-core'
+import { LifeCycleEventType } from '../../lifeCycle'
+import type { LifeCycle } from '../../lifeCycle'
+import type { RumConfiguration } from '../../configuration'
+import type { LargestContentfulPaint } from './trackLargestContentfulPaint'
+import type { NavigationTimings } from './trackNavigationTimings'
+
+const INITIAL_VIEW_METRICS_TELEMETRY_NAME = 'Initial view metrics'
+
+interface CoreInitialViewMetrics extends Context {
+  lcp: {
+    value: number
+  }
+  navigation: {
+    domComplete: number
+    domContentLoaded: number
+    domInteractive: number
+    firstByte: number | undefined
+    loadEvent: number
+  }
+}
+
+export function startInitialViewMetricsTelemetry(
+  configuration: RumConfiguration,
+  lifeCycle: LifeCycle,
+  telemetry: Telemetry
+) {
+  const initialViewMetricsTelemetryEnabled =
+    telemetry.enabled && performDraw(configuration.initialViewMetricsTelemetrySampleRate)
+  if (!initialViewMetricsTelemetryEnabled) {
+    return { stop: noop }
+  }
+
+  const { unsubscribe } = lifeCycle.subscribe(LifeCycleEventType.VIEW_UPDATED, ({ initialViewMetrics }) => {
+    if (!initialViewMetrics.largestContentfulPaint || !initialViewMetrics.navigationTimings) {
+      return
+    }
+
+    // The navigation timings become available shortly after the load event fires, so
+    // we're snapshotting the LCP value available at that point. However, more LCP values
+    // can be emitted until the page is scrolled or interacted with, so it's possible that
+    // the final LCP value may differ. These metrics are intended to help diagnose
+    // performance issues early in the page load process, and using LCP-at-page-load is a
+    // good fit for that use case, but it's important to be aware that this is not
+    // necessarily equivalent to the normal LCP metric.
+
+    addTelemetryMetrics(INITIAL_VIEW_METRICS_TELEMETRY_NAME, {
+      metrics: createCoreInitialViewMetrics(
+        initialViewMetrics.largestContentfulPaint,
+        initialViewMetrics.navigationTimings
+      ),
+    })
+
+    unsubscribe()
+  })
+
+  return {
+    stop: unsubscribe,
+  }
+}
+
+function createCoreInitialViewMetrics(
+  lcp: LargestContentfulPaint,
+  navigation: NavigationTimings
+): CoreInitialViewMetrics {
+  return {
+    lcp: {
+      value: lcp.value,
+    },
+    navigation: {
+      domComplete: navigation.domComplete,
+      domContentLoaded: navigation.domContentLoaded,
+      domInteractive: navigation.domInteractive,
+      firstByte: navigation.firstByte,
+      loadEvent: navigation.loadEvent,
+    },
+  }
+}