@kubesense/kubesense-browser-rum-core 1.0.0

package/src/domain/view/viewMetrics/trackInteractionToNextPaint.ts

@@ -0,0 +1,193 @@
+import { elapsed, noop, ONE_MINUTE } from '@kubesense/kubesense-browser-core'
+import type { Duration, RelativeTime } from '@kubesense/kubesense-browser-core'
+import {
+  createPerformanceObservable,
+  RumPerformanceEntryType,
+  supportPerformanceTimingEvent,
+} from '../../../browser/performanceObservable'
+import type { RumFirstInputTiming, RumPerformanceEventTiming } from '../../../browser/performanceObservable'
+import { ViewLoadingType } from '../../../rawRumEvent.types'
+import { getSelectorFromElement } from '../../getSelectorFromElement'
+import { isElementNode } from '../../../browser/htmlDomUtils'
+import { getInteractionSelector } from '../../action/interactionSelectorCache'
+import type { RumConfiguration } from '../../configuration'
+import { getInteractionCount, initInteractionCountPolyfill } from './interactionCountPolyfill'
+
+// Arbitrary value to prevent unnecessary memory usage on views with lots of interactions.
+const MAX_INTERACTION_ENTRIES = 10
+// Arbitrary value to cap INP outliers
+export const MAX_INP_VALUE = (1 * ONE_MINUTE) as Duration
+
+export interface InteractionToNextPaint {
+  value: Duration
+  targetSelector?: string
+  time?: Duration
+}
+/**
+ * Track the interaction to next paint (INP).
+ * To avoid outliers, return the p98 worst interaction of the view.
+ * Documentation: https://web.dev/inp/
+ * Reference implementation: https://github.com/GoogleChrome/web-vitals/blob/main/src/onINP.ts
+ */
+export function trackInteractionToNextPaint(
+  configuration: RumConfiguration,
+  viewStart: RelativeTime,
+  viewLoadingType: ViewLoadingType
+) {
+  if (!isInteractionToNextPaintSupported()) {
+    return {
+      getInteractionToNextPaint: () => undefined,
+      setViewEnd: noop,
+      stop: noop,
+    }
+  }
+
+  const { getViewInteractionCount, stopViewInteractionCount } = trackViewInteractionCount(viewLoadingType)
+
+  let viewEnd = Infinity as RelativeTime
+
+  const longestInteractions = trackLongestInteractions(getViewInteractionCount)
+  let interactionToNextPaint = -1 as Duration
+  let interactionToNextPaintTargetSelector: string | undefined
+  let interactionToNextPaintStartTime: Duration | undefined
+
+  function handleEntries(entries: Array<RumPerformanceEventTiming | RumFirstInputTiming>) {
+    for (const entry of entries) {
+      if (
+        entry.interactionId &&
+        // Check the entry start time is inside the view bounds because some view interactions can be reported after the view end (if long duration).
+        entry.startTime >= viewStart &&
+        entry.startTime <= viewEnd
+      ) {
+        longestInteractions.process(entry)
+      }
+    }
+
+    const newInteraction = longestInteractions.estimateP98Interaction()
+    if (newInteraction && newInteraction.duration !== interactionToNextPaint) {
+      interactionToNextPaint = newInteraction.duration
+      interactionToNextPaintStartTime = elapsed(viewStart, newInteraction.startTime)
+      interactionToNextPaintTargetSelector = getInteractionSelector(newInteraction.startTime)
+      if (!interactionToNextPaintTargetSelector && newInteraction.target && isElementNode(newInteraction.target)) {
+        interactionToNextPaintTargetSelector = getSelectorFromElement(
+          newInteraction.target,
+          configuration.actionNameAttribute
+        )
+      }
+    }
+  }
+
+  const firstInputSubscription = createPerformanceObservable(configuration, {
+    type: RumPerformanceEntryType.FIRST_INPUT,
+    buffered: true,
+  }).subscribe(handleEntries)
+
+  const eventSubscription = createPerformanceObservable(configuration, {
+    type: RumPerformanceEntryType.EVENT,
+    // durationThreshold only impact PerformanceEventTiming entries used for INP computation which requires a threshold at 40 (default is 104ms)
+    // cf: https://github.com/GoogleChrome/web-vitals/blob/3806160ffbc93c3c4abf210a167b81228172b31c/src/onINP.ts#L202-L210
+    durationThreshold: 40,
+    buffered: true,
+  }).subscribe(handleEntries)
+
+  return {
+    getInteractionToNextPaint: (): InteractionToNextPaint | undefined => {
+      // If no INP duration where captured because of the performanceObserver 40ms threshold
+      // but the view interaction count > 0 then report 0
+      if (interactionToNextPaint >= 0) {
+        return {
+          value: Math.min(interactionToNextPaint, MAX_INP_VALUE) as Duration,
+          targetSelector: interactionToNextPaintTargetSelector,
+          time: interactionToNextPaintStartTime,
+        }
+      } else if (getViewInteractionCount()) {
+        return {
+          value: 0 as Duration,
+        }
+      }
+    },
+    setViewEnd: (viewEndTime: RelativeTime) => {
+      viewEnd = viewEndTime
+      stopViewInteractionCount()
+    },
+    stop: () => {
+      eventSubscription.unsubscribe()
+      firstInputSubscription.unsubscribe()
+    },
+  }
+}
+
+function trackLongestInteractions(getViewInteractionCount: () => number) {
+  const longestInteractions: Array<RumPerformanceEventTiming | RumFirstInputTiming> = []
+
+  function sortAndTrimLongestInteractions() {
+    longestInteractions.sort((a, b) => b.duration - a.duration).splice(MAX_INTERACTION_ENTRIES)
+  }
+
+  return {
+    /**
+     * Process the performance entry:
+     * - if its duration is long enough, add the performance entry to the list of worst interactions
+     * - if an entry with the same interaction id exists and its duration is lower than the new one, then replace it in the list of worst interactions
+     */
+    process(entry: RumPerformanceEventTiming | RumFirstInputTiming) {
+      const interactionIndex = longestInteractions.findIndex(
+        (interaction) => entry.interactionId === interaction.interactionId
+      )
+
+      const minLongestInteraction = longestInteractions[longestInteractions.length - 1]
+
+      if (interactionIndex !== -1) {
+        if (entry.duration > longestInteractions[interactionIndex].duration) {
+          longestInteractions[interactionIndex] = entry
+          sortAndTrimLongestInteractions()
+        }
+      } else if (
+        longestInteractions.length < MAX_INTERACTION_ENTRIES ||
+        entry.duration > minLongestInteraction.duration
+      ) {
+        longestInteractions.push(entry)
+        sortAndTrimLongestInteractions()
+      }
+    },
+    /**
+     * Compute the p98 longest interaction.
+     * For better performance the computation is based on 10 longest interactions and the interaction count of the current view.
+     */
+    estimateP98Interaction(): RumPerformanceEventTiming | RumFirstInputTiming | undefined {
+      const interactionIndex = Math.min(longestInteractions.length - 1, Math.floor(getViewInteractionCount() / 50))
+      return longestInteractions[interactionIndex]
+    },
+  }
+}
+
+export function trackViewInteractionCount(viewLoadingType: ViewLoadingType) {
+  initInteractionCountPolyfill()
+  const previousInteractionCount = viewLoadingType === ViewLoadingType.INITIAL_LOAD ? 0 : getInteractionCount()
+  let state: { stopped: false } | { stopped: true; interactionCount: number } = { stopped: false }
+
+  function computeViewInteractionCount() {
+    return getInteractionCount() - previousInteractionCount
+  }
+
+  return {
+    getViewInteractionCount: () => {
+      if (state.stopped) {
+        return state.interactionCount
+      }
+
+      return computeViewInteractionCount()
+    },
+    stopViewInteractionCount: () => {
+      state = { stopped: true, interactionCount: computeViewInteractionCount() }
+    },
+  }
+}
+
+export function isInteractionToNextPaintSupported() {
+  return (
+    supportPerformanceTimingEvent(RumPerformanceEntryType.EVENT) &&
+    window.PerformanceEventTiming &&
+    'interactionId' in PerformanceEventTiming.prototype
+  )
+}

