🐛 collect feature flag evaluations before rum start in a map instead of a buffer

Previously, `addFeatureFlagEvaluation` calls made before `startRum` were
buffered and replayed after init. This caused the `BoundedBuffer` limit to
be reached when many flags were evaluated early, silently dropping other
buffered calls (e.g. `setUser`).

Instead, pre-start evaluations are now collected into a `FeatureFlagCollection`
(a `Map<string, ContextValue>`) and passed to `startFeatureFlagContexts`,
which seeds the first view's context with it. Subsequent views start with an
empty collection as before. This trades per-evaluation ordering for
reliability.

Author: BenoitZugmeyer

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

@@ -681,17 +681,13 @@ describe('preStartRum', () => {
     })
 
     it('addFeatureFlagEvaluation', async () => {
-      const addFeatureFlagEvaluationSpy = jasmine.createSpy()
-      doStartRumSpy.and.returnValue({
-        addFeatureFlagEvaluation: addFeatureFlagEvaluationSpy,
-      } as unknown as StartRumResult)
-
       const key = 'foo'
       const value = 'bar'
       strategy.addFeatureFlagEvaluation(key, value)
       strategy.init(DEFAULT_INIT_CONFIGURATION, PUBLIC_API)
-      await collectAsyncCalls(addFeatureFlagEvaluationSpy, 1)
-      expect(addFeatureFlagEvaluationSpy).toHaveBeenCalledOnceWith(key, value)
+      await collectAsyncCalls(doStartRumSpy, 1)
+      const initialFeatureFlagCollection: Map<string, unknown> = doStartRumSpy.calls.argsFor(0)[6]
+      expect(initialFeatureFlagCollection.get(key)).toEqual(value)
     })
 
     it('startDurationVital', async () => {

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

@@ -50,6 +50,8 @@ import type { ViewOptions } from '../domain/view/trackViews'
 import type { FeatureOperationOptions, FailureReason } from '../domain/vital/vitalCollection'
 import { callPluginsMethod } from '../domain/plugins'
 import { startTrackingConsentContext } from '../domain/contexts/trackingConsentContext'
+import { createFeatureFlagCollection } from '../domain/contexts/featureFlagContext'
+import type { FeatureFlagCollection } from '../domain/contexts/featureFlagContext'
 import type { StartRumResult } from './startRum'
 import type { RumPublicApiOptions, Strategy } from './rumPublicApi'
 
@@ -59,7 +61,8 @@ export type DoStartRum = (
   deflateWorker: DeflateWorker | undefined,
   initialViewOptions: ViewOptions | undefined,
   telemetry: Telemetry,
-  hooks: Hooks
+  hooks: Hooks,
+  initialFeatureFlagCollection: FeatureFlagCollection
 ) => StartRumResult
 
 export function createPreStartStrategy(
@@ -68,6 +71,7 @@ export function createPreStartStrategy(
   doStartRum: DoStartRum
 ): Strategy {
   const bufferApiCalls = createBoundedBuffer<StartRumResult>()
+  const initialFeatureFlagCollection = createFeatureFlagCollection()
 
   // TODO next major: remove the globalContextManager, userContextManager and accountContextManager from preStartStrategy and use an empty context instead
   const globalContext = buildGlobalContextManager()
@@ -123,7 +127,8 @@ export function createPreStartStrategy(
       deflateWorker,
       initialViewOptions,
       telemetry,
-      hooks
+      hooks,
+      initialFeatureFlagCollection
     )
 
     bufferApiCalls.drain(startRumResult)
@@ -324,8 +329,13 @@ export function createPreStartStrategy(
       bufferApiCalls.add((startRumResult) => startRumResult.addError(providedError))
     },
 
+    // Intentionally not using bufferApiCalls here: feature flag evaluations can be called very
+    // frequently before RUM starts (e.g. by flag evaluation frameworks on page load), which would
+    // exhaust the BoundedBuffer and silently drop other buffered calls such as setUser.
+    // Trade-off: we lose per-call granularity (only the last value per key is kept), but we avoid
+    // storing an unbounded call history in memory.
     addFeatureFlagEvaluation(key, value) {
-      bufferApiCalls.add((startRumResult) => startRumResult.addFeatureFlagEvaluation(key, value))
+      initialFeatureFlagCollection.set(key, value)
     },
 
     startDurationVital(name, options) {

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

@@ -639,10 +639,10 @@ describe('rum public api', () => {
     it('should add feature flag evaluation when ff feature_flags enabled', async () => {
       rumPublicApi.init(DEFAULT_INIT_CONFIGURATION)
       rumPublicApi.addFeatureFlagEvaluation('feature', 'foo')
-      await collectAsyncCalls(startRumSpy, 1)
+      const calls = await collectAsyncCalls(startRumSpy, 1)
 
-      expect(addFeatureFlagEvaluationSpy).toHaveBeenCalledTimes(1)
-      expect(addFeatureFlagEvaluationSpy.calls.argsFor(0)).toEqual(['feature', 'foo'])
+      const initialFeatureFlagCollection: Map<string, unknown> = calls.argsFor(0)[5]
+      expect(initialFeatureFlagCollection.get('feature')).toBe('foo')
       expect(displaySpy).not.toHaveBeenCalled()
     })
   })
@@ -1217,7 +1217,7 @@ describe('rum public api', () => {
 
       rumPublicApi.init(DEFAULT_INIT_CONFIGURATION)
       const calls = await collectAsyncCalls(startRumSpy, 1)
-      const sdkName = calls.argsFor(0)[9]
+      const sdkName = calls.argsFor(0)[10]
       expect(sdkName).toBe('rum-slim')
     })
   })

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

@@ -609,7 +609,15 @@ export function makeRumPublicApi(
   let strategy = createPreStartStrategy(
     options,
     trackingConsentState,
-    (configuration, sessionManager, deflateWorker, initialViewOptions, telemetry, hooks) => {
+    (
+      configuration,
+      sessionManager,
+      deflateWorker,
+      initialViewOptions,
+      telemetry,
+      hooks,
+      initialFeatureFlagCollection
+    ) => {
       const createEncoder =
         deflateWorker && options.createDeflateEncoder
           ? (streamId: DeflateEncoderStreamId) => options.createDeflateEncoder!(configuration, deflateWorker, streamId)
@@ -621,6 +629,7 @@ export function makeRumPublicApi(
         recorderApi,
         profilerApi,
         initialViewOptions,
+        initialFeatureFlagCollection,
         createEncoder,
         bufferedDataObservable,
         telemetry,

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

@@ -51,6 +51,7 @@ function startRumStub(
     sessionManager,
     noopRecorderApi,
     undefined,
+    new Map(),
     new Observable(),
     undefined,
     reportError
@@ -161,6 +162,7 @@ describe('view events', () => {
       noopRecorderApi,
       noopProfilerApi,
       undefined,
+      new Map(),
       createIdentityEncoder,
       new BufferedObservable<BufferedData>(100),
       createFakeTelemetryObject(),

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

@@ -33,6 +33,7 @@ import { startUrlContexts } from '../domain/contexts/urlContexts'
 import { createLocationChangeObservable } from '../browser/locationChangeObservable'
 import type { RumConfiguration } from '../domain/configuration'
 import type { ViewOptions } from '../domain/view/trackViews'
+import type { FeatureFlagCollection } from '../domain/contexts/featureFlagContext'
 import { startFeatureFlagContexts } from '../domain/contexts/featureFlagContext'
 import { startCustomerDataTelemetry } from '../domain/startCustomerDataTelemetry'
 import { startPageStateHistory } from '../domain/contexts/pageStateHistory'
@@ -61,6 +62,7 @@ export function startRum(
   recorderApi: RecorderApi,
   profilerApi: ProfilerApi,
   initialViewOptions: ViewOptions | undefined,
+  initialFeatureFlagCollection: FeatureFlagCollection,
   createEncoder: (streamId: DeflateEncoderStreamId) => Encoder,
   bufferedDataObservable: BufferedObservable<BufferedData>,
   telemetry: Telemetry,
@@ -116,6 +118,7 @@ export function startRum(
     sessionManager,
     recorderApi,
     initialViewOptions,
+    initialFeatureFlagCollection,
     bufferedDataObservable,
     sdkName,
     reportError
@@ -146,6 +149,7 @@ export function startRumEventCollection(
   sessionManager: SessionManager,
   recorderApi: RecorderApi,
   initialViewOptions: ViewOptions | undefined,
+  initialFeatureFlagCollection: FeatureFlagCollection,
   bufferedDataObservable: Observable<BufferedData>,
   sdkName: SdkName | undefined,
   reportError: (error: RawError) => void
@@ -164,7 +168,7 @@ export function startRumEventCollection(
   cleanupTasks.push(() => viewHistory.stop())
   const urlContexts = startUrlContexts(lifeCycle, hooks, locationChangeObservable)
   cleanupTasks.push(() => urlContexts.stop())
-  const featureFlagContexts = startFeatureFlagContexts(lifeCycle, hooks, configuration)
+  const featureFlagContexts = startFeatureFlagContexts(lifeCycle, hooks, configuration, initialFeatureFlagCollection)
   startSessionContext(hooks, configuration, sessionManager, recorderApi, viewHistory)
   startConnectivityContext(hooks)
   const globalContext = startGlobalContext(hooks, configuration, 'rum', true)

packages/rum-core/src/domain/contexts/featureFlagContext.spec.ts

@@ -9,7 +9,7 @@ import { RumEventType } from '../../rawRumEvent.types'
 import type { AssembleHookParams, Hooks } from '../hooks'
 import { createHooks } from '../hooks'
 import type { FeatureFlagContexts } from './featureFlagContext'
-import { startFeatureFlagContexts } from './featureFlagContext'
+import { createFeatureFlagCollection, startFeatureFlagContexts } from './featureFlagContext'
 
 describe('featureFlagContexts', () => {
   const lifeCycle = new LifeCycle()
@@ -22,9 +22,14 @@ describe('featureFlagContexts', () => {
     clock = mockClock()
     hooks = createHooks()
     trackFeatureFlagsForEvents = []
-    featureFlagContexts = startFeatureFlagContexts(lifeCycle, hooks, {
-      trackFeatureFlagsForEvents,
-    } as unknown as RumConfiguration)
+    featureFlagContexts = startFeatureFlagContexts(
+      lifeCycle,
+      hooks,
+      {
+        trackFeatureFlagsForEvents,
+      } as unknown as RumConfiguration,
+      new Map()
+    )
   })
 
   describe('assemble hook', () => {
@@ -154,6 +159,60 @@ describe('featureFlagContexts', () => {
       expect(defaultRumEventAttributes).toBeUndefined()
     })
 
+    it('should initialize the first view with the initial collection', () => {
+      const initialCollection = createFeatureFlagCollection()
+      initialCollection.set('feature', 'initial')
+      featureFlagContexts = startFeatureFlagContexts(
+        lifeCycle,
+        hooks,
+        {
+          trackFeatureFlagsForEvents,
+        } as unknown as RumConfiguration,
+        initialCollection
+      )
+
+      lifeCycle.notify(LifeCycleEventType.BEFORE_VIEW_CREATED, {
+        startClocks: relativeToClocks(0 as RelativeTime),
+      } as ViewCreatedEvent)
+
+      expect(
+        hooks.triggerHook(HookNames.Assemble, {
+          eventType: 'view',
+          startTime: 0 as RelativeTime,
+        } as AssembleHookParams)
+      ).toEqual({ type: 'view', feature_flags: { feature: 'initial' } })
+    })
+
+    it('should not carry over the initial collection to subsequent views', () => {
+      const initialCollection = createFeatureFlagCollection()
+      initialCollection.set('feature', 'initial')
+      featureFlagContexts = startFeatureFlagContexts(
+        lifeCycle,
+        hooks,
+        {
+          trackFeatureFlagsForEvents,
+        } as unknown as RumConfiguration,
+        initialCollection
+      )
+
+      lifeCycle.notify(LifeCycleEventType.BEFORE_VIEW_CREATED, {
+        startClocks: relativeToClocks(0 as RelativeTime),
+      } as ViewCreatedEvent)
+      lifeCycle.notify(LifeCycleEventType.AFTER_VIEW_ENDED, {
+        endClocks: relativeToClocks(10 as RelativeTime),
+      } as ViewEndedEvent)
+      lifeCycle.notify(LifeCycleEventType.BEFORE_VIEW_CREATED, {
+        startClocks: relativeToClocks(10 as RelativeTime),
+      } as ViewCreatedEvent)
+
+      expect(
+        hooks.triggerHook(HookNames.Assemble, {
+          eventType: 'view',
+          startTime: 10 as RelativeTime,
+        } as AssembleHookParams)
+      ).toBeUndefined()
+    })
+
     it('should replace existing feature flag evaluations for the current view', () => {
       lifeCycle.notify(LifeCycleEventType.BEFORE_VIEW_CREATED, {
         startClocks: relativeToClocks(0 as RelativeTime),

packages/rum-core/src/domain/contexts/featureFlagContext.ts

@@ -1,5 +1,5 @@
-import type { ContextValue, Context } from '@datadog/browser-core'
-import { HookNames, SESSION_TIME_OUT_DELAY, SKIPPED, createValueHistory, isEmptyObject } from '@datadog/browser-core'
+import type { ContextValue } from '@datadog/browser-core'
+import { HookNames, SESSION_TIME_OUT_DELAY, SKIPPED, createValueHistory } from '@datadog/browser-core'
 import type { LifeCycle } from '../lifeCycle'
 import { LifeCycleEventType } from '../lifeCycle'
 import { RumEventType } from '../../rawRumEvent.types'
@@ -9,12 +9,16 @@ import type { DefaultRumEventAttributes, Hooks } from '../hooks'
 export const FEATURE_FLAG_CONTEXT_TIME_OUT_DELAY = SESSION_TIME_OUT_DELAY
 export const BYTES_COMPUTATION_THROTTLING_DELAY = 200
 
-export type FeatureFlagContext = Context
+export type FeatureFlagCollection = Map<string, ContextValue>
 
 export interface FeatureFlagContexts {
   addFeatureFlagEvaluation: (key: string, value: ContextValue) => void
 }
 
+export function createFeatureFlagCollection(): FeatureFlagCollection {
+  return new Map()
+}
+
 /**
  * Start feature flag contexts
  *
@@ -26,14 +30,18 @@ export interface FeatureFlagContexts {
 export function startFeatureFlagContexts(
   lifeCycle: LifeCycle,
   hooks: Hooks,
-  configuration: RumConfiguration
+  configuration: RumConfiguration,
+  initialCollection: FeatureFlagCollection
 ): FeatureFlagContexts {
-  const featureFlagContexts = createValueHistory<FeatureFlagContext>({
+  const featureFlagContexts = createValueHistory<FeatureFlagCollection>({
     expireDelay: FEATURE_FLAG_CONTEXT_TIME_OUT_DELAY,
   })
 
+  let isFirstView = true
   lifeCycle.subscribe(LifeCycleEventType.BEFORE_VIEW_CREATED, ({ startClocks }) => {
-    featureFlagContexts.add({}, startClocks.relative)
+    const collection = isFirstView ? initialCollection : createFeatureFlagCollection()
+    isFirstView = false
+    featureFlagContexts.add(collection, startClocks.relative)
   })
 
   lifeCycle.subscribe(LifeCycleEventType.AFTER_VIEW_ENDED, ({ endClocks }) => {
@@ -50,21 +58,21 @@ export function startFeatureFlagContexts(
     }
 
     const featureFlagContext = featureFlagContexts.find(startTime)
-    if (!featureFlagContext || isEmptyObject(featureFlagContext)) {
+    if (!featureFlagContext || featureFlagContext.size === 0) {
       return SKIPPED
     }
 
     return {
       type: eventType,
-      feature_flags: featureFlagContext,
+      feature_flags: Object.fromEntries(featureFlagContext),
     }
   })
 
   return {
     addFeatureFlagEvaluation: (key: string, value: ContextValue) => {
-      const currentContext = featureFlagContexts.find()
-      if (currentContext) {
-        currentContext[key] = value
+      const currentCollection = featureFlagContexts.find()
+      if (currentCollection) {
+        currentCollection.set(key, value)
       }
     },
   }