✨ [RUM-3837] Force Replay recording on sampled-out sessions

packages/core/src/domain/session/sessionManager.spec.ts

@@ -630,6 +630,16 @@ describe('startSessionManager', () => {
     })
   })
 
+  describe('forced replay', () => {
+    it('should update current entity when replay recording is forced', () => {
+      const sessionManager = startSessionManagerWithDefaults()
+      sessionManager.setForcedReplay()
+
+      expectSessionIdToBeDefined(sessionManager)
+      expect(sessionManager.findSession()!.isReplayForced).toBe(true)
+    })
+  })
+
   function startSessionManagerWithDefaults({
     configuration,
     productKey = FIRST_PRODUCT_KEY,

packages/core/src/domain/session/sessionManager.ts

@@ -18,11 +18,13 @@ export interface SessionManager<TrackingType extends string> {
   renewObservable: Observable<void>
   expireObservable: Observable<void>
   expire: () => void
+  setForcedReplay: () => void
 }
 
 export interface SessionContext<TrackingType extends string> extends Context {
   id: string
   trackingType: TrackingType
+  isReplayForced: boolean
 }
 
 export const VISIBILITY_CHECK_DELAY = ONE_MINUTE
@@ -53,6 +55,12 @@ export function startSessionManager<TrackingType extends string>(
     expireObservable.notify()
     sessionContextHistory.closeActive(relativeNow())
   })
+  sessionStore.forceReplayObservable.subscribe(() => {
+    const sessionEntity = sessionContextHistory.find()
+    if (sessionEntity) {
+      sessionEntity.isReplayForced = true
+    }
+  })
 
   // We expand/renew session unconditionally as tracking consent is always granted when the session
   // manager is started.
@@ -79,6 +87,7 @@ export function startSessionManager<TrackingType extends string>(
     return {
       id: sessionStore.getSession().id!,
       trackingType: sessionStore.getSession()[productKey] as TrackingType,
+      isReplayForced: !!sessionStore.getSession().forcedReplay,
     }
   }
 
@@ -87,6 +96,7 @@ export function startSessionManager<TrackingType extends string>(
     renewObservable,
     expireObservable,
     expire: sessionStore.expire,
+    setForcedReplay: sessionStore.setForcedReplay,
   }
 }
 

packages/core/src/domain/session/sessionStore.spec.ts

@@ -472,4 +472,60 @@ describe('session store', () => {
       })
     })
   })
+
+  describe('session update and synchronisation', () => {
+    let updateSpy: () => void
+    let otherUpdateSpy: () => void
+    let clock: Clock
+
+    function setupSessionStore(updateSpy: () => void) {
+      const computeSessionState: (rawTrackingType?: string) => {
+        trackingType: FakeTrackingType
+        isTracked: boolean
+      } = () => ({
+        isTracked: true,
+        trackingType: FakeTrackingType.TRACKED,
+      })
+      const sessionStoreStrategyType = selectSessionStoreStrategyType({
+        clientToken: 'abc',
+        allowFallbackToLocalStorage: false,
+      })
+
+      const sessionStoreManager = startSessionStore(sessionStoreStrategyType!, PRODUCT_KEY, computeSessionState)
+      sessionStoreManager.forceReplayObservable.subscribe(updateSpy)
+
+      return sessionStoreManager
+    }
+
+    let sessionStoreManager: SessionStore
+    let otherSessionStoreManager: SessionStore
+
+    beforeEach(() => {
+      updateSpy = jasmine.createSpy()
+      otherUpdateSpy = jasmine.createSpy()
+      clock = mockClock()
+    })
+
+    afterEach(() => {
+      resetSessionInStore()
+      clock.cleanup()
+      sessionStoreManager.stop()
+      otherSessionStoreManager.stop()
+    })
+
+    it('should synchronise all stores and notify update observables of all stores', () => {
+      setSessionInStore(FakeTrackingType.TRACKED, FIRST_ID)
+
+      sessionStoreManager = setupSessionStore(updateSpy)
+      otherSessionStoreManager = setupSessionStore(otherUpdateSpy)
+
+      sessionStoreManager.setForcedReplay()
+
+      expect(updateSpy).toHaveBeenCalled()
+
+      // Need to wait until watch is triggered
+      clock.tick(STORAGE_POLL_DELAY)
+      expect(otherUpdateSpy).toHaveBeenCalled()
+    })
+  })
 })

packages/core/src/domain/session/sessionStore.ts

@@ -4,6 +4,7 @@ import { ONE_SECOND, dateNow } from '../../tools/utils/timeUtils'
 import { throttle } from '../../tools/utils/functionUtils'
 import { generateUUID } from '../../tools/utils/stringUtils'
 import type { InitConfiguration } from '../configuration'
