@kubesense/kubesense-browser-rum-core 1.0.0

package/src/domain/vital/vitalCollection.ts

@@ -0,0 +1,207 @@
+import type { ClocksState, Duration } from '@kubesense/kubesense-browser-core'
+import {
+  clocksNow,
+  combine,
+  elapsed,
+  ExperimentalFeature,
+  generateUUID,
+  isExperimentalFeatureEnabled,
+  sanitize,
+  toServerDuration,
+} from '@kubesense/kubesense-browser-core'
+import type { LifeCycle, RawRumEventCollectedData } from '../lifeCycle'
+import { LifeCycleEventType } from '../lifeCycle'
+import type { RawRumVitalEvent } from '../../rawRumEvent.types'
+import { RumEventType, VitalType } from '../../rawRumEvent.types'
+import type { PageStateHistory } from '../contexts/pageStateHistory'
+import { PageState } from '../contexts/pageStateHistory'
+
+export interface VitalOptions {
+  context?: any
+  description?: string
+}
+export type DurationVitalOptions = VitalOptions
+export interface FeatureOperationOptions extends VitalOptions {
+  operationKey?: string
+}
+
+export type FailureReason = 'error' | 'abandoned' | 'other'
+export interface AddDurationVitalOptions extends DurationVitalOptions {
+  startTime: number
+  duration: number
+}
+
+export interface DurationVitalReference {
+  __kubesense_vital_reference: true
+}
+
+export interface DurationVitalStart extends DurationVitalOptions {
+  name: string
+  startClocks: ClocksState
+}
+
+interface BaseVital extends VitalOptions {
+  name: string
+  startClocks: ClocksState
+}
+export interface DurationVital extends BaseVital {
+  type: typeof VitalType.DURATION
+  duration: Duration
+}
+
+export interface OperationStepVital extends BaseVital {
+  type: typeof VitalType.OPERATION_STEP
+  stepType: 'start' | 'end'
+  operationKey?: string
+  failureReason?: string
+}
+
+export interface CustomVitalsState {
+  vitalsByName: Map<string, DurationVitalStart>
+  vitalsByReference: WeakMap<DurationVitalReference, DurationVitalStart>
+}
+
+export function createCustomVitalsState() {
+  const vitalsByName = new Map<string, DurationVitalStart>()
+  const vitalsByReference = new WeakMap<DurationVitalReference, DurationVitalStart>()
+  return { vitalsByName, vitalsByReference }
+}
+
+export function startVitalCollection(
+  lifeCycle: LifeCycle,
+  pageStateHistory: PageStateHistory,
+  customVitalsState: CustomVitalsState
+) {
+  function isValid(vital: DurationVital) {
+    return !pageStateHistory.wasInPageStateDuringPeriod(PageState.FROZEN, vital.startClocks.relative, vital.duration)
+  }
+
+  function addDurationVital(vital: DurationVital) {
+    if (isValid(vital)) {
+      lifeCycle.notify(LifeCycleEventType.RAW_RUM_EVENT_COLLECTED, processVital(vital))
+    }
+  }
+
+  function addOperationStepVital(
+    name: string,
+    stepType: 'start' | 'end',
+    options?: FeatureOperationOptions,
+    failureReason?: FailureReason
+  ) {
+    if (!isExperimentalFeatureEnabled(ExperimentalFeature.FEATURE_OPERATION_VITAL)) {
+      return
+    }
+
+    const { operationKey, context, description } = options || {}
+
+    const vital: OperationStepVital = {
+      name,
+      type: VitalType.OPERATION_STEP,
+      operationKey,
+      failureReason,
+      stepType,
+      startClocks: clocksNow(),
+      context: sanitize(context),
+      description,
+    }
+    lifeCycle.notify(LifeCycleEventType.RAW_RUM_EVENT_COLLECTED, processVital(vital))
+  }
+
+  return {
+    addOperationStepVital,
+    addDurationVital,
+    startDurationVital: (name: string, options: DurationVitalOptions = {}) =>
+      startDurationVital(customVitalsState, name, options),
+    stopDurationVital: (nameOrRef: string | DurationVitalReference, options: DurationVitalOptions = {}) => {
+      stopDurationVital(addDurationVital, customVitalsState, nameOrRef, options)
+    },
+  }
+}
+
+export function startDurationVital(
+  { vitalsByName, vitalsByReference }: CustomVitalsState,
+  name: string,
+  options: DurationVitalOptions = {}
+) {
+  const vital = {
+    name,
+    startClocks: clocksNow(),
+    ...options,
+  }
+
+  // To avoid leaking implementation details of the vital, we return a reference to it.
+  const reference: DurationVitalReference = { __kubesense_vital_reference: true }
+
+  vitalsByName.set(name, vital)
+
+  // To avoid memory leaks caused by the creation of numerous references (e.g., from improper useEffect implementations), we use a WeakMap.
+  vitalsByReference.set(reference, vital)
+
+  return reference
+}
+
+export function stopDurationVital(
+  stopCallback: (vital: DurationVital) => void,
+  { vitalsByName, vitalsByReference }: CustomVitalsState,
+  nameOrRef: string | DurationVitalReference,
+  options: DurationVitalOptions = {}
+) {
+  const vitalStart = typeof nameOrRef === 'string' ? vitalsByName.get(nameOrRef) : vitalsByReference.get(nameOrRef)
+
+  if (!vitalStart) {
+    return
+  }
+
+  stopCallback(buildDurationVital(vitalStart, vitalStart.startClocks, options, clocksNow()))
+
+  if (typeof nameOrRef === 'string') {
+    vitalsByName.delete(nameOrRef)
+  } else {
+    vitalsByReference.delete(nameOrRef)
+  }
+}
+
+function buildDurationVital(
+  vitalStart: DurationVitalStart,
+  startClocks: ClocksState,
+  stopOptions: DurationVitalOptions,
+  stopClocks: ClocksState
+): DurationVital {
+  return {
+    name: vitalStart.name,
+    type: VitalType.DURATION,
+    startClocks,
+    duration: elapsed(startClocks.timeStamp, stopClocks.timeStamp),
+    context: combine(vitalStart.context, stopOptions.context),
+    description: stopOptions.description ?? vitalStart.description,
+  }
+}
+
+function processVital(vital: DurationVital | OperationStepVital): RawRumEventCollectedData<RawRumVitalEvent> {
+  const { startClocks, type, name, description, context } = vital
+  const vitalData = {
+    id: generateUUID(),
+    type,
+    name,
+    description,
+    ...(type === VitalType.DURATION
+      ? { duration: toServerDuration(vital.duration) }
+      : {
+          step_type: vital.stepType,
+          operation_key: vital.operationKey,
+          failure_reason: vital.failureReason,
+        }),
+  }
+
+  return {
+    rawRumEvent: {
+      date: startClocks.timeStamp,
+      vital: vitalData,
+      type: RumEventType.VITAL,
+      context,
+    },
+    startTime: startClocks.relative,
+    duration: type === VitalType.DURATION ? vital.duration : undefined,
+    domainContext: {},
+  }
+}

