✨ [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,7 +25,7 @@ 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." />
   }
 
@@ -66,7 +66,7 @@ function generateFullSnapshot() {
   // Restart to make sure we have a fresh Full Snapshot
   evalInWindow(`
     DD_RUM.stopSessionReplayRecording()
-    DD_RUM.startSessionReplayRecording()
+    DD_RUM.startSessionReplayRecording({ force: true })
   `).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,23 @@ describe('startSessionManager', () => {
     })
   })
 
+  describe('session state update', () => {
+    it('should notify session manager update observable', () => {
+      const sessionStateUpdateSpy = jasmine.createSpy()
+      const sessionManager = startSessionManagerWithDefaults()
+      sessionManager.sessionStateUpdateObservable.subscribe(sessionStateUpdateSpy)
+
+      sessionManager.updateSessionState({ extra: 'extra' })
+
+      expectSessionIdToBeDefined(sessionManager)
+      expect(sessionStateUpdateSpy).toHaveBeenCalledTimes(1)
+
+      const callArgs = sessionStateUpdateSpy.calls.argsFor(0)[0]
+      expect(callArgs.previousState.extra).toBeUndefined()
+      expect(callArgs.newState.extra).toBe('extra')
+    })
+  })
+
   function startSessionManagerWithDefaults({
     configuration,
     productKey = FIRST_PRODUCT_KEY,

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

@@ -9,6 +9,7 @@ import type { Configuration } from '../configuration'
 import type { TrackingConsentState } from '../trackingConsent'
 import { SESSION_TIME_OUT_DELAY } from './sessionConstants'
 import { startSessionStore } from './sessionStore'
+import type { SessionState } from './sessionState'
 
 export interface SessionManager<TrackingType extends string> {
   findSession: (
@@ -17,12 +18,15 @@ export interface SessionManager<TrackingType extends string> {
   ) => SessionContext<TrackingType> | undefined
   renewObservable: Observable<void>
   expireObservable: Observable<void>
+  sessionStateUpdateObservable: Observable<{ previousState: SessionState; newState: SessionState }>
   expire: () => void
+  updateSessionState: (state: Partial<SessionState>) => void
 }
 
 export interface SessionContext<TrackingType extends string> extends Context {
   id: string
   trackingType: TrackingType
+  isReplayForced: boolean
 }
 
 export const VISIBILITY_CHECK_DELAY = ONE_MINUTE
@@ -79,14 +83,17 @@ export function startSessionManager<TrackingType extends string>(
     return {
       id: sessionStore.getSession().id!,
       trackingType: sessionStore.getSession()[productKey] as TrackingType,
+      isReplayForced: !!sessionStore.getSession().forcedReplay,
     }
   }
 
   return {
     findSession: (startTime, options) => sessionContextHistory.find(startTime, options),
     renewObservable,
     expireObservable,
+    sessionStateUpdateObservable: sessionStore.sessionStateUpdateObservable,
     expire: sessionStore.expire,
+    updateSessionState: sessionStore.updateSessionState,
   }
 }
 

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

@@ -472,4 +472,64 @@ describe('session store', () => {
       })
     })
   })
