@kubesense/kubesense-browser-rum-core 1.7.0 → 2.0.0-beta.1

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

@@ -1,15 +1,7 @@
-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 { ONE_SECOND, elapsed, relativeNow } from '@kubesense/kubesense-js-core/time'
+import type { Duration, ClocksState } from '@kubesense/kubesense-js-core/time'
+import { monitor } from '@kubesense/kubesense-js-core/monitor'
+import { Observable, throttle, addEventListener, DOM_EVENT } from '@kubesense/kubesense-browser-core'
 import { getScrollY } from '../../../browser/scroll'
 import { getViewportDimension } from '../../../browser/viewportObservable'
 
@@ -24,10 +16,9 @@ export interface ScrollMetrics {
 }
 
 export function trackScrollMetrics(
-  configuration: RumConfiguration,
   viewStart: ClocksState,
   callback: (scrollMetrics: ScrollMetrics) => void,
-  scrollValues = createScrollValuesObservable(configuration)
+  scrollValues = createScrollValuesObservable()
 ) {
   let maxScrollDepth = 0
   let maxScrollHeight = 0
@@ -85,35 +76,30 @@ export function computeScrollValues() {
   }
 }
 
-export function createScrollValuesObservable(
-  configuration: RumConfiguration,
-  throttleDuration = THROTTLE_SCROLL_DURATION
-): Observable<ScrollValues> {
+export function createScrollValuesObservable(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,
-      })
+    const throttledNotify = throttle(notify, throttleDuration, {
+      leading: false,
+      trailing: true,
+    })
 
-      return () => {
-        throttledNotify.cancel()
-        resizeObserver.disconnect()
-        eventListener.stop()
-      }
+    const observerTarget = document.scrollingElement || document.documentElement
+    const resizeObserver = new ResizeObserver(monitor(throttledNotify.throttled))
+    if (observerTarget) {
+      resizeObserver.observe(observerTarget)
+    }
+    const eventListener = addEventListener(window, DOM_EVENT.SCROLL, throttledNotify.throttled, {
+      passive: true,
+    })
+
+    return () => {
+      throttledNotify.cancel()
+      resizeObserver.disconnect()
+      eventListener.stop()
     }
   })
 }

package/src/domain/vital/vitalCollection.ts

@@ -1,50 +1,78 @@
-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 { ClocksState, Duration } from '@kubesense/kubesense-js-core/time'
+import { toServerDuration, clocksNow } from '@kubesense/kubesense-js-core/time'
+import { generateUUID, sanitize } 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'
+import { startEventTracker } from '../eventTracker'
 
+/**
+ * Vital options
+ */
 export interface VitalOptions {
+  /**
+   * Vital context
+   */
   context?: any
+
+  /**
+   * Vital description
+   */
   description?: string
 }
