@kubesense/kubesense-browser-rum-core 1.0.0

package/src/domain/action/trackClickActions.ts

@@ -0,0 +1,388 @@
+import type { Duration, ClocksState, RelativeTime, TimeStamp, ValueHistory } from '@kubesense/kubesense-browser-core'
+import {
+  timeStampNow,
+  Observable,
+  getRelativeTime,
+  ONE_MINUTE,
+  generateUUID,
+  clocksNow,
+  elapsed,
+  createValueHistory,
+  PageExitReason,
+  relativeToClocks,
+} from '@kubesense/kubesense-browser-core'
+import type { FrustrationType } from '../../rawRumEvent.types'
+import { ActionType } from '../../rawRumEvent.types'
+import type { LifeCycle } from '../lifeCycle'
+import { LifeCycleEventType } from '../lifeCycle'
+import { trackEventCounts } from '../trackEventCounts'
+import { PAGE_ACTIVITY_VALIDATION_DELAY, waitPageActivityEnd } from '../waitPageActivityEnd'
+import { getSelectorFromElement } from '../getSelectorFromElement'
+import { getNodePrivacyLevel } from '../privacy'
+import { NodePrivacyLevel } from '../privacyConstants'
+import type { RumConfiguration } from '../configuration'
+import type { RumMutationRecord } from '../../browser/domMutationObservable'
+import type { ClickChain } from './clickChain'
+import { createClickChain } from './clickChain'
+import { getActionNameFromElement } from './getActionNameFromElement'
+import type { ActionNameSource } from './actionNameConstants'
+import type { MouseEventOnElement, UserActivity } from './listenActionEvents'
+import { listenActionEvents } from './listenActionEvents'
+import { computeFrustration } from './computeFrustration'
+import { CLICK_ACTION_MAX_DURATION, updateInteractionSelector } from './interactionSelectorCache'
+
+interface ActionCounts {
+  errorCount: number
+  longTaskCount: number
+  resourceCount: number
+}
+
+export interface ClickAction {
+  type: typeof ActionType.CLICK
+  id: string
+  name: string
+  nameSource: ActionNameSource
+  target?: {
+    selector: string | undefined
+    width: number
+    height: number
+  }
+  position?: { x: number; y: number }
+  startClocks: ClocksState
+  duration?: Duration
+  counts: ActionCounts
+  event: MouseEventOnElement
+  frustrationTypes: FrustrationType[]
+  events: Event[]
+}
+
+export interface ActionContexts {
+  findActionId: (startTime?: RelativeTime) => string | string[] | undefined
+}
+
+type ClickActionIdHistory = ValueHistory<ClickAction['id']>
+
+export const ACTION_CONTEXT_TIME_OUT_DELAY = 5 * ONE_MINUTE // arbitrary
+
+export function trackClickActions(
+  lifeCycle: LifeCycle,
+  domMutationObservable: Observable<RumMutationRecord[]>,
+  windowOpenObservable: Observable<void>,
+  configuration: RumConfiguration
+) {
+  const history: ClickActionIdHistory = createValueHistory({ expireDelay: ACTION_CONTEXT_TIME_OUT_DELAY })
+  const stopObservable = new Observable<void>()
+  let currentClickChain: ClickChain | undefined
+
+  lifeCycle.subscribe(LifeCycleEventType.SESSION_RENEWED, () => {
+    history.reset()
+  })
+
+  lifeCycle.subscribe(LifeCycleEventType.VIEW_ENDED, stopClickChain)
+  lifeCycle.subscribe(LifeCycleEventType.PAGE_MAY_EXIT, (event) => {
+    if (event.reason === PageExitReason.UNLOADING) {
+      stopClickChain()
+    }
+  })
+
+  const { stop: stopActionEventsListener } = listenActionEvents<{
+    clickActionBase: ClickActionBase
+    hadActivityOnPointerDown: () => boolean
+  }>(configuration, {
+    onPointerDown: (pointerDownEvent) =>
+      processPointerDown(configuration, lifeCycle, domMutationObservable, pointerDownEvent, windowOpenObservable),
+    onPointerUp: ({ clickActionBase, hadActivityOnPointerDown }, startEvent, getUserActivity) => {
+      startClickAction(
+        configuration,
+        lifeCycle,
+        domMutationObservable,
+        windowOpenObservable,
+        history,
+        stopObservable,
+        appendClickToClickChain,
+        clickActionBase,
+        startEvent,
+        getUserActivity,
+        hadActivityOnPointerDown
+      )
+    },
+  })
+
+  const actionContexts: ActionContexts = {
+    findActionId: (startTime?: RelativeTime) => history.findAll(startTime),
+  }
+
+  return {
+    stop: () => {
+      stopClickChain()
+      stopObservable.notify()
+      stopActionEventsListener()
+    },
+    actionContexts,
+  }
+
+  function appendClickToClickChain(click: Click) {
+    if (!currentClickChain || !currentClickChain.tryAppend(click)) {
+      const rageClick = click.clone()
+      currentClickChain = createClickChain(click, (clicks) => {
+        finalizeClicks(clicks, rageClick)
+        // Clear the reference to allow garbage collection. Without this, the finalize callback
+        // retains a closure reference to the old click chain, preventing it from being cleaned up
+        // and causing a memory leak as click chains accumulate over time.
+        currentClickChain = undefined
+      })
+    }
+  }
+
+  function stopClickChain() {
+    if (currentClickChain) {
+      currentClickChain.stop()
+    }
+  }
+}
+
+function processPointerDown(
+  configuration: RumConfiguration,
+  lifeCycle: LifeCycle,
+  domMutationObservable: Observable<RumMutationRecord[]>,
+  pointerDownEvent: MouseEventOnElement,
+  windowOpenObservable: Observable<void>
+) {
+  let nodePrivacyLevel: NodePrivacyLevel
+
+  if (configuration.enablePrivacyForActionName) {
+    nodePrivacyLevel = getNodePrivacyLevel(pointerDownEvent.target, configuration.defaultPrivacyLevel)
+  } else {
+    nodePrivacyLevel = NodePrivacyLevel.ALLOW
+  }
+
+  if (nodePrivacyLevel === NodePrivacyLevel.HIDDEN) {
+    return undefined
+  }
+
+  const clickActionBase = computeClickActionBase(pointerDownEvent, nodePrivacyLevel, configuration)
+
+  let hadActivityOnPointerDown = false
+
+  waitPageActivityEnd(
+    lifeCycle,
+    domMutationObservable,
+    windowOpenObservable,
+    configuration,
+    (pageActivityEndEvent) => {
+      hadActivityOnPointerDown = pageActivityEndEvent.hadActivity
+    },
+    // We don't care about the activity duration, we just want to know whether an activity did happen
+    // within the "validation delay" or not. Limit the duration so the callback is called sooner.
+    PAGE_ACTIVITY_VALIDATION_DELAY
+  )
+
+  return { clickActionBase, hadActivityOnPointerDown: () => hadActivityOnPointerDown }
+}
+
+function startClickAction(
+  configuration: RumConfiguration,
+  lifeCycle: LifeCycle,
+  domMutationObservable: Observable<RumMutationRecord[]>,
+  windowOpenObservable: Observable<void>,
+  history: ClickActionIdHistory,
+  stopObservable: Observable<void>,
+  appendClickToClickChain: (click: Click) => void,
+  clickActionBase: ClickActionBase,
+  startEvent: MouseEventOnElement,
+  getUserActivity: () => UserActivity,
+  hadActivityOnPointerDown: () => boolean
+) {
+  const click = newClick(lifeCycle, history, getUserActivity, clickActionBase, startEvent)
+  appendClickToClickChain(click)
+
+  const selector = clickActionBase?.target?.selector
+  if (selector) {
+    updateInteractionSelector(startEvent.timeStamp, selector)
+  }
+
+  const { stop: stopWaitPageActivityEnd } = waitPageActivityEnd(
+    lifeCycle,
+    domMutationObservable,
+    windowOpenObservable,
+    configuration,
+    (pageActivityEndEvent) => {
+      if (pageActivityEndEvent.hadActivity && pageActivityEndEvent.end < click.startClocks.timeStamp) {
+        // If the clock is looking weird, just discard the click
+        click.discard()
+      } else {
+        if (pageActivityEndEvent.hadActivity) {
+          click.stop(pageActivityEndEvent.end)
+        } else if (hadActivityOnPointerDown()) {
+          click.stop(
+            // using the click start as activity end, so the click will have some activity but its
+            // duration will be 0 (as the activity started before the click start)
+            click.startClocks.timeStamp
+          )
+        } else {
+          click.stop()
+        }
+      }
+    },
+    CLICK_ACTION_MAX_DURATION
+  )
+
+  const viewEndedSubscription = lifeCycle.subscribe(LifeCycleEventType.VIEW_ENDED, ({ endClocks }) => {
+    click.stop(endClocks.timeStamp)
+  })
+
+  const stopSubscription = stopObservable.subscribe(() => {
+    click.stop()
+  })
+
+  click.stopObservable.subscribe(() => {
+    viewEndedSubscription.unsubscribe()
+    stopWaitPageActivityEnd()
+    stopSubscription.unsubscribe()
+  })
+}
+
+type ClickActionBase = Pick<ClickAction, 'type' | 'name' | 'nameSource' | 'target' | 'position'>
+
+function computeClickActionBase(
+  event: MouseEventOnElement,
+  nodePrivacyLevel: NodePrivacyLevel,
+  configuration: RumConfiguration
+): ClickActionBase {
+  const rect = event.target.getBoundingClientRect()
+  const selector = getSelectorFromElement(event.target, configuration.actionNameAttribute)
+  if (selector) {
+    updateInteractionSelector(event.timeStamp, selector)
+  }
+
+  const { name, nameSource } = getActionNameFromElement(event.target, configuration, nodePrivacyLevel)
+
+  return {
+    type: ActionType.CLICK,
+    target: {
+      width: Math.round(rect.width),
+      height: Math.round(rect.height),
+      selector,
+    },
+    position: {
+      // Use clientX and Y because for SVG element offsetX and Y are relatives to the <svg> element
+      x: Math.round(event.clientX - rect.left),
+      y: Math.round(event.clientY - rect.top),
+    },
+    name,
+    nameSource,
+  }
+}
+
+const enum ClickStatus {
+  // Initial state, the click is still ongoing.
+  ONGOING,
+  // The click is no more ongoing but still needs to be validated or discarded.
+  STOPPED,
+  // Final state, the click has been stopped and validated or discarded.
+  FINALIZED,
+}
+
+export type Click = ReturnType<typeof newClick>
+
+function newClick(
+  lifeCycle: LifeCycle,
+  history: ClickActionIdHistory,
+  getUserActivity: () => UserActivity,
+  clickActionBase: ClickActionBase,
+  startEvent: MouseEventOnElement
+) {
+  const id = generateUUID()
+  const startClocks = relativeToClocks(startEvent.timeStamp)
+  const historyEntry = history.add(id, startClocks.relative)
+  const eventCountsSubscription = trackEventCounts({
+    lifeCycle,
+    isChildEvent: (event) =>
+      event.action !== undefined &&
+      (Array.isArray(event.action.id) ? event.action.id.includes(id) : event.action.id === id),
+  })
+  let status = ClickStatus.ONGOING
+  let activityEndTime: undefined | TimeStamp
+  const frustrationTypes: FrustrationType[] = []
+  const stopObservable = new Observable<void>()
+
+  function stop(newActivityEndTime?: TimeStamp) {
+    if (status !== ClickStatus.ONGOING) {
+      return
+    }
+    activityEndTime = newActivityEndTime
+    status = ClickStatus.STOPPED
+    if (activityEndTime) {
+      historyEntry.close(getRelativeTime(activityEndTime))
+    } else {
+      historyEntry.remove()
+    }
+    eventCountsSubscription.stop()
+    stopObservable.notify()
+  }
+
+  return {
+    event: startEvent,
+    stop,
+    stopObservable,
+
+    get hasError() {
+      return eventCountsSubscription.eventCounts.errorCount > 0
+    },
+    get hasPageActivity() {
+      return activityEndTime !== undefined
+    },
+    getUserActivity,
+    addFrustration: (frustrationType: FrustrationType) => {
+      frustrationTypes.push(frustrationType)
+    },
+    startClocks,
+
+    isStopped: () => status === ClickStatus.STOPPED || status === ClickStatus.FINALIZED,
+
+    clone: () => newClick(lifeCycle, history, getUserActivity, clickActionBase, startEvent),
+
+    validate: (domEvents?: Event[]) => {
+      stop()
+      if (status !== ClickStatus.STOPPED) {
+        return
+      }
+
+      const { resourceCount, errorCount, longTaskCount } = eventCountsSubscription.eventCounts
+      const clickAction: ClickAction = {
+        duration: activityEndTime && elapsed(startClocks.timeStamp, activityEndTime),
+        startClocks,
+        id,
+        frustrationTypes,
+        counts: {
+          resourceCount,
+          errorCount,
+          longTaskCount,
+        },
+        events: domEvents ?? [startEvent],
+        event: startEvent,
+        ...clickActionBase,
+      }
+
+      lifeCycle.notify(LifeCycleEventType.AUTO_ACTION_COMPLETED, clickAction)
+      status = ClickStatus.FINALIZED
+    },
+
+    discard: () => {
+      stop()
+      status = ClickStatus.FINALIZED
+    },
+  }
+}
+
+export function finalizeClicks(clicks: Click[], rageClick: Click) {
+  const { isRage } = computeFrustration(clicks, rageClick)
+  if (isRage) {
+    clicks.forEach((click) => click.discard())
+    rageClick.stop(timeStampNow())
+    rageClick.validate(clicks.map((click) => click.event))
+  } else {
+    rageClick.discard()
+    clicks.forEach((click) => click.validate())
+  }
+}