+
+  describe('session update and synchronisation', () => {
+    let updateSpy: jasmine.Spy<jasmine.Func>
+    let otherUpdateSpy: jasmine.Spy<jasmine.Func>
+    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.sessionStateUpdateObservable.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.updateSessionState({ extra: 'extra' })
+
+      expect(updateSpy).toHaveBeenCalledTimes(1)
+
+      const callArgs = updateSpy.calls.argsFor(0)[0]
+      expect(callArgs!.previousState.extra).toBeUndefined()
+      expect(callArgs.newState.extra).toBe('extra')
+
+      // 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>
+  sessionStateUpdateObservable: Observable<{ previousState: SessionState; newState: SessionState }>
   expire: () => void
   stop: () => void
+  updateSessionState: (state: Partial<SessionState>) => void
 }
 
 /**
@@ -61,6 +64,7 @@ export function startSessionStore<TrackingType extends string>(
 ): SessionStore {
   const renewObservable = new Observable<void>()
   const expireObservable = new Observable<void>()
+  const sessionStateUpdateObservable = new Observable<{ previousState: SessionState; newState: SessionState }>()
 
   const sessionStoreStrategy =
     sessionStoreStrategyType.type === 'Cookie'
@@ -128,6 +132,7 @@ export function startSessionStore<TrackingType extends string>(
       if (isSessionInCacheOutdated(sessionState)) {
         expireSessionInCache()
       } else {
+        sessionStateUpdateObservable.notify({ previousState: sessionCache, newState: sessionState })
         sessionCache = sessionState
       }
     }
@@ -182,12 +187,23 @@ export function startSessionStore<TrackingType extends string>(
     renewObservable.notify()
   }
 
+  function updateSessionState(partialSessionState: Partial<SessionState>) {
+    processSessionStoreOperations(
+      {
+        process: (sessionState) => assign({}, sessionState, partialSessionState),
+        after: synchronizeSession,
+      },
+      sessionStoreStrategy
+    )
+  }
+
   return {
     expandOrRenewSession: throttledExpandOrRenewSession,
     expandSession,
     getSession: () => sessionCache,
     renewObservable,
     expireObservable,
+    sessionStateUpdateObservable,
     restartSession: startSession,
     expire: () => {
       cancelExpandOrRenewSession()
@@ -197,5 +213,6 @@ export function startSessionStore<TrackingType extends string>(
     stop: () => {
       clearInterval(watchSessionTimeoutId)
     },
+    updateSessionState,
   }
 }

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,
@@ -487,10 +490,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

@@ -28,7 +28,7 @@ import type { CiVisibilityContext } from './contexts/ciVisibilityContext'
 import type { LifeCycle } from './lifeCycle'
 import { LifeCycleEventType } from './lifeCycle'
 import type { ViewContexts } from './contexts/viewContexts'
-import type { RumSessionManager } from './rumSessionManager'
+import { SessionReplayState, type RumSessionManager } from './rumSessionManager'
 import type { UrlContexts } from './contexts/urlContexts'
 import type { RumConfiguration } from './configuration'
 import type { ActionContexts } from './action/actionCollection'
@@ -178,7 +178,8 @@ 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.sessionReplay === SessionReplayState.SAMPLED
         }
 
         if (!isEmptyObject(commonContext.user)) {

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

@@ -21,6 +21,7 @@ import { LifeCycle, LifeCycleEventType } from './lifeCycle'
 import {
   RUM_SESSION_KEY,
   RumTrackingType,
+  SessionReplayState,
   startRumSessionManager,
   startRumSessionManagerStub,
 } from './rumSessionManager'
@@ -163,13 +164,21 @@ describe('rum session manager', () => {
     it('should return session TRACKED_WITH_SESSION_REPLAY', () => {
       setCookie(SESSION_STORE_KEY, 'id=abcdef&rum=1', DURATION)
       const rumSessionManager = startRumSessionManagerWithDefaults()
-      expect(rumSessionManager.findTrackedSession()!.sessionReplayAllowed).toBe(true)
+      expect(rumSessionManager.findTrackedSession()!.sessionReplay).toBe(SessionReplayState.SAMPLED)
     })
 
     it('should return session TRACKED_WITHOUT_SESSION_REPLAY', () => {
       setCookie(SESSION_STORE_KEY, 'id=abcdef&rum=2', DURATION)
       const rumSessionManager = startRumSessionManagerWithDefaults()
-      expect(rumSessionManager.findTrackedSession()!.sessionReplayAllowed).toBe(false)
+      expect(rumSessionManager.findTrackedSession()!.sessionReplay).toBe(SessionReplayState.OFF)
+    })
+
+    it('should update current entity when replay recording is forced', () => {
+      setCookie(SESSION_STORE_KEY, 'id=abcdef&rum=2', DURATION)
+      const rumSessionManager = startRumSessionManagerWithDefaults()
+      rumSessionManager.setForcedReplay()
+
+      expect(rumSessionManager.findTrackedSession()!.sessionReplay).toBe(SessionReplayState.FORCED)
     })
   })
 
@@ -178,12 +187,12 @@ describe('rum session manager', () => {
       {
         description: 'TRACKED_WITH_SESSION_REPLAY should have replay',
         sessionReplaySampleRate: 100,
-        expectSessionReplay: true,
+        expectSessionReplay: SessionReplayState.SAMPLED,
       },
       {
         description: 'TRACKED_WITHOUT_SESSION_REPLAY should have no replay',
         sessionReplaySampleRate: 0,
-        expectSessionReplay: false,
+        expectSessionReplay: SessionReplayState.OFF,
       },
     ].forEach(
       ({
@@ -193,13 +202,13 @@ describe('rum session manager', () => {
       }: {
         description: string
         sessionReplaySampleRate: number
-        expectSessionReplay: boolean
+        expectSessionReplay: SessionReplayState
       }) => {
         it(description, () => {
           const rumSessionManager = startRumSessionManagerWithDefaults({
             configuration: { sessionSampleRate: 100, sessionReplaySampleRate },
           })
-          expect(rumSessionManager.findTrackedSession()!.sessionReplayAllowed).toBe(expectSessionReplay)
+          expect(rumSessionManager.findTrackedSession()!.sessionReplay).toBe(expectSessionReplay)
         })
       }
     )
@@ -224,11 +233,11 @@ describe('rum session manager', () => {
 describe('rum session manager stub', () => {
   it('should return a tracked session with replay allowed when the event bridge support records', () => {
     initEventBridgeStub({ capabilities: [BridgeCapability.RECORDS] })
-    expect(startRumSessionManagerStub().findTrackedSession()!.sessionReplayAllowed).toEqual(true)
+    expect(startRumSessionManagerStub().findTrackedSession()!.sessionReplay).toEqual(SessionReplayState.SAMPLED)
   })
 
   it('should return a tracked session without replay allowed when the event bridge support records', () => {
     initEventBridgeStub({ capabilities: [] })
-    expect(startRumSessionManagerStub().findTrackedSession()!.sessionReplayAllowed).toEqual(false)
+    expect(startRumSessionManagerStub().findTrackedSession()!.sessionReplay).toEqual(SessionReplayState.OFF)
   })
 })