+import { assign } from '../../tools/utils/polyfills'
 import { selectCookieStrategy, initCookieStrategy } from './storeStrategies/sessionInCookie'
 import type { SessionStoreStrategyType } from './storeStrategies/sessionStoreStrategy'
 import {
@@ -23,8 +24,10 @@ export interface SessionStore {
   restartSession: () => void
   renewObservable: Observable<void>
   expireObservable: Observable<void>
+  forceReplayObservable: Observable<void>
   expire: () => void
   stop: () => void
+  setForcedReplay: () => void
 }
 
 /**
@@ -61,6 +64,7 @@ export function startSessionStore<TrackingType extends string>(
 ): SessionStore {
   const renewObservable = new Observable<void>()
   const expireObservable = new Observable<void>()
+  const forceReplayObservable = new Observable<void>()
 
   const sessionStoreStrategy =
     sessionStoreStrategyType.type === 'Cookie'
@@ -128,6 +132,9 @@ export function startSessionStore<TrackingType extends string>(
       if (isSessionInCacheOutdated(sessionState)) {
         expireSessionInCache()
       } else {
+        if (sessionState.forcedReplay && !sessionCache.forcedReplay) {
+          forceReplayObservable.notify()
+        }
         sessionCache = sessionState
       }
     }
@@ -182,12 +189,23 @@ export function startSessionStore<TrackingType extends string>(
     renewObservable.notify()
   }
 
+  function setForcedReplay() {
+    processSessionStoreOperations(
+      {
+        process: (sessionState) => assign({}, sessionState, { forcedReplay: '1' }),
+        after: synchronizeSession,
+      },
+      sessionStoreStrategy
+    )
+  }
+
   return {
     expandOrRenewSession: throttledExpandOrRenewSession,
     expandSession,
     getSession: () => sessionCache,
     renewObservable,
     expireObservable,
+    forceReplayObservable,
     restartSession: startSession,
     expire: () => {
       cancelExpandOrRenewSession()
@@ -197,5 +215,6 @@ export function startSessionStore<TrackingType extends string>(
     stop: () => {
       clearInterval(watchSessionTimeoutId)
     },
+    setForcedReplay,
   }
 }

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

@@ -45,6 +45,9 @@ import type { InternalContext } from '../domain/contexts/internalContext'
 import { createPreStartStrategy } from './preStartRum'
 import type { StartRum, StartRumResult } from './startRum'
 
+export interface StartRecordingOptions {
+  force: boolean
+}
 export interface RumPublicApi extends PublicApi {
   /**
    * Init the RUM browser SDK.
@@ -234,7 +237,7 @@ export interface RumPublicApi extends PublicApi {
    *
    * See [Browser Session Replay](https://docs.datadoghq.com/real_user_monitoring/session_replay/browser) for further information.
    */
-  startSessionReplayRecording: () => void
+  startSessionReplayRecording: (options?: StartRecordingOptions) => void
 
   /**
    * Stop Session Replay recording.
@@ -245,7 +248,7 @@ export interface RumPublicApi extends PublicApi {
 }
 
 export interface RecorderApi {
-  start: () => void
+  start: (options?: StartRecordingOptions) => void
   stop: () => void
   onRumStart: (
     lifeCycle: LifeCycle,
@@ -482,10 +485,9 @@ export function makeRumPublicApi(
     }),
 
     getSessionReplayLink: monitor(() => recorderApi.getSessionReplayLink()),
-
-    startSessionReplayRecording: monitor(() => {
-      recorderApi.start()
-      addTelemetryUsage({ feature: 'start-session-replay-recording' })
+    startSessionReplayRecording: monitor((options?: StartRecordingOptions) => {
+      recorderApi.start(options)
+      addTelemetryUsage({ feature: 'start-session-replay-recording', force: options?.force })
     }),
 
     stopSessionReplayRecording: monitor(() => recorderApi.stop()),

packages/rum-core/src/domain/assembly.ts

@@ -178,7 +178,7 @@ export function startRumAssembly(
           ;(serverRumEvent.session as Mutable<RumEvent['session']>).has_replay = commonContext.hasReplay
         }
         if (serverRumEvent.type === 'view') {
-          ;(serverRumEvent.session as Mutable<RumEvent['session']>).sampled_for_replay = session.sessionReplayAllowed
+          ;(serverRumEvent.session as Mutable<RumEvent['session']>).sampled_for_replay = session.sampledForReplay
         }
 
         if (!isEmptyObject(commonContext.user)) {

packages/rum-core/src/domain/rumSessionManager.ts

@@ -17,10 +17,12 @@ export interface RumSessionManager {
   findTrackedSession: (startTime?: RelativeTime) => RumSession | undefined
   expire: () => void
   expireObservable: Observable<void>
+  setForcedReplay: () => void
 }
 
 export type RumSession = {
   id: string
+  sampledForReplay: boolean
   sessionReplayAllowed: boolean
 }
 
@@ -58,11 +60,14 @@ export function startRumSessionManager(
       }
       return {
         id: session.id,
-        sessionReplayAllowed: session.trackingType === RumTrackingType.TRACKED_WITH_SESSION_REPLAY,
+        sampledForReplay: session.trackingType === RumTrackingType.TRACKED_WITH_SESSION_REPLAY,
+        sessionReplayAllowed:
+          session.trackingType === RumTrackingType.TRACKED_WITH_SESSION_REPLAY || session.isReplayForced,
       }
     },
     expire: sessionManager.expire,
     expireObservable: sessionManager.expireObservable,
+    setForcedReplay: sessionManager.setForcedReplay,
   }
 }
 
@@ -72,12 +77,14 @@ export function startRumSessionManager(
 export function startRumSessionManagerStub(): RumSessionManager {
   const session: RumSession = {
     id: '00000000-aaaa-0000-aaaa-000000000000',
+    sampledForReplay: bridgeSupports(BridgeCapability.RECORDS),
     sessionReplayAllowed: bridgeSupports(BridgeCapability.RECORDS),
   }
   return {
     findTrackedSession: () => session,
     expire: noop,
     expireObservable: new Observable(),
+    setForcedReplay: noop,
   }
 }
 

packages/rum-core/src/index.ts

@@ -1,4 +1,4 @@
-export { RumPublicApi, makeRumPublicApi, RecorderApi } from './boot/rumPublicApi'
+export { RumPublicApi, makeRumPublicApi, RecorderApi, StartRecordingOptions } from './boot/rumPublicApi'
 export { StartRum } from './boot/startRum'
 export {
   RumEvent,

packages/rum-core/test/mockRumSessionManager.ts

@@ -29,6 +29,7 @@ export function createRumSessionManagerMock(): RumSessionManagerMock {
       }
       return {
         id,
+        sampledForReplay: sessionStatus === SessionStatus.TRACKED_WITH_SESSION_REPLAY,
         sessionReplayAllowed: sessionStatus === SessionStatus.TRACKED_WITH_SESSION_REPLAY,
       }
     },
@@ -53,5 +54,6 @@ export function createRumSessionManagerMock(): RumSessionManagerMock {
       sessionStatus = SessionStatus.TRACKED_WITH_SESSION_REPLAY
       return this
     },
+    setForcedReplay() {},
   }
 }

packages/rum/src/boot/recorderApi.spec.ts

@@ -135,6 +135,13 @@ describe('makeRecorderApi', () => {
       expect(startRecordingSpy).not.toHaveBeenCalled()
     })
 
+    it('should start recording if session is tracked without session replay when forced', () => {
+      setupBuilder.withSessionManager(createRumSessionManagerMock().setTrackedWithoutSessionReplay()).build()
+      rumInit()
+      recorderApi.start({ force: true })
+      expect(startRecordingSpy).toHaveBeenCalledTimes(1)
+    })
+
     it('uses the previously created worker if available', () => {
       setupBuilder.build()
       rumInit({ worker: mockWorker })

packages/rum/src/boot/recorderApi.ts

@@ -14,6 +14,7 @@ import type {
   RumSessionManager,
   RecorderApi,
   RumConfiguration,
+  StartRecordingOptions,
 } from '@datadog/browser-rum-core'
 import { LifeCycleEventType } from '@datadog/browser-rum-core'
 import { getReplayStats as getReplayStatsImpl } from '../domain/replayStats'
@@ -57,6 +58,8 @@ type RecorderState =
       stopRecording: () => void
     }
 
+type StartStrategyFn = (options?: StartRecordingOptions) => void
+
 export function makeRecorderApi(
   startRecordingImpl: StartRecording,
   createDeflateWorkerImpl?: CreateDeflateWorker
@@ -76,7 +79,7 @@ export function makeRecorderApi(
     status: RecorderStatus.IntentToStart,
   }
 
-  let startStrategy = () => {
+  let startStrategy: StartStrategyFn = () => {
     state = { status: RecorderStatus.IntentToStart }
   }
   let stopStrategy = () => {
@@ -85,7 +88,7 @@ export function makeRecorderApi(
   let getSessionReplayLinkStrategy = noop as () => string | undefined
 
   return {
-    start: () => startStrategy(),
+    start: (options?: StartRecordingOptions) => startStrategy(options),
     stop: () => stopStrategy(),
     getSessionReplayLink: () => getSessionReplayLinkStrategy(),
     onRumStart: (
@@ -139,9 +142,9 @@ export function makeRecorderApi(
         return cachedDeflateEncoder
       }
 
-      startStrategy = () => {
+      startStrategy = (options?: StartRecordingOptions) => {
         const session = sessionManager.findTrackedSession()
-        if (!session || !session.sessionReplayAllowed) {
+        if (!session || (!session.sessionReplayAllowed && !options?.force)) {
           state = { status: RecorderStatus.IntentToStart }
           return
         }
@@ -177,6 +180,10 @@ export function makeRecorderApi(
             stopRecording,
           }
         })
+
+        if (options?.force && !session.sessionReplayAllowed) {
+          sessionManager.setForcedReplay()
+        }
       }
 
       stopStrategy = () => {