[RUM-14619] Add addViewLoadingTime() public API

.gitignore

@@ -31,3 +31,4 @@ playwright-report/
 # Claude Code local files
 *.local.md
 .claude/settings.local.json
+.planning/

packages/core/src/domain/telemetry/telemetryEvent.types.ts

@@ -532,11 +532,13 @@ export type TelemetryCommonFeaturesUsage =
 /**
  * Schema of browser specific features usage
  */
+// [MANUAL] AddViewLoadingTime added pending upstream rum-events-format schema sync
 export type TelemetryBrowserFeaturesUsage =
   | StartSessionReplayRecording
   | StartDurationVital
   | StopDurationVital
   | AddDurationVital
+  | AddViewLoadingTime
 /**
  * Schema of mobile specific features usage
  */

packages/rum-core/src/boot/preStartRum.spec.ts

@@ -607,6 +607,33 @@ describe('preStartRum', () => {
       expect(addTimingSpy).toHaveBeenCalledOnceWith(name, time)
     })
 
+    it('addLoadingTime', () => {
+      const addLoadingTimeSpy = jasmine.createSpy()
+      doStartRumSpy.and.returnValue({ addLoadingTime: addLoadingTimeSpy } as unknown as StartRumResult)
+
+      const timestamp = 123 as TimeStamp
+      strategy.addLoadingTime(timestamp, false)
+      strategy.init(DEFAULT_INIT_CONFIGURATION, PUBLIC_API)
+      expect(addLoadingTimeSpy).toHaveBeenCalledOnceWith(timestamp, false)
+    })
+
+    it('addLoadingTime should preserve call timestamp', () => {
+      const clock = mockClock()
+      const addLoadingTimeSpy = jasmine.createSpy()
+      doStartRumSpy.and.returnValue({ addLoadingTime: addLoadingTimeSpy } as unknown as StartRumResult)
+
+      clock.tick(10)
+      strategy.addLoadingTime()
+
+      clock.tick(20)
+      strategy.init(DEFAULT_INIT_CONFIGURATION, PUBLIC_API)
+
+      expect(addLoadingTimeSpy).toHaveBeenCalledOnceWith(jasmine.any(Number), false)
+      // Verify the timestamp was captured at call time (tick 10), not at drain time (tick 30)
+      const capturedTimestamp = addLoadingTimeSpy.calls.argsFor(0)[0] as number
+      expect(capturedTimestamp).toBeLessThan(clock.timeStamp(30))
+    })
+
     it('setViewContext', () => {
       const setViewContextSpy = jasmine.createSpy()
       doStartRumSpy.and.returnValue({ setViewContext: setViewContextSpy } as unknown as StartRumResult)

packages/rum-core/src/boot/preStartRum.ts

@@ -241,6 +241,10 @@ export function createPreStartStrategy(
       bufferApiCalls.add((startRumResult) => startRumResult.addTiming(name, time))
     },
 
+    addLoadingTime: ((callTimestamp = timeStampNow(), overwrite = false) => {
+      bufferApiCalls.add((startRumResult) => startRumResult.addLoadingTime(callTimestamp, overwrite))
+    }) as Strategy['addLoadingTime'],
+
     startView(options, startClocks = clocksNow()) {
       const callback = (startRumResult: StartRumResult) => {
         startRumResult.startView(options, startClocks)

packages/rum-core/src/boot/rumPublicApi.spec.ts

@@ -14,6 +14,7 @@ const noopStartRum = (): ReturnType<StartRum> => ({
   addError: () => undefined,
   addEvent: () => undefined,
   addTiming: () => undefined,
+  addLoadingTime: () => ({ noActiveView: false, overwritten: false }),
   addFeatureFlagEvaluation: () => undefined,
   startView: () => undefined,
   setViewContext: () => undefined,
@@ -544,6 +545,42 @@ describe('rum public api', () => {
     })
   })
 
+  describe('addViewLoadingTime', () => {
+    let addLoadingTimeSpy: jasmine.Spy<ReturnType<StartRum>['addLoadingTime']>
+    let rumPublicApi: RumPublicApi
+
+    beforeEach(() => {
+      addLoadingTimeSpy = jasmine.createSpy()
+      ;({ rumPublicApi } = makeRumPublicApiWithDefaults({
+        startRumResult: {
+          addLoadingTime: addLoadingTimeSpy,
+        },
+      }))
+    })
+
+    it('should call addLoadingTime with timestamp and no overwrite by default', () => {
+      rumPublicApi.init(DEFAULT_INIT_CONFIGURATION)
+
+      rumPublicApi.addViewLoadingTime()
+
+      expect(addLoadingTimeSpy).toHaveBeenCalledOnceWith(jasmine.any(Number), false)
+    })
+
+    it('should pass overwrite true when specified', () => {
+      rumPublicApi.init(DEFAULT_INIT_CONFIGURATION)
+
+      rumPublicApi.addViewLoadingTime({ overwrite: true })
+
+      expect(addLoadingTimeSpy).toHaveBeenCalledOnceWith(jasmine.any(Number), true)
+    })
+
+    it('should not throw when called before init', () => {
+      expect(() => rumPublicApi.addViewLoadingTime()).not.toThrow()
+
+      expect(addLoadingTimeSpy).not.toHaveBeenCalled()
+    })
+  })
+
   describe('addFeatureFlagEvaluation', () => {
     let addFeatureFlagEvaluationSpy: jasmine.Spy<ReturnType<StartRum>['addFeatureFlagEvaluation']>
     let displaySpy: jasmine.Spy<() => void>

packages/rum-core/src/boot/rumPublicApi.ts

@@ -35,6 +35,7 @@ import {
   startBufferingData,
   isExperimentalFeatureEnabled,
   ExperimentalFeature,
+  timeStampNow,
 } from '@datadog/browser-core'
 
 import type { LifeCycle } from '../domain/lifeCycle'
@@ -215,6 +216,18 @@ export interface RumPublicApi extends PublicApi {
    */
   addTiming: (name: string, time?: number) => void
 
+  /**
+   * 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. By default, the first call sets the loading time and
+   * subsequent calls are no-ops. Use `{ overwrite: true }` to replace a previously set value.
+   *
+   * @category Data Collection
+   * @param options - Options. Set `overwrite: true` to replace a previously set loading time.
+   */
+  addViewLoadingTime: (options?: { overwrite?: boolean }) => void
+
   /**
    * Set the global context information to all events, stored in `@context`
    * See [Global context](https://docs.datadoghq.com/real_user_monitoring/browser/advanced_configuration/#global-context) for further information.
@@ -533,6 +546,7 @@ export interface Strategy {
   getInternalContext: StartRumResult['getInternalContext']
   stopSession: StartRumResult['stopSession']
   addTiming: StartRumResult['addTiming']
+  addLoadingTime: StartRumResult['addLoadingTime']
   startView: StartRumResult['startView']
   setViewName: StartRumResult['setViewName']
 
@@ -727,6 +741,17 @@ export function makeRumPublicApi(
       strategy.addTiming(sanitize(name)!, time as RelativeTime | TimeStamp | undefined)
     }),
 
+    addViewLoadingTime: monitor((options?: { overwrite?: boolean }) => {
+      const callTimestamp = timeStampNow()
+      const result = strategy.addLoadingTime(callTimestamp, options?.overwrite ?? false)
+      addTelemetryUsage({
+        feature: 'addViewLoadingTime',
+        no_view: false,
+        no_active_view: result?.noActiveView ?? false,
+        overwritten: result?.overwritten ?? false,
+      })
+    }),
+
     setGlobalContext: defineContextMethod(
       getStrategy,
       CustomerContextKey.globalContext,

packages/rum-core/src/boot/startRum.ts

@@ -202,6 +202,7 @@ export function startRumEventCollection(
 
   const {
     addTiming,
+    addLoadingTime,
     startView,
     setViewName,
     setViewContext,
@@ -252,6 +253,7 @@ export function startRumEventCollection(
     addEvent: eventCollection.addEvent,
     addError,
     addTiming,
+    addLoadingTime,
     addFeatureFlagEvaluation: featureFlagContexts.addFeatureFlagEvaluation,
     startView,
     setViewContext,

packages/rum-core/src/domain/view/setupViewTest.specHelper.ts

@@ -45,7 +45,7 @@ export function setupViewTest(
   } = spyOnViews<ViewEndedEvent>()
   lifeCycle.subscribe(LifeCycleEventType.VIEW_ENDED, viewEndHandler)
 
-  const { stop, startView, setViewName, setViewContext, setViewContextProperty, getViewContext, addTiming } =
+  const { stop, startView, setViewName, setViewContext, setViewContextProperty, getViewContext, addTiming, addLoadingTime } =
     trackViews(
       fakeLocation,
       lifeCycle,
@@ -65,6 +65,7 @@ export function setupViewTest(
     changeLocation,
     setViewName,
     addTiming,
+    addLoadingTime,
     getViewUpdate,
     getViewUpdateCount,
     getViewCreate,