package/src/domain/view/viewMetrics/trackLargestContentfulPaint.ts

@@ -0,0 +1,87 @@
+import type { RelativeTime } from '@kubesense/kubesense-browser-core'
+import { DOM_EVENT, ONE_MINUTE, addEventListeners, findLast } from '@kubesense/kubesense-browser-core'
+import type { RumConfiguration } from '../../configuration'
+import { createPerformanceObservable, RumPerformanceEntryType } from '../../../browser/performanceObservable'
+import type { RumLargestContentfulPaintTiming } from '../../../browser/performanceObservable'
+import { getSelectorFromElement } from '../../getSelectorFromElement'
+import type { FirstHidden } from './trackFirstHidden'
+
+// Discard LCP timings above a certain delay to avoid incorrect data
+// It happens in some cases like sleep mode or some browser implementations
+export const LCP_MAXIMUM_DELAY = 10 * ONE_MINUTE
+
+export interface LargestContentfulPaint {
+  value: RelativeTime
+  targetSelector?: string
+  resourceUrl?: string
+}
+
+/**
+ * Track the largest contentful paint (LCP) occurring during the initial View.  This can yield
+ * multiple values, only the most recent one should be used.
+ * Documentation: https://web.dev/lcp/
+ * Reference implementation: https://github.com/GoogleChrome/web-vitals/blob/master/src/onLCP.ts
+ */
+export function trackLargestContentfulPaint(
+  configuration: RumConfiguration,
+  firstHidden: FirstHidden,
+  eventTarget: Window,
+  callback: (largestContentfulPaint: LargestContentfulPaint) => void
+) {
+  // Ignore entries that come after the first user interaction. According to the documentation, the
+  // browser should not send largest-contentful-paint entries after a user interact with the page,
+  // but the web-vitals reference implementation uses this as a safeguard.
+  let firstInteractionTimestamp = Infinity
+  const { stop: stopEventListener } = addEventListeners(
+    configuration,
+    eventTarget,
+    [DOM_EVENT.POINTER_DOWN, DOM_EVENT.KEY_DOWN],
+    (event) => {
+      firstInteractionTimestamp = event.timeStamp
+    },
+    { capture: true, once: true }
+  )
+
+  let biggestLcpSize = 0
+  const performanceLcpSubscription = createPerformanceObservable(configuration, {
+    type: RumPerformanceEntryType.LARGEST_CONTENTFUL_PAINT,
+    buffered: true,
+  }).subscribe((entries) => {
+    const lcpEntry = findLast(
+      entries,
+      (entry): entry is RumLargestContentfulPaintTiming =>
+        entry.entryType === RumPerformanceEntryType.LARGEST_CONTENTFUL_PAINT &&
+        entry.startTime < firstInteractionTimestamp &&
+        entry.startTime < firstHidden.timeStamp &&
+        entry.startTime < LCP_MAXIMUM_DELAY &&
+        // Ensure to get the LCP entry with the biggest size, see
+        // https://bugs.chromium.org/p/chromium/issues/detail?id=1516655
+        entry.size > biggestLcpSize
+    )
+    if (lcpEntry) {
+      let lcpTargetSelector
+      if (lcpEntry.element) {
+        lcpTargetSelector = getSelectorFromElement(lcpEntry.element, configuration.actionNameAttribute)
+      }
+
+      callback({
+        value: lcpEntry.startTime,
+        targetSelector: lcpTargetSelector,
+        resourceUrl: computeLcpEntryUrl(lcpEntry),
+      })
+      biggestLcpSize = lcpEntry.size
+    }
+  })
+
+  return {
+    stop: () => {
+      stopEventListener()
+      performanceLcpSubscription.unsubscribe()
+    },
+  }
+}
+
+// The property url report an empty string if the value is not available, we shouldn't report it in this case.
+function computeLcpEntryUrl(entry: RumLargestContentfulPaintTiming) {
+  return entry.url === '' ? undefined : entry.url
+}