package/src/domain/waitPageActivityEnd.ts

@@ -0,0 +1,189 @@
+import type { Subscription, TimeoutId, TimeStamp } from '@kubesense/kubesense-browser-core'
+import { matchList, monitor, Observable, timeStampNow, setTimeout, clearTimeout } from '@kubesense/kubesense-browser-core'  
+import { createPerformanceObservable, RumPerformanceEntryType } from '../browser/performanceObservable'
+import type { RumMutationRecord } from '../browser/domMutationObservable'
+import { isElementNode } from '../browser/htmlDomUtils'
+import type { RumConfiguration } from './configuration'
+import type { LifeCycle } from './lifeCycle'
+import { LifeCycleEventType } from './lifeCycle'
+
+// Delay to wait for a page activity to validate the tracking process
+export const PAGE_ACTIVITY_VALIDATION_DELAY = 100
+// Delay to wait after a page activity to end the tracking process
+export const PAGE_ACTIVITY_END_DELAY = 100
+
+export const EXCLUDED_MUTATIONS_ATTRIBUTE = 'data-kubesense-excluded-activity-mutations'
+
+export interface PageActivityEvent {
+  isBusy: boolean
+}
+
+export type PageActivityEndEvent = { hadActivity: true; end: TimeStamp } | { hadActivity: false }
+
+/**
+ * Wait for the page activity end
+ *
+ * Detection lifecycle:
+ * ```
+ *                        Wait page activity end
+ *              .-------------------'--------------------.
+ *              v                                        v
+ *     [Wait for a page activity ]          [Wait for a maximum duration]
+ *     [timeout: VALIDATION_DELAY]          [  timeout: maxDuration     ]
+ *          /                  \                           |
+ *         v                    v                          |
+ *  [No page activity]   [Page activity]                   |
+ *         |                   |,----------------------.   |
+ *         v                   v                       |   |
+ *     (Discard)     [Wait for a page activity]        |   |
+ *                   [   timeout: END_DELAY   ]        |   |
+ *                       /                \            |   |
+ *                      v                  v           |   |
+ *             [No page activity]    [Page activity]   |   |
+ *                      |                 |            |   |
+ *                      |                 '------------'   |
+ *                      '-----------. ,--------------------'
+ *                                   v
+ *                                 (End)
+ * ```
+ *
+ * Note: by assuming that maxDuration is greater than VALIDATION_DELAY, we are sure that if the
+ * process is still alive after maxDuration, it has been validated.
+ */
+export function waitPageActivityEnd(
+  lifeCycle: LifeCycle,
+  domMutationObservable: Observable<RumMutationRecord[]>,
+  windowOpenObservable: Observable<void>,
+  configuration: RumConfiguration,
+  pageActivityEndCallback: (event: PageActivityEndEvent) => void,
+  maxDuration?: number
+) {
+  const pageActivityObservable = createPageActivityObservable(
+    lifeCycle,
+    domMutationObservable,
+    windowOpenObservable,
+    configuration
+  )
+  return doWaitPageActivityEnd(pageActivityObservable, pageActivityEndCallback, maxDuration)
+}
+
+export function doWaitPageActivityEnd(
+  pageActivityObservable: Observable<PageActivityEvent>,
+  pageActivityEndCallback: (event: PageActivityEndEvent) => void,
+  maxDuration?: number
+) {
+  let pageActivityEndTimeoutId: TimeoutId
+  let hasCompleted = false
+
+  const validationTimeoutId = setTimeout(
+    monitor(() => complete({ hadActivity: false })),
+    PAGE_ACTIVITY_VALIDATION_DELAY
+  )
+  const maxDurationTimeoutId =
+    maxDuration !== undefined
+      ? setTimeout(
+          monitor(() => complete({ hadActivity: true, end: timeStampNow() })),
+          maxDuration
+        )
+      : undefined
+
+  const pageActivitySubscription = pageActivityObservable.subscribe(({ isBusy }) => {
+    clearTimeout(validationTimeoutId)
+    clearTimeout(pageActivityEndTimeoutId)
+    const lastChangeTime = timeStampNow()
+    if (!isBusy) {
+      pageActivityEndTimeoutId = setTimeout(
+        monitor(() => complete({ hadActivity: true, end: lastChangeTime })),
+        PAGE_ACTIVITY_END_DELAY
+      )
+    }
+  })
+
+  const stop = () => {
+    hasCompleted = true
+    clearTimeout(validationTimeoutId)
+    clearTimeout(pageActivityEndTimeoutId)
+    clearTimeout(maxDurationTimeoutId)
+    pageActivitySubscription.unsubscribe()
+  }
+
+  function complete(event: PageActivityEndEvent) {
+    if (hasCompleted) {
+      return
+    }
+    stop()
+    pageActivityEndCallback(event)
+  }
+  return { stop }
+}
+
+export function createPageActivityObservable(
+  lifeCycle: LifeCycle,
+  domMutationObservable: Observable<RumMutationRecord[]>,
+  windowOpenObservable: Observable<void>,
+  configuration: RumConfiguration
+): Observable<PageActivityEvent> {
+  return new Observable<PageActivityEvent>((observable) => {
+    const subscriptions: Subscription[] = []
+    let firstRequestIndex: undefined | number
+    let pendingRequestsCount = 0
+
+    subscriptions.push(
+      domMutationObservable.subscribe((mutations) => {
+        if (!mutations.every(isExcludedMutation)) {
+          notifyPageActivity()
+        }
+      }),
+      windowOpenObservable.subscribe(notifyPageActivity),
+      createPerformanceObservable(configuration, { type: RumPerformanceEntryType.RESOURCE }).subscribe((entries) => {
+        if (entries.some((entry) => !isExcludedUrl(configuration, entry.name))) {
+          notifyPageActivity()
+        }
+      }),
+      lifeCycle.subscribe(LifeCycleEventType.REQUEST_STARTED, (startEvent) => {
+        if (isExcludedUrl(configuration, startEvent.url)) {
+          return
+        }
+        if (firstRequestIndex === undefined) {
+          firstRequestIndex = startEvent.requestIndex
+        }
+        pendingRequestsCount += 1
+        notifyPageActivity()
+      }),
+      lifeCycle.subscribe(LifeCycleEventType.REQUEST_COMPLETED, (request) => {
+        if (
+          isExcludedUrl(configuration, request.url) ||
+          firstRequestIndex === undefined ||
+          // If the request started before the tracking start, ignore it
+          request.requestIndex < firstRequestIndex
+        ) {
+          return
+        }
+        pendingRequestsCount -= 1
+        notifyPageActivity()
+      })
+    )
+
+    return () => {
+      subscriptions.forEach((s) => s.unsubscribe())
+    }
+
+    function notifyPageActivity() {
+      observable.notify({ isBusy: pendingRequestsCount > 0 })
+    }
+  })
+}
+
+function isExcludedUrl(configuration: RumConfiguration, requestUrl: string): boolean {
+  return matchList(configuration.excludedActivityUrls, requestUrl)
+}
+
+function isExcludedMutation(mutation: RumMutationRecord): boolean {
+  const targetElement = mutation.type === 'characterData' ? mutation.target.parentElement : mutation.target
+
+  return Boolean(
+    targetElement &&
+    isElementNode(targetElement) &&
+    targetElement.matches(`[${EXCLUDED_MUTATIONS_ATTRIBUTE}], [${EXCLUDED_MUTATIONS_ATTRIBUTE}] *`)
+  )
+}

