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

package/src/boot/rumPublicApi.ts

@@ -1,12 +1,12 @@
+import { timeStampNow, clocksNow, timeStampToClocks } from '@kubesense/kubesense-js-core/time'
+import { deepClone } from '@kubesense/kubesense-js-core/util'
+import type { Duration, TimeStamp, RelativeTime } from '@kubesense/kubesense-js-core/time'
 import type {
   Context,
-  TimeStamp,
-  RelativeTime,
   DeflateWorker,
   DeflateEncoderStreamId,
   DeflateEncoder,
   PublicApi,
-  Duration,
   ContextManager,
   TrackingConsent,
   User,
@@ -14,47 +14,49 @@ import type {
   RumInternalContext,
   Telemetry,
   Encoder,
+  ResourceType,
+  SessionManager,
 } from '@kubesense/kubesense-browser-core'
 import {
   ContextManagerMethod,
   addTelemetryUsage,
-  deepClone,
   makePublicApi,
-  monitor,
-  clocksNow,
-  callMonitored,
   createHandlingStack,
   sanitize,
   createIdentityEncoder,
   displayAlreadyInitializedError,
   createTrackingConsentState,
-  timeStampToClocks,
   CustomerContextKey,
   defineContextMethod,
   startBufferingData,
+  mockable,
+  generateUUID,
+  display,
 } from '@kubesense/kubesense-browser-core'
+import { monitor, callMonitored } from '@kubesense/kubesense-js-core/monitor'
 
 import type { LifeCycle } from '../domain/lifeCycle'
 import type { ViewHistory } from '../domain/contexts/viewHistory'
-import type { RumSessionManager } from '../domain/rumSessionManager'
 import type { ReplayStats } from '../rawRumEvent.types'
 import { ActionType, VitalType } from '../rawRumEvent.types'
+import { DEFAULT_TRACKED_RESOURCE_HEADERS } from '../domain/configuration'
 import type { RumConfiguration, RumInitConfiguration } from '../domain/configuration'
 import type { ViewOptions } from '../domain/view/trackViews'
 import type {
   AddDurationVitalOptions,
-  DurationVitalReference,
   DurationVitalOptions,
+  OperationOptions,
   FeatureOperationOptions,
   FailureReason,
 } from '../domain/vital/vitalCollection'
-import { createCustomVitalsState } from '../domain/vital/vitalCollection'
-import { callPluginsMethod } from '../domain/plugins'
+import { callPluginsOnRumStart } from '../domain/plugins'
 import type { Hooks } from '../domain/hooks'
 import type { SdkName } from '../domain/contexts/defaultContext'
-import type { LongTaskContexts } from '../domain/longTask/longTaskCollection'
+import type { ActionOptions } from '../domain/action/trackManualActions'
+import type { ResourceOptions, ResourceStopOptions } from '../domain/resource/trackManualResources'
 import { createPreStartStrategy } from './preStartRum'
-import type { StartRum, StartRumResult } from './startRum'
+import type { StartRumResult } from './startRum'
+import { startRum } from './startRum'
 
 export interface StartRecordingOptions {
   force: boolean
@@ -63,12 +65,16 @@ export interface StartRecordingOptions {
 /**
  * Public API for the RUM browser SDK.
  *
+ * See [RUM Browser Monitoring Setup](https://docs.kubesense.ai/real_user_monitoring/browser) for further information.
+ *
  * @category Main
  */
 export interface RumPublicApi extends PublicApi {
   /**
    * Init the RUM browser SDK.
    *
+   * See [RUM Browser Monitoring Setup](https://docs.kubesense.ai/real_user_monitoring/browser) for further information.
+   *
    * @category Init
    * @param initConfiguration - Configuration options of the SDK
    * @example
@@ -80,14 +86,12 @@ export interface RumPublicApi extends PublicApi {
    *   // ...
    * })
    * ```
-   *
    */
   init: (initConfiguration: RumInitConfiguration) => void
 
   /**
    * Set the tracking consent of the current user.
    *
-   *
    * Data will be sent only if it is set to "granted". This value won't be stored by the library
    * across page loads: you will need to call this method or set the appropriate `trackingConsent`
    * field in the init() method at each page load.
@@ -95,7 +99,8 @@ export interface RumPublicApi extends PublicApi {
    * If this method is called before the init() method, the provided value will take precedence
    * over the one provided as initialization parameter.
    *
-   * *
+   * See [User tracking consent](https://docs.kubesense.ai/real_user_monitoring/browser/advanced_configuration/#user-tracking-consent) for further information.
+   *
    * @category Privacy
    * @param trackingConsent - The user tracking consent
    */
@@ -105,8 +110,10 @@ export interface RumPublicApi extends PublicApi {
    * Set View Name.
    *
    * Enable to manually change the name of the current view.
+   * See [Override default RUM view names](https://docs.kubesense.ai/real_user_monitoring/browser/advanced_configuration/#override-default-rum-view-names) for further information.
+   *
    * @category Context - View
-   * @param name name of the view
+   * @param name - Name of the view
    */
   setViewName: (name: string) => void
 
@@ -114,14 +121,16 @@ export interface RumPublicApi extends PublicApi {
    * Set View Context.
    *
    * Enable to manually set the context of the current view.
+   *
    * @category Context - View
-   * @param context context of the view
+   * @param context - Context of the view
    */
   setViewContext: (context: Context) => void
   /**
    * Set View Context Property.
    *
    * Enable to manually set a property of the context of the current view.
+   *
    * @category Context - View
    * @param key - key of the property
    * @param value - value of the property
@@ -130,40 +139,106 @@ export interface RumPublicApi extends PublicApi {
 
   /**
    * Get View Context.
+   *
    * @category Context - View
-   * 
    */
   getViewContext(): Context
 
   /**
-   * Set the global context information to all events, stored in `@context`
-   *
-   * @category internal - View
-   * @param context Global context
+   * [Internal API] Get the internal SDK context
    *
+   * @internal
    */
   getInternalContext: (startTime?: number) => RumInternalContext | undefined
 
   /**
    * Get the init configuration
+   *
+   * @category Init
+   * @returns RumInitConfiguration | undefined
    */
   getInitConfiguration: () => RumInitConfiguration | undefined
 
   /**
    * Add a custom action, stored in `@action`
-   * @category Data Collection
-   * @param name Name of the action
-   * @param context Context of the action
    *
+   * See [Send RUM Custom Actions](https://docs.kubesense.ai/real_user_monitoring/guide/send-rum-custom-actions) for further information.
+   *
+   * @category Data Collection
+   * @param name - Name of the action
+   * @param context - Context of the action
    */
   addAction: (name: string, context?: object) => void
 
   /**
-   * Add a custom error, stored in `@error`.
+   * Start tracking a custom action.
+   *
+   * Call {@link stopAction} with the same name (and optional `actionKey`) to send a RUM action event
+   * with the elapsed duration. Errors and resources triggered between start and stop are associated
+   * with the action.
+   *
    * @category Data Collection
-   * @param error Error. Favor sending a [Javascript Error](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error) to have a stack trace attached to the error event.
-   * @param context Context of the error
+   * @param name - Name of the action
+   * @param options - Options of the action (@default type: 'custom')
+   * @example
+   * ```ts
+   * kubesenseSdk.startAction('checkout', { context: { cartId: 'abc' } })
+   * // ... user completes checkout
+   * kubesenseSdk.stopAction('checkout')
+   * ```
+   */
+  startAction: (name: string, options?: ActionOptions) => void
+
+  /**
+   * Stop tracking a custom action started with {@link startAction}.
+   *
+   * Sends a RUM action event with the elapsed duration since the matching start call. Context from
+   * start and stop calls is merged into the event.
    *
+   * @category Data Collection
+   * @param name - Name of the action
+   * @param options - Options of the action
+   */
+  stopAction: (name: string, options?: ActionOptions) => void
+
+  /**
+   * Start tracking a resource manually.
+   *
+   * Use this for network activity that the SDK cannot automatically instrument. Call {@link stopResource}
+   * with the same URL (and optional `resourceKey`) to send a RUM resource event with the elapsed duration.
+   *
+   * @category Data Collection
+   * @param url - URL of the resource
+   * @param options - Options of the resource (@default type: 'other')
+   * @example
+   * ```ts
+   * kubesenseSdk.startResource('https://api.example.com/users', { type: 'fetch', method: 'POST' })
+   * // ... perform the request
+   * kubesenseSdk.stopResource('https://api.example.com/users', { statusCode: 201 })
+   * ```
+   */
+  startResource: (url: string, options?: ResourceOptions) => void
+
+  /**
+   * Stop tracking a resource started with {@link startResource}.
+   *
+   * Sends a RUM resource event with the elapsed duration since the matching start call. Context from
+   * start and stop calls is merged into the event.
+   *
+   * @category Data Collection
+   * @param url - URL of the resource
+   * @param options - Options of the resource
+   */
+  stopResource: (url: string, options?: ResourceStopOptions) => void
+
+  /**
+   * Add a custom error, stored in `@error`.
+   *
+   * See [Send RUM Custom Actions](https://docs.kubesense.ai/real_user_monitoring/guide/send-rum-custom-actions) for further information.
+   *
+   * @category Data Collection
+   * @param error - Error. Favor sending a [Javascript Error](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error) to have a stack trace attached to the error event.
+   * @param context - Context of the error
    */
   addError: (error: unknown, context?: object) => void
 
@@ -171,15 +246,25 @@ export interface RumPublicApi extends PublicApi {
    * Add a custom timing relative to the start of the current view,
    * stored in `@view.custom_timings.<timing_name>`
    *
-   * @category Data Collection
-   * @param name Name of the custom timing
-   * @param [time] Epoch timestamp of the custom timing (if not set, will use current time)
-   *
    * Note: passing a relative time is discouraged since it is actually used as-is but displayed relative to the view start.
    * We currently don't provide a way to retrieve the view start time, so it can be challenging to provide a timing relative to the view start.
+   *
+   * @category Data Collection
+   * @param name - Name of the custom timing
+   * @param [time] - Epoch timestamp of the custom timing (if not set, will use current time)
    */
   addTiming: (name: string, time?: number) => void
 
+  /**
+   * [Experimental] Manually set the current view's loading time.
+   *
+   * Call this method when the view has finished loading. The loading time is computed as the
+   * elapsed time since the view started. Each call replaces any previously set value (last-call-wins).
+   *
+   * @category Data Collection
+   */
+  setViewLoadingTime: () => void
+
   /**
    * Set the global context information to all events, stored in `@context`
    * See [Global context](https://docs.kubesense.ai/real_user_monitoring/browser/advanced_configuration/#global-context) for further information.
@@ -333,7 +418,7 @@ export interface RumPublicApi extends PublicApi {
    *
    * Context - @category Data Collection
    *
-   * @param nameOrOptions - Name or options (name, service, version) for the view
+   * @param nameOrOptions - The view name, or a {@link ViewOptions} object to configure the view
    */
   startView(nameOrOptions?: string | ViewOptions): void
 
@@ -398,54 +483,113 @@ export interface RumPublicApi extends PublicApi {
   /**
    * Start a custom duration vital.
    *
-   * If you plan to have multiple durations for the same vital, you should use the reference returned by this method.
+   * If you plan to have multiple durations for the same vital, use the `vitalKey` option to
+   * differentiate them. Provide the same key when calling `stopDurationVital`.
    *
    * @category Vital - Duration
    * @param name - Name of the custom vital
-   * @param options - Options for the custom vital (context, description)
-   * @returns reference to the custom vital
+   * @param options - Options for the custom vital (vitalKey, context, description)
+   * @example
+   * ```ts
+   * // Simple usage
+   * kubesenseSdk.startDurationVital('my-vital')
+   * kubesenseSdk.stopDurationVital('my-vital')
+   *
+   * // Multiple simultaneous vitals with the same name
+   * const key = crypto.randomUUID()
+   * kubesenseSdk.startDurationVital('my-vital', { vitalKey: key })
+   * kubesenseSdk.stopDurationVital('my-vital', { vitalKey: key })
+   * ```
    */
-  startDurationVital: (name: string, options?: DurationVitalOptions) => DurationVitalReference
+  startDurationVital: (name: string, options?: DurationVitalOptions) => void
 
   /**
    * Stop a custom duration vital
    *
    * @category Vital - Duration
-   * @param nameOrRef - Name or reference of the custom vital
-   * @param options - Options for the custom vital (operationKey, context, description)
+   * @param name - Name of the custom vital
+   * @param options - Options for the custom vital (vitalKey, context, description)
    */
-  stopDurationVital: (nameOrRef: string | DurationVitalReference, options?: DurationVitalOptions) => void
+  stopDurationVital: (name: string, options?: DurationVitalOptions) => void
 
   /**
-   * start a feature operation
+   * Start an operation.
+   *
+   * Call {@link succeedOperation} or {@link failOperation} with the same name (and optional
+   * `operationKey`) to send a RUM vital event marking the end of the operation.
+   *
+   * @category Vital - Operation
+   * @param name - Name of the operation
+   * @param options - Options for the operation (operationKey, context, description)
+   * @example
+   * ```ts
+   * kubesenseSdk.startOperation('checkout')
+   * // ... perform the operation
+   * kubesenseSdk.succeedOperation('checkout')
+   * ```
+   */
+  startOperation: (name: string, options?: OperationOptions) => void
+
+  /**
+   * Mark an operation as successful.
+   *
+   * Sends a RUM vital event marking the end of the operation started with {@link startOperation}.
+   *
+   * @category Vital - Operation
+   * @param name - Name of the operation
+   * @param options - Options for the operation (operationKey, context, description)
+   */
+  succeedOperation: (name: string, options?: OperationOptions) => void
+
+  /**
+   * Mark an operation as failed.
+   *
+   * Sends a RUM vital event marking the end of the operation started with {@link startOperation}.
+   *
+   * @category Vital - Operation
+   * @param name - Name of the operation
+   * @param failureReason - Reason for the failure
+   * @param options - Options for the operation (operationKey, context, description)
+   */
+  failOperation: (name: string, failureReason: FailureReason, options?: OperationOptions) => void
+
+  /**
+   * Start a feature operation.
    *
    * @category Vital - Feature Operation
-   * @param name - Name of the operation step
-   * @param options - Options for the operation step (operationKey, context, description)
-   * @hidden // TODO: replace by @since when GA
+   * @deprecated Use {@link startOperation} instead.
+   * @param name - Name of the operation
+   * @param options - Options for the operation (operationKey, context, description)
    */
   startFeatureOperation: (name: string, options?: FeatureOperationOptions) => void
 
   /**
-   * succeed a feature operation
+   * Mark a feature operation as successful.
    *
    * @category Vital - Feature Operation
-   * @param name - Name of the operation step
-   * @param options - Options for the operation step (operationKey, context, description)
-   * @hidden // TODO: replace by @since when GA
+   * @deprecated Use {@link succeedOperation} instead.
+   * @param name - Name of the operation
+   * @param options - Options for the operation (operationKey, context, description)
    */
   succeedFeatureOperation: (name: string, options?: FeatureOperationOptions) => void
 
   /**
-   * fail a feature operation
+   * Mark a feature operation as failed.
    *
    * @category Vital - Feature Operation
-   * @param name - Name of the operation step
-   * @param failureReason
-   * @param options - Options for the operation step (operationKey, context, description)
-   * @hidden // TODO: replace by @since when GA
+   * @deprecated Use {@link failOperation} instead.
+   * @param name - Name of the operation
+   * @param failureReason - Reason for the failure
+   * @param options - Options for the operation (operationKey, context, description)
+   */
+  failFeatureOperation: (name: string, failureReason: FailureReason, options?: FeatureOperationOptions) => void
+
+  /**
+   * List of default headers used by the {@link RumInitConfiguration.trackResourceHeaders | trackResourceHeaders} option.
+   *
+   * @deprecated You can now omit `name` from a MatchHeader entry to include default headers.
    */
-  failFeatureOperation: (name: string, failureReaon: FailureReason, options?: FeatureOperationOptions) => void
+  DEFAULT_TRACKED_RESOURCE_HEADERS: typeof DEFAULT_TRACKED_RESOURCE_HEADERS
 }
 
 export interface RecorderApi {
@@ -454,7 +598,7 @@ export interface RecorderApi {
   onRumStart: (
     lifeCycle: LifeCycle,
     configuration: RumConfiguration,
-    sessionManager: RumSessionManager,
+    sessionManager: SessionManager,
     viewHistory: ViewHistory,
     deflateWorker: DeflateWorker | undefined,
     telemetry: Telemetry
@@ -470,9 +614,8 @@ export interface ProfilerApi {
     lifeCycle: LifeCycle,
     hooks: Hooks,
     configuration: RumConfiguration,
-    sessionManager: RumSessionManager,
+    sessionManager: SessionManager,
     viewHistory: ViewHistory,
-    longTaskContexts: LongTaskContexts,
     createEncoder: (streamId: DeflateEncoderStreamId) => Encoder
   ) => void
 }
@@ -484,11 +627,7 @@ export interface RumPublicApiOptions {
     source: string,
     onInitializationFailure: () => void
   ) => DeflateWorker | undefined
-  createDeflateEncoder?: (
-    configuration: RumConfiguration,
-    worker: DeflateWorker,
-    streamId: DeflateEncoderStreamId
-  ) => DeflateEncoder
+  createDeflateEncoder?: (worker: DeflateWorker, streamId: DeflateEncoderStreamId) => DeflateEncoder
   sdkName?: SdkName
 }
 
@@ -498,6 +637,7 @@ export interface Strategy {
   getInternalContext: StartRumResult['getInternalContext']
   stopSession: StartRumResult['stopSession']
   addTiming: StartRumResult['addTiming']
+  setLoadingTime: StartRumResult['setLoadingTime']
   startView: StartRumResult['startView']
   setViewName: StartRumResult['setViewName']
 
@@ -510,6 +650,10 @@ export interface Strategy {
   accountContext: ContextManager
 
   addAction: StartRumResult['addAction']
+  startAction: StartRumResult['startAction']
+  stopAction: StartRumResult['stopAction']
+  startResource: StartRumResult['startResource']
+  stopResource: StartRumResult['stopResource']
   addError: StartRumResult['addError']
   addFeatureFlagEvaluation: StartRumResult['addFeatureFlagEvaluation']
   startDurationVital: StartRumResult['startDurationVital']
@@ -519,41 +663,39 @@ export interface Strategy {
 }
 
 export function makeRumPublicApi(
-  startRumImpl: StartRum,
   recorderApi: RecorderApi,
   profilerApi: ProfilerApi,
   options: RumPublicApiOptions = {}
 ): RumPublicApi {
   const trackingConsentState = createTrackingConsentState()
-  const customVitalsState = createCustomVitalsState()
-  const bufferedDataObservable = startBufferingData().observable
+  const bufferedData = startBufferingData()
 
   let strategy = createPreStartStrategy(
     options,
     trackingConsentState,
-    customVitalsState,
-    (configuration, deflateWorker, initialViewOptions) => {
+    (configuration, sessionManager, deflateWorker, initialViewOptions, telemetry, hooks) => {
       const createEncoder =
         deflateWorker && options.createDeflateEncoder
-          ? (streamId: DeflateEncoderStreamId) => options.createDeflateEncoder!(configuration, deflateWorker, streamId)
+          ? (streamId: DeflateEncoderStreamId) => options.createDeflateEncoder!(deflateWorker, streamId)
           : createIdentityEncoder
 
-      const startRumResult = startRumImpl(
+      const startRumResult = mockable(startRum)(
         configuration,
+        sessionManager,
         recorderApi,
         profilerApi,
         initialViewOptions,
         createEncoder,
-        trackingConsentState,
-        customVitalsState,
-        bufferedDataObservable,
+        bufferedData.observable,
+        telemetry,
+        hooks,
         options.sdkName
       )
 
       recorderApi.onRumStart(
         startRumResult.lifeCycle,
         configuration,
-        startRumResult.session,
+        sessionManager,
         startRumResult.viewHistory,
         deflateWorker,
         startRumResult.telemetry
@@ -563,17 +705,16 @@ export function makeRumPublicApi(
         startRumResult.lifeCycle,
         startRumResult.hooks,
         configuration,
-        startRumResult.session,
+        sessionManager,
         startRumResult.viewHistory,
-        startRumResult.longTaskContexts,
         createEncoder
       )
 
       strategy = createPostStartStrategy(strategy, startRumResult)
 
-      callPluginsMethod(configuration.plugins, 'onRumStart', {
-        strategy, // TODO: remove this in the next major release
+      callPluginsOnRumStart(configuration.plugins, {
         addEvent: startRumResult.addEvent,
+        addError: startRumResult.addError,
       })
 
       return startRumResult
@@ -584,10 +725,37 @@ export function makeRumPublicApi(
   const startView: {
     (name?: string): void
     (options: ViewOptions): void
-  } = monitor((options?: string | ViewOptions) => {
-    const sanitizedOptions = typeof options === 'object' ? options : { name: options }
-    strategy.startView(sanitizedOptions)
-    addTelemetryUsage({ feature: 'start-view' })
+  } = (options?: string | ViewOptions) => {
+    const handlingStack = createHandlingStack('view')
+    callMonitored(() => {
+      const sanitizedOptions = typeof options === 'object' ? options : { name: options }
+      strategy.startView({
+        ...sanitizedOptions,
+        name: sanitizeStringOption(sanitizedOptions.name, 'view name'),
+        service: sanitizeStringOption(sanitizedOptions.service, 'view service'),
+        version: sanitizeStringOption(sanitizedOptions.version, 'view version'),
+        handlingStack,
+      })
+      addTelemetryUsage({ feature: 'start-view' })
+    })
+  }
+
+  const startOperation: RumPublicApi['startOperation'] = (name, options) => {
+    const handlingStack = createHandlingStack('vital')
+    callMonitored(() => {
+      addTelemetryUsage({ feature: 'add-operation-step-vital', action_type: 'start' })
+      strategy.addOperationStepVital(name, 'start', { ...options, handlingStack })
+    })
+  }
+
+  const succeedOperation: RumPublicApi['succeedOperation'] = monitor((name, options) => {
+    addTelemetryUsage({ feature: 'add-operation-step-vital', action_type: 'succeed' })
+    strategy.addOperationStepVital(name, 'end', options)
+  })
+
+  const failOperation: RumPublicApi['failOperation'] = monitor((name, failureReason, options) => {
+    addTelemetryUsage({ feature: 'add-operation-step-vital', action_type: 'fail' })
+    strategy.addOperationStepVital(name, 'end', options, failureReason)
   })
 
   const rumPublicApi: RumPublicApi = makePublicApi<RumPublicApi>({
@@ -602,7 +770,7 @@ export function makeRumPublicApi(
     }),
 
     setViewName: monitor((name: string) => {
-      strategy.setViewName(name)
+      strategy.setViewName(sanitizeStringOption(name, 'view name')!)
       addTelemetryUsage({ feature: 'set-view-name' })
     }),
 
@@ -640,6 +808,45 @@ export function makeRumPublicApi(
       })
     },
 
+    startAction: monitor((name, options) => {
+      addTelemetryUsage({ feature: 'start-action' })
+      strategy.startAction(sanitize(name)!, {
+        type: sanitize(options?.type) as ActionType | undefined,
+        context: sanitize(options?.context) as Context,
+        actionKey: options?.actionKey,
+      })
+    }),
+
+    stopAction: monitor((name, options) => {
+      addTelemetryUsage({ feature: 'stop-action' })
+      strategy.stopAction(sanitize(name)!, {
+        type: sanitize(options?.type) as ActionType | undefined,
+        context: sanitize(options?.context) as Context,
+        actionKey: options?.actionKey,
+      })
+    }),
+
+    startResource: monitor((url, options) => {
+      addTelemetryUsage({ feature: 'start-resource' })
+      strategy.startResource(sanitize(url)!, {
+        type: sanitize(options?.type) as ResourceType | undefined,
+        method: sanitize(options?.method) as string | undefined,
+        context: sanitize(options?.context) as Context,
+        resourceKey: options?.resourceKey,
+      })
+    }),
+
+    stopResource: monitor((url, options) => {
+      addTelemetryUsage({ feature: 'stop-resource' })
+      strategy.stopResource(sanitize(url)!, {
+        type: sanitize(options?.type) as ResourceType | undefined,
+        statusCode: options?.statusCode,
+        size: options?.size,
+        context: sanitize(options?.context) as Context,
+        resourceKey: options?.resourceKey,
+      })
+    }),
+
     addError: (error, context) => {
       const handlingStack = createHandlingStack('error')
       callMonitored(() => {
@@ -658,6 +865,14 @@ export function makeRumPublicApi(
       strategy.addTiming(sanitize(name)!, time as RelativeTime | TimeStamp | undefined)
     }),
 
+    setViewLoadingTime: monitor(() => {
+      const callTimestamp = timeStampNow()
+      strategy.setLoadingTime(callTimestamp)
+      addTelemetryUsage({
+        feature: 'addViewLoadingTime',
+      })
+    }),
+
     setGlobalContext: defineContextMethod(
       getStrategy,
       CustomerContextKey.globalContext,
@@ -767,64 +982,88 @@ export function makeRumPublicApi(
 
     startSessionReplayRecording: monitor((options?: StartRecordingOptions) => {
       recorderApi.start(options)
-      addTelemetryUsage({ feature: 'start-session-replay-recording', force: options && options.force })
+      addTelemetryUsage({ feature: 'start-session-replay-recording', force: options?.force })
     }),
 
     stopSessionReplayRecording: monitor(() => recorderApi.stop()),
 
-    addDurationVital: monitor((name, options) => {
-      addTelemetryUsage({ feature: 'add-duration-vital' })
-      strategy.addDurationVital({
-        name: sanitize(name)!,
-        type: VitalType.DURATION,
-        startClocks: timeStampToClocks(options.startTime as TimeStamp),
-        duration: options.duration as Duration,
-        context: sanitize(options && options.context) as Context,
-        description: sanitize(options && options.description) as string | undefined,
+    addDurationVital: (name, options) => {
+      const handlingStack = createHandlingStack('vital')
+      callMonitored(() => {
+        addTelemetryUsage({ feature: 'add-duration-vital' })
+        strategy.addDurationVital({
+          id: generateUUID(),
+          name: sanitize(name)!,
+          type: VitalType.DURATION,
+          startClocks: timeStampToClocks(options.startTime as TimeStamp),
+          duration: options.duration as Duration,
+          context: sanitize(options?.context) as Context,
+          description: sanitize(options?.description) as string | undefined,
+          handlingStack,
+        })
       })
-    }),
+    },
 
-    startDurationVital: monitor((name, options) => {
-      addTelemetryUsage({ feature: 'start-duration-vital' })
-      return strategy.startDurationVital(sanitize(name)!, {
-        context: sanitize(options && options.context) as Context,
-        description: sanitize(options && options.description) as string | undefined,
+    startDurationVital: (name, options) => {
+      const handlingStack = createHandlingStack('vital')
+      callMonitored(() => {
+        addTelemetryUsage({ feature: 'start-duration-vital' })
+        strategy.startDurationVital(sanitize(name)!, {
+          vitalKey: options?.vitalKey,
+          context: sanitize(options?.context) as Context,
+          description: sanitize(options?.description) as string | undefined,
+          handlingStack,
+        })
       })
-    }),
+    },
 
-    stopDurationVital: monitor((nameOrRef, options) => {
+    stopDurationVital: monitor((name, options) => {
       addTelemetryUsage({ feature: 'stop-duration-vital' })
-      strategy.stopDurationVital(typeof nameOrRef === 'string' ? sanitize(nameOrRef)! : nameOrRef, {
-        context: sanitize(options && options.context) as Context,
-        description: sanitize(options && options.description) as string | undefined,
+      strategy.stopDurationVital(sanitize(name)!, {
+        vitalKey: options?.vitalKey,
+        context: sanitize(options?.context) as Context,
+        description: sanitize(options?.description) as string | undefined,
       })
     }),
 
-    startFeatureOperation: monitor((name, options) => {
-      addTelemetryUsage({ feature: 'add-operation-step-vital', action_type: 'start' })
-      strategy.addOperationStepVital(name, 'start', options)
-    }),
+    startOperation,
+    succeedOperation,
+    failOperation,
 
-    succeedFeatureOperation: monitor((name, options) => {
-      addTelemetryUsage({ feature: 'add-operation-step-vital', action_type: 'succeed' })
-      strategy.addOperationStepVital(name, 'end', options)
-    }),
+    // Deprecated aliases — kept for backwards compatibility, forward to the renamed APIs above.
+    // TODO: remove in the next major version (RUM-16921).
+    startFeatureOperation: startOperation,
+    succeedFeatureOperation: succeedOperation,
+    failFeatureOperation: failOperation,
 
-    failFeatureOperation: monitor((name, failureReason, options) => {
-      addTelemetryUsage({ feature: 'add-operation-step-vital', action_type: 'fail' })
-      strategy.addOperationStepVital(name, 'end', options, failureReason)
-    }),
+    DEFAULT_TRACKED_RESOURCE_HEADERS,
   })
 
   return rumPublicApi
 }
 
+function sanitizeStringOption(value: unknown, label: string): string | undefined {
+  if (value === undefined) {
+    return undefined
+  }
+  if (typeof value !== 'string') {
+    display.warn(`Invalid ${label} provided (expected a string, got ${typeof value}). Ignoring.`)
+    return undefined
+  }
+  return sanitize(value)
+}
+
 function createPostStartStrategy(preStartStrategy: Strategy, startRumResult: StartRumResult): Strategy {
   return {
+    ...preStartStrategy,
     init: (initConfiguration: RumInitConfiguration) => {
       displayAlreadyInitializedError('KUBESENSE_SDK', initConfiguration)
     },
-    initConfiguration: preStartStrategy.initConfiguration,
-    ...startRumResult,
+    getInternalContext: startRumResult.getInternalContext,
+    stopSession: startRumResult.stopSession,
+    getViewContext: startRumResult.getViewContext,
+    globalContext: startRumResult.globalContext,
+    userContext: startRumResult.userContext,
+    accountContext: startRumResult.accountContext,
   }
 }