@kubesense/kubesense-browser-rum-core 1.0.0

package/src/browser/performanceObservable.ts

@@ -0,0 +1,324 @@
+import type { Duration, RelativeTime, TimeoutId } from '@kubesense/kubesense-browser-core'
+import { addEventListener, Observable, setTimeout, clearTimeout, monitor } from '@kubesense/kubesense-browser-core'
+import type { RumConfiguration } from '../domain/configuration'
+import { hasValidResourceEntryDuration, isAllowedRequestUrl } from '../domain/resource/resourceUtils'
+import { retrieveFirstInputTiming } from './firstInputPolyfill'
+
+type RumPerformanceObserverConstructor = new (callback: PerformanceObserverCallback) => RumPerformanceObserver
+
+export interface BrowserWindow extends Window {
+  PerformanceObserver: RumPerformanceObserverConstructor
+  performance: Performance & { interactionCount?: number }
+}
+
+export interface RumPerformanceObserver extends PerformanceObserver {
+  observe(options?: PerformanceObserverInit & { durationThreshold?: number }): void
+}
+
+// We want to use a real enum (i.e. not a const enum) here, to be able to check whether an arbitrary
+// string is an expected performance entry
+// eslint-disable-next-line no-restricted-syntax
+export enum RumPerformanceEntryType {
+  EVENT = 'event',
+  FIRST_INPUT = 'first-input',
+  LARGEST_CONTENTFUL_PAINT = 'largest-contentful-paint',
+  LAYOUT_SHIFT = 'layout-shift',
+  LONG_TASK = 'longtask',
+  LONG_ANIMATION_FRAME = 'long-animation-frame',
+  NAVIGATION = 'navigation',
+  PAINT = 'paint',
+  RESOURCE = 'resource',
+  VISIBILITY_STATE = 'visibility-state',
+}
+
+export interface RumPerformanceLongTaskTiming {
+  name: string
+  entryType: RumPerformanceEntryType.LONG_TASK
+  startTime: RelativeTime
+  duration: Duration
+  toJSON(): Omit<PerformanceEntry, 'toJSON'>
+}
+
+export interface RumPerformanceResourceTiming {
+  entryType: RumPerformanceEntryType.RESOURCE
+  initiatorType: string
+  responseStatus?: number
+  name: string
+  startTime: RelativeTime
+  duration: Duration
+  fetchStart: RelativeTime
+  workerStart: RelativeTime
+  domainLookupStart: RelativeTime
+  domainLookupEnd: RelativeTime
+  connectStart: RelativeTime
+  secureConnectionStart: RelativeTime
+  connectEnd: RelativeTime
+  requestStart: RelativeTime
+  responseStart: RelativeTime
+  responseEnd: RelativeTime
+  redirectStart: RelativeTime
+  redirectEnd: RelativeTime
+  decodedBodySize?: number
+  encodedBodySize?: number
+  transferSize?: number
+  nextHopProtocol?: string
+  renderBlockingStatus?: string
+  traceId?: string
+  deliveryType?: 'cache' | 'navigational-prefetch' | ''
+  toJSON(): Omit<PerformanceEntry, 'toJSON'>
+}
+
+export interface RumPerformancePaintTiming {
+  entryType: RumPerformanceEntryType.PAINT
+  name: 'first-paint' | 'first-contentful-paint'
+  startTime: RelativeTime
+  toJSON(): Omit<RumPerformancePaintTiming, 'toJSON'>
+}
+
+export interface RumPerformanceNavigationTiming extends Omit<RumPerformanceResourceTiming, 'entryType'> {
+  entryType: RumPerformanceEntryType.NAVIGATION
+  initiatorType: 'navigation'
+  name: string
+
+  domComplete: RelativeTime
+  domContentLoadedEventEnd: RelativeTime
+  domInteractive: RelativeTime
+  loadEventEnd: RelativeTime
+
+  toJSON(): Omit<RumPerformanceNavigationTiming, 'toJSON'>
+}
+
+export interface RumLargestContentfulPaintTiming {
+  entryType: RumPerformanceEntryType.LARGEST_CONTENTFUL_PAINT
+  startTime: RelativeTime
+  size: number
+  element?: Element
+  url?: string
+  toJSON(): Omit<RumLargestContentfulPaintTiming, 'toJSON'>
+}
+
+export interface RumFirstInputTiming {
+  entryType: RumPerformanceEntryType.FIRST_INPUT
+  startTime: RelativeTime
+  processingStart: RelativeTime
+  processingEnd: RelativeTime
+  duration: Duration
+  target?: Node
+  interactionId?: number
+  toJSON(): Omit<RumFirstInputTiming, 'toJSON'>
+}
+
+export interface RumPerformanceEventTiming {
+  entryType: RumPerformanceEntryType.EVENT
+  startTime: RelativeTime
+  processingStart: RelativeTime
+  processingEnd: RelativeTime
+  duration: Duration
+  interactionId?: number
+  target?: Node
+  name: string
+  toJSON(): Omit<RumPerformanceEventTiming, 'toJSON'>
+}
+
+export interface RumLayoutShiftAttribution {
+  node: Node | null
+  previousRect: DOMRectReadOnly
+  currentRect: DOMRectReadOnly
+}
+
+export interface RumLayoutShiftTiming {
+  entryType: RumPerformanceEntryType.LAYOUT_SHIFT
+  startTime: RelativeTime
+  value: number
+  hadRecentInput: boolean
+  sources: RumLayoutShiftAttribution[]
+  toJSON(): Omit<RumLayoutShiftTiming, 'toJSON'>
+}
+
+// Documentation https://developer.chrome.com/docs/web-platform/long-animation-frames#better-attribution
+export interface RumPerformanceScriptTiming {
+  duration: Duration
+  entryType: 'script'
+  executionStart: RelativeTime
+  forcedStyleAndLayoutDuration: Duration
+  invoker: string // e.g. "https://static.kubesense.ai/static/c/93085/chunk-bc4db53278fd4c77a637.min.js"
+  invokerType:
+    | 'user-callback'
+    | 'event-listener'
+    | 'resolve-promise'
+    | 'reject-promise'
+    | 'classic-script'
+    | 'module-script'
+  name: 'script'
+  pauseDuration: Duration
+  sourceCharPosition: number
+  sourceFunctionName: string
+  sourceURL: string
+  startTime: RelativeTime
+  window: Window
+  windowAttribution: string
+}
+
+export interface RumPerformanceLongAnimationFrameTiming {
+  blockingDuration: Duration
+  duration: Duration
+  entryType: RumPerformanceEntryType.LONG_ANIMATION_FRAME
+  firstUIEventTimestamp: RelativeTime
+  name: 'long-animation-frame'
+  renderStart: RelativeTime
+  scripts: RumPerformanceScriptTiming[]
+  startTime: RelativeTime
+  styleAndLayoutStart: RelativeTime
+  toJSON(): Omit<RumPerformanceLongAnimationFrameTiming, 'toJSON'>
+}
+
+export interface RumFirstHiddenTiming {
+  entryType: RumPerformanceEntryType.VISIBILITY_STATE
+  name: 'hidden' | 'visible'
+  startTime: RelativeTime
+  toJSON(): Omit<RumFirstHiddenTiming, 'toJSON'>
+}
+
+export type RumPerformanceEntry =
+  | RumPerformanceResourceTiming
+  | RumPerformanceLongTaskTiming
+  | RumPerformanceLongAnimationFrameTiming
+  | RumPerformancePaintTiming
+  | RumPerformanceNavigationTiming
+  | RumLargestContentfulPaintTiming
+  | RumFirstInputTiming
+  | RumPerformanceEventTiming
+  | RumLayoutShiftTiming
+  | RumFirstHiddenTiming
+
+export interface EntryTypeToReturnType {
+  [RumPerformanceEntryType.EVENT]: RumPerformanceEventTiming
+  [RumPerformanceEntryType.FIRST_INPUT]: RumFirstInputTiming
+  [RumPerformanceEntryType.LARGEST_CONTENTFUL_PAINT]: RumLargestContentfulPaintTiming
+  [RumPerformanceEntryType.LAYOUT_SHIFT]: RumLayoutShiftTiming
+  [RumPerformanceEntryType.PAINT]: RumPerformancePaintTiming
+  [RumPerformanceEntryType.LONG_TASK]: RumPerformanceLongTaskTiming
+  [RumPerformanceEntryType.LONG_ANIMATION_FRAME]: RumPerformanceLongAnimationFrameTiming
+  [RumPerformanceEntryType.NAVIGATION]: RumPerformanceNavigationTiming
+  [RumPerformanceEntryType.RESOURCE]: RumPerformanceResourceTiming
+  [RumPerformanceEntryType.VISIBILITY_STATE]: RumFirstHiddenTiming
+}
+
+export function createPerformanceObservable<T extends RumPerformanceEntryType>(
+  configuration: RumConfiguration,
+  options: { type: T; buffered?: boolean; durationThreshold?: number }
+) {
+  return new Observable<Array<EntryTypeToReturnType[T]>>((observable) => {
+    if (!window.PerformanceObserver) {
+      return
+    }
+
+    const handlePerformanceEntries = (entries: PerformanceEntryList) => {
+      const rumPerformanceEntries = filterRumPerformanceEntries(entries as Array<EntryTypeToReturnType[T]>)
+      if (rumPerformanceEntries.length > 0) {
+        observable.notify(rumPerformanceEntries)
+      }
+    }
+
+    let timeoutId: TimeoutId | undefined
+    let isObserverInitializing = true
+    const observer = new PerformanceObserver(
+      monitor((entries) => {
+        // In Safari the performance observer callback is synchronous.
+        // Because the buffered performance entry list can be quite large we delay the computation to prevent the SDK from blocking the main thread on init
+        if (isObserverInitializing) {
+          timeoutId = setTimeout(() => handlePerformanceEntries(entries.getEntries()))
+        } else {
+          handlePerformanceEntries(entries.getEntries())
+        }
+      })
+    )
+    try {
+      observer.observe(options)
+    } catch {
+      // Some old browser versions (<= chrome 74 ) don't support the PerformanceObserver type and buffered options
+      // In these cases, fallback to getEntriesByType and PerformanceObserver with entryTypes
+      // TODO: remove this fallback in the next major version
+      const fallbackSupportedEntryTypes = [
+        RumPerformanceEntryType.RESOURCE,
+        RumPerformanceEntryType.NAVIGATION,
+        RumPerformanceEntryType.LONG_TASK,
+        RumPerformanceEntryType.PAINT,
+      ]
+      if (fallbackSupportedEntryTypes.includes(options.type)) {
+        if (options.buffered) {
+          timeoutId = setTimeout(() => handlePerformanceEntries(performance.getEntriesByType(options.type)))
+        }
+        try {
+          observer.observe({ entryTypes: [options.type] })
+        } catch {
+          // Old versions of Safari are throwing "entryTypes contained only unsupported types"
+          // errors when observing only unsupported entry types.
+          //
+          // We could use `supportPerformanceTimingEvent` to make sure we don't invoke
+          // `observer.observe` with an unsupported entry type, but Safari 11 and 12 don't support
+          // `Performance.supportedEntryTypes`, so doing so would lose support for these versions
+          // even if they do support the entry type.
+          return
+        }
+      }
+    }
+    isObserverInitializing = false
+
+    manageResourceTimingBufferFull(configuration)
+
+    let stopFirstInputTiming: (() => void) | undefined
+    if (
+      !supportPerformanceTimingEvent(RumPerformanceEntryType.FIRST_INPUT) &&
+      options.type === RumPerformanceEntryType.FIRST_INPUT
+    ) {
+      ;({ stop: stopFirstInputTiming } = retrieveFirstInputTiming(configuration, (timing) => {
+        handlePerformanceEntries([timing])
+      }))
+    }
+
+    return () => {
+      observer.disconnect()
+      if (stopFirstInputTiming) {
+        stopFirstInputTiming()
+      }
+      clearTimeout(timeoutId)
+    }
+  })
+}
+
+let resourceTimingBufferFullListener: { stop: () => void }
+function manageResourceTimingBufferFull(configuration: RumConfiguration) {
+  if (!resourceTimingBufferFullListener && supportPerformanceObject() && 'addEventListener' in performance) {
+    // https://bugzilla.mozilla.org/show_bug.cgi?id=1559377
+    resourceTimingBufferFullListener = addEventListener(configuration, performance, 'resourcetimingbufferfull', () => {
+      performance.clearResourceTimings()
+    })
+  }
+  return () => {
+    resourceTimingBufferFullListener?.stop()
+  }
+}
+
+function supportPerformanceObject() {
+  return window.performance !== undefined && 'getEntries' in performance
+}
+
+export function supportPerformanceTimingEvent(entryType: RumPerformanceEntryType) {
+  return (
+    window.PerformanceObserver &&
+    PerformanceObserver.supportedEntryTypes !== undefined &&
+    PerformanceObserver.supportedEntryTypes.includes(entryType)
+  )
+}
+
+function filterRumPerformanceEntries<T extends RumPerformanceEntryType>(entries: Array<EntryTypeToReturnType[T]>) {
+  return entries.filter((entry) => !isForbiddenResource(entry))
+}
+
+function isForbiddenResource(entry: RumPerformanceEntry) {
+  return (
+    entry.entryType === RumPerformanceEntryType.RESOURCE &&
+    (!isAllowedRequestUrl(entry.name) || !hasValidResourceEntryDuration(entry))
+  )
+}