package/src/domain/view/viewMetrics/trackLoadingTime.ts

@@ -0,0 +1,69 @@
+import type { ClocksState, Duration, Observable } from '@kubesense/kubesense-browser-core'
+import { elapsed } from '@kubesense/kubesense-browser-core'
+import { waitPageActivityEnd } from '../../waitPageActivityEnd'
+import type { RumConfiguration } from '../../configuration'
+import type { LifeCycle } from '../../lifeCycle'
+import { ViewLoadingType } from '../../../rawRumEvent.types'
+import type { RumMutationRecord } from '../../../browser/domMutationObservable'
+import { trackFirstHidden } from './trackFirstHidden'
+
+/**
+ * For non-initial views (such as route changes or BFCache restores), the regular load event does not fire
+ * In these cases, trackLoadingTime can only emit a loadingTime  if waitPageActivityEnd detects some post-restore activity.
+ * If nothing happens after the view starts,no candidate is recorded and loadingTime stays undefined.
+ */
+
+export function trackLoadingTime(
+  lifeCycle: LifeCycle,
+  domMutationObservable: Observable<RumMutationRecord[]>,
+  windowOpenObservable: Observable<void>,
+  configuration: RumConfiguration,
+  loadType: ViewLoadingType,
+  viewStart: ClocksState,
+  callback: (loadingTime: Duration) => void
+) {
+  let isWaitingForLoadEvent = loadType === ViewLoadingType.INITIAL_LOAD
+  let isWaitingForActivityLoadingTime = true
+  const loadingTimeCandidates: Duration[] = []
+  const firstHidden = trackFirstHidden(configuration, viewStart)
+
+  function invokeCallbackIfAllCandidatesAreReceived() {
+    if (!isWaitingForActivityLoadingTime && !isWaitingForLoadEvent && loadingTimeCandidates.length > 0) {
+      const loadingTime = Math.max(...loadingTimeCandidates)
+      // firstHidden is a relative time from time origin, so we use the relative start time of the view to compare with the loading time
+      if (loadingTime < firstHidden.timeStamp - viewStart.relative) {
+        callback(loadingTime as Duration)
+      }
+    }
+  }
+
+  const { stop } = waitPageActivityEnd(
+    lifeCycle,
+    domMutationObservable,
+    windowOpenObservable,
+    configuration,
+    (event) => {
+      if (isWaitingForActivityLoadingTime) {
+        isWaitingForActivityLoadingTime = false
+        if (event.hadActivity) {
+          loadingTimeCandidates.push(elapsed(viewStart.timeStamp, event.end))
+        }
+        invokeCallbackIfAllCandidatesAreReceived()
+      }
+    }
+  )
+
+  return {
+    stop: () => {
+      stop()
+      firstHidden.stop()
+    },
+    setLoadEvent: (loadEvent: Duration) => {
+      if (isWaitingForLoadEvent) {
+        isWaitingForLoadEvent = false
+        loadingTimeCandidates.push(loadEvent)
+        invokeCallbackIfAllCandidatesAreReceived()
+      }
+    },
+  }
+}