package/src/domain/assembly.ts

@@ -0,0 +1,141 @@
+import type { RawError, EventRateLimiter } from '@kubesense/kubesense-browser-core'
+import {
+  combine,
+  isEmptyObject,
+  display,
+  createEventRateLimiter,
+  HookNames,
+  DISCARDED,
+  buildTags,
+} from '@kubesense/kubesense-browser-core'
+import type { RumEventDomainContext } from '../domainContext.types'
+import type { AssembledRumEvent } from '../rawRumEvent.types'
+import { RumEventType } from '../rawRumEvent.types'
+import type { LifeCycle } from './lifeCycle'
+import { LifeCycleEventType } from './lifeCycle'
+import type { RumConfiguration } from './configuration'
+import type { ModifiableFieldPaths } from './limitModification'
+import { limitModification } from './limitModification'
+import type { Hooks } from './hooks'
+
+const VIEW_MODIFIABLE_FIELD_PATHS: ModifiableFieldPaths = {
+  'view.name': 'string',
+  'view.url': 'string',
+  'view.referrer': 'string',
+}
+
+const USER_CUSTOMIZABLE_FIELD_PATHS: ModifiableFieldPaths = {
+  context: 'object',
+}
+
+const ROOT_MODIFIABLE_FIELD_PATHS: ModifiableFieldPaths = {
+  service: 'string',
+  version: 'string',
+}
+
+let modifiableFieldPathsByEvent: { [key in RumEventType]: ModifiableFieldPaths }
+
+export function startRumAssembly(
+  configuration: RumConfiguration,
+  lifeCycle: LifeCycle,
+  hooks: Hooks,
+  reportError: (error: RawError) => void,
+  eventRateLimit?: number
+) {
+  modifiableFieldPathsByEvent = {
+    [RumEventType.VIEW]: {
+      'view.performance.lcp.resource_url': 'string',
+      ...USER_CUSTOMIZABLE_FIELD_PATHS,
+      ...VIEW_MODIFIABLE_FIELD_PATHS,
+      ...ROOT_MODIFIABLE_FIELD_PATHS,
+    },
+    [RumEventType.ERROR]: {
+      'error.message': 'string',
+      'error.stack': 'string',
+      'error.resource.url': 'string',
+      'error.fingerprint': 'string',
+      ...USER_CUSTOMIZABLE_FIELD_PATHS,
+      ...VIEW_MODIFIABLE_FIELD_PATHS,
+      ...ROOT_MODIFIABLE_FIELD_PATHS,
+    },
+    [RumEventType.RESOURCE]: {
+      'resource.url': 'string',
+      'resource.graphql.variables': 'string',
+      ...USER_CUSTOMIZABLE_FIELD_PATHS,
+      ...VIEW_MODIFIABLE_FIELD_PATHS,
+      ...ROOT_MODIFIABLE_FIELD_PATHS,
+    },
+    [RumEventType.ACTION]: {
+      'action.target.name': 'string',
+      ...USER_CUSTOMIZABLE_FIELD_PATHS,
+      ...VIEW_MODIFIABLE_FIELD_PATHS,
+      ...ROOT_MODIFIABLE_FIELD_PATHS,
+    },
+    [RumEventType.LONG_TASK]: {
+      'long_task.scripts[].source_url': 'string',
+      'long_task.scripts[].invoker': 'string',
+      ...USER_CUSTOMIZABLE_FIELD_PATHS,
+      ...VIEW_MODIFIABLE_FIELD_PATHS,
+      ...ROOT_MODIFIABLE_FIELD_PATHS,
+    },
+    [RumEventType.VITAL]: {
+      ...USER_CUSTOMIZABLE_FIELD_PATHS,
+      ...VIEW_MODIFIABLE_FIELD_PATHS,
+      ...ROOT_MODIFIABLE_FIELD_PATHS,
+    },
+  }
+  const eventRateLimiters = {
+    [RumEventType.ERROR]: createEventRateLimiter(RumEventType.ERROR, reportError, eventRateLimit),
+    [RumEventType.ACTION]: createEventRateLimiter(RumEventType.ACTION, reportError, eventRateLimit),
+    [RumEventType.VITAL]: createEventRateLimiter(RumEventType.VITAL, reportError, eventRateLimit),
+  }
+
+  lifeCycle.subscribe(
+    LifeCycleEventType.RAW_RUM_EVENT_COLLECTED,
+    ({ startTime, duration, rawRumEvent, domainContext }) => {
+      const defaultRumEventAttributes = hooks.triggerHook(HookNames.Assemble, {
+        eventType: rawRumEvent.type,
+        startTime,
+        duration,
+      })!
+
+      if (defaultRumEventAttributes === DISCARDED) {
+        return
+      }
+
+      const serverRumEvent = combine(defaultRumEventAttributes, rawRumEvent, {
+        ddtags: buildTags(configuration).join(','),
+      }) as AssembledRumEvent
+
+      if (shouldSend(serverRumEvent, configuration.beforeSend, domainContext, eventRateLimiters)) {
+        if (isEmptyObject(serverRumEvent.context!)) {
+          delete serverRumEvent.context
+        }
+        lifeCycle.notify(LifeCycleEventType.RUM_EVENT_COLLECTED, serverRumEvent)
+      }
+    }
+  )
+}
+
+function shouldSend(
+  event: AssembledRumEvent,
+  beforeSend: RumConfiguration['beforeSend'],
+  domainContext: RumEventDomainContext,
+  eventRateLimiters: { [key in RumEventType]?: EventRateLimiter }
+) {
+  if (beforeSend) {
+    const result = limitModification(event, modifiableFieldPathsByEvent[event.type], (event) =>
+      beforeSend(event, domainContext)
+    )
+    if (result === false && event.type !== RumEventType.VIEW) {
+      return false
+    }
+    if (result === false) {
+      display.warn("Can't dismiss view events using beforeSend!")
+    }
+  }
+
+  const rateLimitReached = eventRateLimiters[event.type]?.isLimitReached()
+
+  return !rateLimitReached
+}