package/src/browser/performanceUtils.ts

@@ -0,0 +1,50 @@
+import type { RelativeTime, TimeStamp } from '@kubesense/kubesense-browser-core'
+import { getRelativeTime, isNumber } from '@kubesense/kubesense-browser-core'
+import type { RumPerformanceNavigationTiming } from './performanceObservable'
+import { RumPerformanceEntryType, supportPerformanceTimingEvent } from './performanceObservable'
+
+export function getNavigationEntry(): RumPerformanceNavigationTiming {
+  if (supportPerformanceTimingEvent(RumPerformanceEntryType.NAVIGATION)) {
+    const navigationEntry = performance.getEntriesByType(
+      RumPerformanceEntryType.NAVIGATION
+    )[0] as unknown as RumPerformanceNavigationTiming
+    if (navigationEntry) {
+      return navigationEntry
+    }
+  }
+
+  const timings = computeTimingsFromDeprecatedPerformanceTiming()
+  const entry: RumPerformanceNavigationTiming = {
+    entryType: RumPerformanceEntryType.NAVIGATION as const,
+    initiatorType: 'navigation' as const,
+    name: window.location.href,
+    startTime: 0 as RelativeTime,
+    duration: timings.loadEventEnd,
+    decodedBodySize: 0,
+    encodedBodySize: 0,
+    transferSize: 0,
+    workerStart: 0 as RelativeTime,
+    toJSON: () => ({ ...entry, toJSON: undefined }),
+    ...timings,
+  }
+
+  return entry
+}
+
+export type TimingsFromDeprecatedPerformanceTiming = {
+  -readonly [key in keyof Omit<PerformanceTiming, 'toJSON'>]: RelativeTime
+}
+
+export function computeTimingsFromDeprecatedPerformanceTiming() {
+  const result: Partial<TimingsFromDeprecatedPerformanceTiming> = {}
+  const timing = performance.timing
+
+  for (const key in timing) {
+    if (isNumber(timing[key as keyof PerformanceTiming])) {
+      const numberKey = key as keyof TimingsFromDeprecatedPerformanceTiming
+      const timingElement = timing[numberKey] as TimeStamp
+      result[numberKey] = timingElement === 0 ? (0 as RelativeTime) : getRelativeTime(timingElement)
+    }
+  }
+  return result as TimingsFromDeprecatedPerformanceTiming
+}