-export type DurationVitalOptions = VitalOptions
-export interface FeatureOperationOptions extends VitalOptions {
+
+/**
+ * Duration vital options
+ */
+export interface DurationVitalOptions extends VitalOptions {
+  /**
+   * Vital key, used to identify a specific vital instance when multiple vitals with the same name
+   * are tracked simultaneously
+   */
+  vitalKey?: string
+}
+
+export interface OperationOptions extends VitalOptions {
   operationKey?: string
 }
 
+/** @deprecated Use {@link OperationOptions} instead. */
+export type FeatureOperationOptions = OperationOptions
+
 export type FailureReason = 'error' | 'abandoned' | 'other'
+
+/**
+ * Add duration vital options
+ */
 export interface AddDurationVitalOptions extends DurationVitalOptions {
+  /**
+   * Vital start time, expects a UNIX timestamp in milliseconds (the number of milliseconds since January 1, 1970)
+   */
   startTime: number
-  duration: number
-}
 
-export interface DurationVitalReference {
-  __kubesense_vital_reference: true
+  /**
+   * Vital duration, expects a duration in milliseconds
+   */
+  duration: number
 }
 
 export interface DurationVitalStart extends DurationVitalOptions {
+  id: string
   name: string
   startClocks: ClocksState
+  handlingStack?: string
 }
 
 interface BaseVital extends VitalOptions {
   name: string
   startClocks: ClocksState
+  handlingStack?: string
 }
 export interface DurationVital extends BaseVital {
+  id: string
   type: typeof VitalType.DURATION
   duration: Duration
 }
@@ -56,22 +84,16 @@ export interface OperationStepVital extends BaseVital {
   failureReason?: string
 }
 
-export interface CustomVitalsState {
-  vitalsByName: Map<string, DurationVitalStart>
-  vitalsByReference: WeakMap<DurationVitalReference, DurationVitalStart>
+interface DurationVitalData {
+  name: string
+  context?: any
+  description?: string
+  handlingStack?: string
 }
 
-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) {
+  const vitalTracker = startEventTracker<DurationVitalData>(lifeCycle)
 
-export function startVitalCollection(
-  lifeCycle: LifeCycle,
-  pageStateHistory: PageStateHistory,
-  customVitalsState: CustomVitalsState
-) {
   function isValid(vital: DurationVital) {
     return !pageStateHistory.wasInPageStateDuringPeriod(PageState.FROZEN, vital.startClocks.relative, vital.duration)
   }
@@ -85,14 +107,10 @@ export function startVitalCollection(
   function addOperationStepVital(
     name: string,
     stepType: 'start' | 'end',
-    options?: FeatureOperationOptions,
+    options?: OperationOptions & { handlingStack?: string },
     failureReason?: FailureReason
   ) {
-    if (!isExperimentalFeatureEnabled(ExperimentalFeature.FEATURE_OPERATION_VITAL)) {
-      return
-    }
-
-    const { operationKey, context, description } = options || {}
+    const { operationKey, context, description, handlingStack } = options || {}
 
     const vital: OperationStepVital = {
       name,
@@ -103,84 +121,47 @@ export function startVitalCollection(
       startClocks: clocksNow(),
       context: sanitize(context),
       description,
+      handlingStack,
     }
     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
+  function startDurationVital(
+    name: string,
+    options: DurationVitalOptions & { handlingStack?: string } = {},
+    startClocks = clocksNow()
+  ) {
+    const { id } = vitalTracker.start(options.vitalKey ?? name, startClocks, {
+      name,
+      ...options,
+    })
+    lifeCycle.notify(LifeCycleEventType.DURATION_VITAL_STARTED, { id, name, startClocks, ...options })
   }
 
-  stopCallback(buildDurationVital(vitalStart, vitalStart.startClocks, options, clocksNow()))
-
-  if (typeof nameOrRef === 'string') {
-    vitalsByName.delete(nameOrRef)
-  } else {
-    vitalsByReference.delete(nameOrRef)
+  function stopDurationVital(name: string, options: DurationVitalOptions = {}, stopClocks = clocksNow()) {
+    const stopped = vitalTracker.stop(options.vitalKey ?? name, stopClocks, options)
+    if (stopped) {
+      addDurationVital({
+        type: VitalType.DURATION,
+        ...stopped,
+      })
+    }
   }
-}
 
-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,
+    addOperationStepVital,
+    addDurationVital,
+    startDurationVital,
+    stopDurationVital,
   }
 }
 
 function processVital(vital: DurationVital | OperationStepVital): RawRumEventCollectedData<RawRumVitalEvent> {
-  const { startClocks, type, name, description, context } = vital
+  const { startClocks, type, name, description, context, handlingStack } = vital
+  const vitalId = vital.type === VitalType.DURATION ? vital.id : undefined
+
   const vitalData = {
-    id: generateUUID(),
+    id: vitalId ?? generateUUID(),
     type,
     name,
     description,
@@ -200,8 +181,8 @@ function processVital(vital: DurationVital | OperationStepVital): RawRumEventCol
       type: RumEventType.VITAL,
       context,
     },
-    startTime: startClocks.relative,
+    startClocks,
     duration: type === VitalType.DURATION ? vital.duration : undefined,
-    domainContext: {},
+    domainContext: handlingStack ? { handlingStack } : {},
   }
 }

package/src/domain/waitPageActivityEnd.ts

@@ -1,5 +1,8 @@
-import type { Subscription, TimeoutId, TimeStamp } from '@kubesense/kubesense-browser-core'
-import { matchList, monitor, Observable, timeStampNow, setTimeout, clearTimeout } from '@kubesense/kubesense-browser-core'  
+import type { Subscription, TimeoutId } from '@kubesense/kubesense-browser-core'
+import { timeStampNow } from '@kubesense/kubesense-js-core/time'
+import type { TimeStamp } from '@kubesense/kubesense-js-core/time'
+import { monitor } from '@kubesense/kubesense-js-core/monitor'
+import { matchList, Observable, setTimeout, clearTimeout, mockable } from '@kubesense/kubesense-browser-core'
 import { createPerformanceObservable, RumPerformanceEntryType } from '../browser/performanceObservable'
 import type { RumMutationRecord } from '../browser/domMutationObservable'
 import { isElementNode } from '../browser/htmlDomUtils'
@@ -58,20 +61,13 @@ export function waitPageActivityEnd(
   pageActivityEndCallback: (event: PageActivityEndEvent) => void,
   maxDuration?: number
 ) {
-  const pageActivityObservable = createPageActivityObservable(
+  const pageActivityObservable = mockable(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
 
@@ -135,7 +131,7 @@ export function createPageActivityObservable(
         }
       }),
       windowOpenObservable.subscribe(notifyPageActivity),
-      createPerformanceObservable(configuration, { type: RumPerformanceEntryType.RESOURCE }).subscribe((entries) => {
+      createPerformanceObservable({ type: RumPerformanceEntryType.RESOURCE }).subscribe((entries) => {
         if (entries.some((entry) => !isExcludedUrl(configuration, entry.name))) {
           notifyPageActivity()
         }

package/src/domainContext.types.ts

@@ -9,7 +9,7 @@ export type RumEventDomainContext<T extends RumEventType = any> = T extends type
   : T extends typeof RumEventType.ACTION
     ? RumActionEventDomainContext
     : T extends typeof RumEventType.RESOURCE
-      ? RumFetchResourceEventDomainContext | RumXhrResourceEventDomainContext | RumOtherResourceEventDomainContext
+      ? RumResourceEventDomainContext | RumManualResourceEventDomainContext | RumWebSocketResourceEventDomainContext
       : T extends typeof RumEventType.ERROR
         ? RumErrorEventDomainContext
         : T extends typeof RumEventType.LONG_TASK
@@ -20,6 +20,7 @@ export type RumEventDomainContext<T extends RumEventType = any> = T extends type
 
 export interface RumViewEventDomainContext {
   location: Readonly<Location>
+  handlingStack?: string
 }
 
 export interface RumActionEventDomainContext {
@@ -27,25 +28,31 @@ export interface RumActionEventDomainContext {
   handlingStack?: string
 }
 
-export interface RumFetchResourceEventDomainContext {
+export interface RumResourceEventDomainContext {
+  isManual: false
+  isWebSocket: false
+  performanceEntry: PerformanceResourceTiming | PerformanceNavigationTiming
+  xhr: XMLHttpRequest | undefined
+  isAborted: boolean
+  handlingStack: string | undefined
   requestInit: RequestInit | undefined
-  requestInput: RequestInfo
+  requestInput: RequestInfo | undefined
   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 RumManualResourceEventDomainContext {
+  /**
+   * Manual resources created via startResource/stopResource do not have
+   * a performance entry or request/response objects.
+   */
+  isManual: true
 }
 
-export interface RumOtherResourceEventDomainContext {
-  performanceEntry: PerformanceEntry
+export interface RumWebSocketResourceEventDomainContext {
+  isManual: false
+  isWebSocket: true
+  webSocket: WebSocket
 }
 
 export interface RumErrorEventDomainContext {
@@ -57,5 +64,6 @@ export interface RumLongTaskEventDomainContext {
   performanceEntry: PerformanceEntry
 }
 
-// eslint-disable-next-line @typescript-eslint/no-empty-object-type
-export interface RumVitalEventDomainContext {}
+export interface RumVitalEventDomainContext {
+  handlingStack?: string
+}

package/src/index.ts

@@ -7,6 +7,7 @@ export type {
   CommonProperties,
   RumErrorEvent,
   RumViewEvent,
+  RumViewUpdateEvent,
   RumResourceEvent,
   RumLongTaskEvent,
   RumVitalEvent,
@@ -15,24 +16,23 @@ export type {
 export type {
   RumLongTaskEventDomainContext,
   RumErrorEventDomainContext,
-  RumOtherResourceEventDomainContext,
-  RumXhrResourceEventDomainContext,
-  RumFetchResourceEventDomainContext,
+  RumManualResourceEventDomainContext,
+  RumResourceEventDomainContext,
+  RumWebSocketResourceEventDomainContext,
   RumActionEventDomainContext,
   RumViewEventDomainContext,
   RumEventDomainContext,
   RumVitalEventDomainContext,
 } from './domainContext.types'
 export type { ReplayStats, RawRumActionEvent, RawRumEvent } from './rawRumEvent.types'
-export { ActionType, RumEventType, FrustrationType } from './rawRumEvent.types'
+export { ActionType, RumEventType, FrustrationType, RumLongTaskEntryType, VitalType } 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 type { SessionManager } from '@kubesense/kubesense-browser-core'
 export { getMutationObserverConstructor } from './browser/domMutationObservable'
 export type {
   RumMutationRecord,
@@ -46,10 +46,13 @@ export { getScrollX, getScrollY } from './browser/scroll'
 export type {
   RumInitConfiguration,
   RumConfiguration,
+  RumBeforeSend,
   FeatureFlagsForEvents,
   RemoteConfiguration,
+  MatchHeader,
   SessionReplayRoutes,
 } from './domain/configuration'
+export { DEFAULT_TRACKED_RESOURCE_HEADERS, CanvasRecordingQuality } from './domain/configuration'
 export { isRouteRecordable, getRoutePath } from './domain/configuration'
 export { DEFAULT_PROGRAMMATIC_ACTION_NAME_ATTRIBUTE } from './domain/action/actionNameConstants'
 export { STABLE_ATTRIBUTES } from './domain/getSelectorFromElement'
@@ -58,21 +61,24 @@ 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 { SessionReplayState, computeSessionReplayState } from './domain/sessionReplayState'
+export type { RumPlugin, OnRumStartOptions, RumPluginOnInitOptions } 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,
+  OperationOptions,
+  FeatureOperationOptions,
+  FailureReason,
 } from './domain/vital/vitalCollection'
+export type { ActionOptions } from './domain/action/trackManualActions'
+export type { ResourceOptions, ResourceStopOptions } from './domain/resource/trackManualResources'
 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'
+export { createFormDataTransport } from './transport/formDataTransport'