package/src/domainContext.types.ts

@@ -0,0 +1,61 @@
+/**
+ * Keep these types in a separate file in order to reference it from the official doc
+ */
+
+import type { RumEventType } from './rawRumEvent.types'
+
+export type RumEventDomainContext<T extends RumEventType = any> = T extends typeof RumEventType.VIEW
+  ? RumViewEventDomainContext
+  : T extends typeof RumEventType.ACTION
+    ? RumActionEventDomainContext
+    : T extends typeof RumEventType.RESOURCE
+      ? RumFetchResourceEventDomainContext | RumXhrResourceEventDomainContext | RumOtherResourceEventDomainContext
+      : T extends typeof RumEventType.ERROR
+        ? RumErrorEventDomainContext
+        : T extends typeof RumEventType.LONG_TASK
+          ? RumLongTaskEventDomainContext
+          : T extends typeof RumEventType.VITAL
+            ? RumVitalEventDomainContext
+            : never
+
+export interface RumViewEventDomainContext {
+  location: Readonly<Location>
+}
+
+export interface RumActionEventDomainContext {
+  events?: Event[]
+  handlingStack?: string
+}
+
+export interface RumFetchResourceEventDomainContext {
+  requestInit: RequestInit | undefined
+  requestInput: RequestInfo
+  response: Response | undefined
+  error: Error | undefined
+  performanceEntry: PerformanceEntry | undefined
+  isAborted: boolean
+  handlingStack: string | undefined
+}
+
+export interface RumXhrResourceEventDomainContext {
+  xhr: XMLHttpRequest
+  performanceEntry: PerformanceEntry | undefined
+  isAborted: boolean
+  handlingStack: string | undefined
+}
+
+export interface RumOtherResourceEventDomainContext {
+  performanceEntry: PerformanceEntry
+}
+
+export interface RumErrorEventDomainContext {
+  error: unknown
+  handlingStack?: string
+}
+
+export interface RumLongTaskEventDomainContext {
+  performanceEntry: PerformanceEntry
+}
+
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export interface RumVitalEventDomainContext {}