package/src/domain/view/viewMetrics/trackNavigationTimings.ts

@@ -0,0 +1,66 @@
+import type { Duration, TimeoutId } from '@kubesense/kubesense-browser-core'
+import { setTimeout, relativeNow, runOnReadyState, clearTimeout } from '@kubesense/kubesense-browser-core'
+import type { RumPerformanceNavigationTiming } from '../../../browser/performanceObservable'
+import type { RumConfiguration } from '../../configuration'
+import { getNavigationEntry } from '../../../browser/performanceUtils'
+
+export interface NavigationTimings {
+  domComplete: Duration
+  domContentLoaded: Duration
+  domInteractive: Duration
+  loadEvent: Duration
+  firstByte: Duration | undefined
+}
+
+// This is a subset of "RumPerformanceNavigationTiming" that only contains the relevant fields for
+// computing navigation timings. This is useful to mock the navigation entry in tests.
+export type RelevantNavigationTiming = Pick<
+  RumPerformanceNavigationTiming,
+  'domComplete' | 'domContentLoadedEventEnd' | 'domInteractive' | 'loadEventEnd' | 'responseStart'
+>
+
+export function trackNavigationTimings(
+  configuration: RumConfiguration,
+  callback: (timings: NavigationTimings) => void,
+  getNavigationEntryImpl: () => RelevantNavigationTiming = getNavigationEntry
+) {
+  return waitAfterLoadEvent(configuration, () => {
+    const entry = getNavigationEntryImpl()
+
+    if (!isIncompleteNavigation(entry)) {
+      callback(processNavigationEntry(entry))
+    }
+  })
+}
+
+function processNavigationEntry(entry: RelevantNavigationTiming): NavigationTimings {
+  return {
+    domComplete: entry.domComplete,
+    domContentLoaded: entry.domContentLoadedEventEnd,
+    domInteractive: entry.domInteractive,
+    loadEvent: entry.loadEventEnd,
+    // In some cases the value reported is negative, zero (meaning unavailable, e.g. cross-origin
+    // without Timing-Allow-Origin), or larger than the current page time. Ignore these cases:
+    // https://github.com/GoogleChrome/web-vitals/issues/137
+    // https://github.com/GoogleChrome/web-vitals/issues/162
+    firstByte: entry.responseStart > 0 && entry.responseStart <= relativeNow() ? entry.responseStart : undefined,
+  }
+}
+
+function isIncompleteNavigation(entry: RelevantNavigationTiming) {
+  return entry.loadEventEnd <= 0
+}
+
+function waitAfterLoadEvent(configuration: RumConfiguration, callback: () => void) {
+  let timeoutId: TimeoutId | undefined
+  const { stop: stopOnReadyState } = runOnReadyState(configuration, 'complete', () => {
+    // Invoke the callback a bit after the actual load event, so the "loadEventEnd" timing is accurate
+    timeoutId = setTimeout(() => callback())
+  })
+  return {
+    stop: () => {
+      stopOnReadyState()
+      clearTimeout(timeoutId)
+    },
+  }
+}