package/src/browser/scroll.ts

@@ -0,0 +1,25 @@
+export function getScrollX() {
+  let scrollX
+  const visual = window.visualViewport
+  if (visual) {
+    scrollX = visual.pageLeft - visual.offsetLeft
+  } else if (window.scrollX !== undefined) {
+    scrollX = window.scrollX
+  } else {
+    scrollX = window.pageXOffset || 0
+  }
+  return Math.round(scrollX)
+}
+
+export function getScrollY() {
+  let scrollY
+  const visual = window.visualViewport
+  if (visual) {
+    scrollY = visual.pageTop - visual.offsetTop
+  } else if (window.scrollY !== undefined) {
+    scrollY = window.scrollY
+  } else {
+    scrollY = window.pageYOffset || 0
+  }
+  return Math.round(scrollY)
+}

package/src/browser/viewportObservable.ts

@@ -0,0 +1,44 @@
+import { Observable, throttle, addEventListener, DOM_EVENT } from '@kubesense/kubesense-browser-core'
+import type { RumConfiguration } from '../domain/configuration'
+
+export interface ViewportDimension {
+  height: number
+  width: number
+  [k: string]: unknown
+}
+
+let viewportObservable: Observable<ViewportDimension> | undefined
+
+export function initViewportObservable(configuration: RumConfiguration) {
+  if (!viewportObservable) {
+    viewportObservable = createViewportObservable(configuration)
+  }
+  return viewportObservable
+}
+
+export function createViewportObservable(configuration: RumConfiguration) {
+  return new Observable<ViewportDimension>((observable) => {
+    const { throttled: updateDimension } = throttle(() => {
+      observable.notify(getViewportDimension())
+    }, 200)
+
+    return addEventListener(configuration, window, DOM_EVENT.RESIZE, updateDimension, { capture: true, passive: true })
+      .stop
+  })
+}
+
+// excludes the width and height of any rendered classic scrollbar that is fixed to the visual viewport
+export function getViewportDimension(): ViewportDimension {
+  const visual = window.visualViewport
+  if (visual) {
+    return {
+      width: Number(visual.width * visual.scale),
+      height: Number(visual.height * visual.scale),
+    }
+  }
+
+  return {
+    width: Number(window.innerWidth || 0),
+    height: Number(window.innerHeight || 0),
+  }
+}

