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

developer-extension/src/panel/components/tabs/infosTab.tsx

@@ -45,6 +45,7 @@ export function InfosTab() {
                   )
                 }
               />
+              {infos.cookie.forcedReplay && <Entry name="Is Replay Forced" value={'True'} />}
               <Entry name="Created" value={infos.cookie.created && formatDate(Number(infos.cookie.created))} />
               <Entry name="Expire" value={infos.cookie.expire && formatDate(Number(infos.cookie.expire))} />
               <Button color="violet" variant="light" onClick={endSession} className="dd-privacy-allow">

developer-extension/src/panel/components/tabs/replayTab.tsx

@@ -25,14 +25,14 @@ export function ReplayTab() {
     return <Alert level="error" message="RUM session sampled out." />
   }
 
-  if (infos.cookie.rum === '2') {
+  if (infos.cookie.rum === '2' && infos.cookie.forcedReplay !== '1') {
     return <Alert level="error" message="RUM session plan does not include replay." />
   }
 
-  return <Player />
+  return <Player isReplayForced={infos.cookie.forcedReplay === '1'} />
 }
 
-function Player() {
+function Player({ isReplayForced }: { isReplayForced: boolean }) {
   const frameRef = useRef<HTMLIFrameElement | null>(null)
   const [playerStatus, setPlayerStatus] = useState<SessionReplayPlayerStatus>('loading')
 
@@ -43,30 +43,31 @@ function Player() {
   return (
     <TabBase>
       <iframe ref={frameRef} className={classes.iframe} data-status={playerStatus} />
-      {playerStatus === 'waiting-for-full-snapshot' && <WaitingForFullSnapshot />}
+      {playerStatus === 'waiting-for-full-snapshot' && <WaitingForFullSnapshot isReplayForced={isReplayForced} />}
     </TabBase>
   )
 }
 
-function WaitingForFullSnapshot() {
+function WaitingForFullSnapshot({ isReplayForced }: { isReplayForced: boolean }) {
   return (
     <Alert
       level="warning"
       message="Waiting for a full snapshot to be generated..."
       button={
-        <Button onClick={generateFullSnapshot} color="orange">
+        <Button onClick={() => generateFullSnapshot(isReplayForced)} color="orange">
           Generate Full Snapshot
         </Button>
       }
     />
   )
 }
 
-function generateFullSnapshot() {
+function generateFullSnapshot(isReplayForced: boolean) {
   // Restart to make sure we have a fresh Full Snapshot
+  const startParam = isReplayForced ? '{ force: true }' : ''
   evalInWindow(`
     DD_RUM.stopSessionReplayRecording()
-    DD_RUM.startSessionReplayRecording()
+    DD_RUM.startSessionReplayRecording(${startParam})
   `).catch((error) => {
     logger.error('While restarting recording:', error)
   })

developer-extension/src/panel/hooks/useSdkInfos.ts

@@ -26,6 +26,7 @@ export interface SdkInfos {
     expire?: string
     logs?: string
     rum?: string
+    forcedReplay?: '1'
   }
 }
 

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 })