package/src/index.ts

@@ -0,0 +1,76 @@
+export type { RumPublicApi, RecorderApi, ProfilerApi, StartRecordingOptions, Strategy } from './boot/rumPublicApi'
+export { makeRumPublicApi } from './boot/rumPublicApi'
+export type { StartRum, StartRumResult } from './boot/startRum'
+export type {
+  RumEvent,
+  RumActionEvent,
+  CommonProperties,
+  RumErrorEvent,
+  RumViewEvent,
+  RumResourceEvent,
+  RumLongTaskEvent,
+  RumVitalEvent,
+  ProfilingInternalContextSchema,
+} from './rumEvent.types'
+export type {
+  RumLongTaskEventDomainContext,
+  RumErrorEventDomainContext,
+  RumOtherResourceEventDomainContext,
+  RumXhrResourceEventDomainContext,
+  RumFetchResourceEventDomainContext,
+  RumActionEventDomainContext,
+  RumViewEventDomainContext,
+  RumEventDomainContext,
+  RumVitalEventDomainContext,
+} from './domainContext.types'
+export type { ReplayStats, RawRumActionEvent, RawRumEvent } from './rawRumEvent.types'
+export { ActionType, RumEventType, FrustrationType } from './rawRumEvent.types'
+export { startRum } from './boot/startRum'
+export type { RawRumEventCollectedData } from './domain/lifeCycle'
+export { LifeCycle, LifeCycleEventType } from './domain/lifeCycle'
+export type { ViewCreatedEvent, ViewOptions } from './domain/view/trackViews'
+export type { ViewHistoryEntry, ViewHistory } from './domain/contexts/viewHistory'
+export type { LongTaskContexts, LongTaskContext } from './domain/longTask/longTaskCollection'
+export { startViewHistory } from './domain/contexts/viewHistory'
+export type { RumSessionManager, RumSession } from './domain/rumSessionManager'
+export { getMutationObserverConstructor } from './browser/domMutationObservable'
+export type {
+  RumMutationRecord,
+  RumAttributesMutationRecord,
+  RumChildListMutationRecord,
+  RumCharacterDataMutationRecord,
+} from './browser/domMutationObservable'
+export type { ViewportDimension } from './browser/viewportObservable'
+export { initViewportObservable, getViewportDimension } from './browser/viewportObservable'
+export { getScrollX, getScrollY } from './browser/scroll'
+export type {
+  RumInitConfiguration,
+  RumConfiguration,
+  FeatureFlagsForEvents,
+  RemoteConfiguration,
+} from './domain/configuration'
+export { DEFAULT_PROGRAMMATIC_ACTION_NAME_ATTRIBUTE } from './domain/action/actionNameConstants'
+export { STABLE_ATTRIBUTES } from './domain/getSelectorFromElement'
+export * from './browser/htmlDomUtils'
+export { getSessionReplayUrl } from './domain/getSessionReplayUrl'
+export { sanitizeIfLongDataUrl } from './domain/resource/resourceUtils'
+export * from './domain/privacy'
+export * from './domain/privacyConstants'
+export { SessionReplayState } from './domain/rumSessionManager'
+export type { RumPlugin, OnRumStartOptions } from './domain/plugins'
+export type { MouseEventOnElement } from './domain/action/listenActionEvents'
+export { supportPerformanceTimingEvent } from './browser/performanceObservable'
+export { RumPerformanceEntryType } from './browser/performanceObservable'
+export type { AllowedRawRumEvent } from './domain/event/eventCollection'
+export type {
+  DurationVitalReference,
+  DurationVitalStart,
+  AddDurationVitalOptions,
+  DurationVitalOptions,
+} from './domain/vital/vitalCollection'
+export type { Hooks, DefaultRumEventAttributes, DefaultTelemetryEventAttributes } from './domain/hooks'
+export { createHooks } from './domain/hooks'
+export { isSampled } from './domain/sampler/sampler'
+export type { TracingOption, PropagatorType } from './domain/tracing/tracer.types'
+export type { TransportPayload } from './transport/formDataTransport'
+export { createFormDataTransport } from './transport/formDataTransport'