package/src/browser/windowOpenObservable.ts

@@ -0,0 +1,7 @@
+import { instrumentMethod, Observable } from '@kubesense/kubesense-browser-core'
+
+export function createWindowOpenObservable() {
+  const observable = new Observable<void>()
+  const { stop } = instrumentMethod(window, 'open', () => observable.notify())
+  return { observable, stop }
+}

package/src/domain/action/actionCollection.ts

@@ -0,0 +1,146 @@
+import type { ClocksState, Context, Observable } from '@kubesense/kubesense-browser-core'
+import { noop, combine, toServerDuration, generateUUID, SKIPPED, HookNames } from '@kubesense/kubesense-browser-core'
+import { discardNegativeDuration } from '../discardNegativeDuration'
+import type { RawRumActionEvent } from '../../rawRumEvent.types'
+import { ActionType, RumEventType } from '../../rawRumEvent.types'
+import type { LifeCycle, RawRumEventCollectedData } from '../lifeCycle'
+import { LifeCycleEventType } from '../lifeCycle'
+import type { RumConfiguration } from '../configuration'
+import type { RumActionEventDomainContext } from '../../domainContext.types'
+import type { DefaultRumEventAttributes, DefaultTelemetryEventAttributes, Hooks } from '../hooks'
+import type { RumMutationRecord } from '../../browser/domMutationObservable'
+import type { ActionContexts, ClickAction } from './trackClickActions'
+import { trackClickActions } from './trackClickActions'
+
+export type { ActionContexts }
+
+export interface CustomAction {
+  type: typeof ActionType.CUSTOM
+  name: string
+  startClocks: ClocksState
+  context?: Context
+  handlingStack?: string
+}
+
+export type AutoAction = ClickAction
+
+export function startActionCollection(
+  lifeCycle: LifeCycle,
+  hooks: Hooks,
+  domMutationObservable: Observable<RumMutationRecord[]>,
+  windowOpenObservable: Observable<void>,
+  configuration: RumConfiguration
+) {
+  const { unsubscribe: unsubscribeAutoAction } = lifeCycle.subscribe(
+    LifeCycleEventType.AUTO_ACTION_COMPLETED,
+    (action) => {
+      lifeCycle.notify(LifeCycleEventType.RAW_RUM_EVENT_COLLECTED, processAction(action))
+    }
+  )
+
+  hooks.register(HookNames.Assemble, ({ startTime, eventType }): DefaultRumEventAttributes | SKIPPED => {
+    if (
+      eventType !== RumEventType.ERROR &&
+      eventType !== RumEventType.RESOURCE &&
+      eventType !== RumEventType.LONG_TASK
+    ) {
+      return SKIPPED
+    }
+
+    const actionId = actionContexts.findActionId(startTime)
+    if (!actionId) {
+      return SKIPPED
+    }
+
+    return {
+      type: eventType,
+      action: { id: actionId },
+    }
+  })
+
+  hooks.register(
+    HookNames.AssembleTelemetry,
+    ({ startTime }): DefaultTelemetryEventAttributes => ({
+      action: { id: actionContexts.findActionId(startTime) as string },
+    })
+  )
+
+  let actionContexts: ActionContexts = { findActionId: noop as () => undefined }
+  let stop: () => void = noop
+
+  if (configuration.trackUserInteractions) {
+    ;({ actionContexts, stop } = trackClickActions(
+      lifeCycle,
+      domMutationObservable,
+      windowOpenObservable,
+      configuration
+    ))
+  }
+
+  return {
+    addAction: (action: CustomAction) => {
+      lifeCycle.notify(LifeCycleEventType.RAW_RUM_EVENT_COLLECTED, processAction(action))
+    },
+    actionContexts,
+    stop: () => {
+      unsubscribeAutoAction()
+      stop()
+    },
+  }
+}
+
+function processAction(action: AutoAction | CustomAction): RawRumEventCollectedData<RawRumActionEvent> {
+  const autoActionProperties = isAutoAction(action)
+    ? {
+        action: {
+          id: action.id,
+          loading_time: discardNegativeDuration(toServerDuration(action.duration)),
+          frustration: {
+            type: action.frustrationTypes,
+          },
+          error: {
+            count: action.counts.errorCount,
+          },
+          long_task: {
+            count: action.counts.longTaskCount,
+          },
+          resource: {
+            count: action.counts.resourceCount,
+          },
+        },
+        _kubesense: {
+          action: {
+            target: action.target,
+            position: action.position,
+            name_source: action.nameSource,
+          },
+        },
+      }
+      : {
+        context: action.context,
+      }
+  const actionEvent: RawRumActionEvent = combine(
+    {
+      action: { id: generateUUID(), target: { name: action.name }, type: action.type },
+      date: action.startClocks.timeStamp,
+      type: RumEventType.ACTION,
+    },
+    autoActionProperties
+  )
+
+  const duration = isAutoAction(action) ? action.duration : undefined
+  const domainContext: RumActionEventDomainContext = isAutoAction(action)
+    ? { events: action.events }
+    : { handlingStack: action.handlingStack }
+
+  return {
+    rawRumEvent: actionEvent,
+    duration,
+    startTime: action.startClocks.relative,
+    domainContext,
+  }
+}
+
+function isAutoAction(action: AutoAction | CustomAction): action is AutoAction {
+  return action.type !== ActionType.CUSTOM
+}

package/src/domain/action/actionNameConstants.ts

@@ -0,0 +1,20 @@
+/**
+ * Get the action name from the attribute 'data-kubesense-action-name' on the element or any of its parent.
+ * It can also be retrieved from a user defined attribute.
+ */
+export const DEFAULT_PROGRAMMATIC_ACTION_NAME_ATTRIBUTE = 'data-kubesense-action-name'
+export const ACTION_NAME_PLACEHOLDER = 'Masked Element'
+export const ACTION_NAME_MASK = 'xxx'
+
+export const enum ActionNameSource {
+  CUSTOM_ATTRIBUTE = 'custom_attribute',
+  MASK_PLACEHOLDER = 'mask_placeholder',
+  TEXT_CONTENT = 'text_content',
+  STANDARD_ATTRIBUTE = 'standard_attribute',
+  BLANK = 'blank',
+}
+
+export interface ActionName {
+  name: string
+  nameSource: ActionNameSource
+}