package/src/domain/view/viewMetrics/trackScrollMetrics.ts

@@ -0,0 +1,119 @@
+import type { ClocksState, Duration } from '@kubesense/kubesense-browser-core'
+import {
+  Observable,
+  ONE_SECOND,
+  elapsed,
+  relativeNow,
+  throttle,
+  addEventListener,
+  DOM_EVENT,
+  monitor,
+} from '@kubesense/kubesense-browser-core'
+import type { RumConfiguration } from '../../configuration'
+import { getScrollY } from '../../../browser/scroll'
+import { getViewportDimension } from '../../../browser/viewportObservable'
+
+/** Arbitrary scroll throttle duration */
+export const THROTTLE_SCROLL_DURATION = ONE_SECOND
+
+export interface ScrollMetrics {
+  maxDepth: number
+  maxScrollHeight: number
+  maxDepthScrollTop: number
+  maxScrollHeightTime: Duration
+}
+
+export function trackScrollMetrics(
+  configuration: RumConfiguration,
+  viewStart: ClocksState,
+  callback: (scrollMetrics: ScrollMetrics) => void,
+  scrollValues = createScrollValuesObservable(configuration)
+) {
+  let maxScrollDepth = 0
+  let maxScrollHeight = 0
+  let maxScrollHeightTime = 0 as Duration
+
+  const subscription = scrollValues.subscribe(({ scrollDepth, scrollTop, scrollHeight }) => {
+    let shouldUpdate = false
+
+    if (scrollDepth > maxScrollDepth) {
+      maxScrollDepth = scrollDepth
+      shouldUpdate = true
+    }
+
+    if (scrollHeight > maxScrollHeight) {
+      maxScrollHeight = scrollHeight
+      const now = relativeNow()
+      maxScrollHeightTime = elapsed(viewStart.relative, now)
+      shouldUpdate = true
+    }
+
+    if (shouldUpdate) {
+      callback({
+        maxDepth: Math.min(maxScrollDepth, maxScrollHeight),
+        maxDepthScrollTop: scrollTop,
+        maxScrollHeight,
+        maxScrollHeightTime,
+      })
+    }
+  })
+
+  return {
+    stop: () => subscription.unsubscribe(),
+  }
+}
+
+export interface ScrollValues {
+  scrollDepth: number
+  scrollTop: number
+  scrollHeight: number
+}
+
+export function computeScrollValues() {
+  const scrollTop = getScrollY()
+
+  const { height } = getViewportDimension()
+
+  const scrollHeight = Math.round((document.scrollingElement || document.documentElement).scrollHeight)
+
+  const scrollDepth = Math.round(height + scrollTop)
+
+  return {
+    scrollHeight,
+    scrollDepth,
+    scrollTop,
+  }
+}
+
+export function createScrollValuesObservable(
+  configuration: RumConfiguration,
+  throttleDuration = THROTTLE_SCROLL_DURATION
+): Observable<ScrollValues> {
+  return new Observable<ScrollValues>((observable) => {
+    function notify() {
+      observable.notify(computeScrollValues())
+    }
+
+    if (window.ResizeObserver) {
+      const throttledNotify = throttle(notify, throttleDuration, {
+        leading: false,
+        trailing: true,
+      })
+
+      const observerTarget = document.scrollingElement || document.documentElement
+      const resizeObserver = new ResizeObserver(monitor(throttledNotify.throttled))
+      if (observerTarget) {
+        resizeObserver.observe(observerTarget)
+      }
+      const eventListener = addEventListener(configuration, window, DOM_EVENT.SCROLL, throttledNotify.throttled, {
+        passive: true,
+      })
+
+      return () => {
+        throttledNotify.cancel()
+        resizeObserver.disconnect()
+        eventListener.stop()
+      }
+    }
+  })
+}