feat(rum): add sessionOnError

CHANGELOG.md

@@ -18,6 +18,19 @@
 
 ---
 
+## Unreleased
+
+- ✨ Two new init options keep only the sessions that report an error, for customers who want every
+  error investigated without storing and paying for every session. `sessionOnError` keeps the
+  events of a session the plain `sessionSampleRate` draw missed: it records from the start, uploads
+  nothing, and is never stored unless it reports an error — on the first error the withheld history,
+  up to the last minute of it, is uploaded and collection continues. `sessionReplayOnError` does the
+  same for the Session Replay of a session the plain `sessionReplaySampleRate` draw missed. Both are
+  switches, default off, and apply only to what the plain rate did not already draw, so a session is
+  never counted twice. Both can also be set from the console when `remoteConfigurationEnabled` is on.
+  View events of such a session carry `sampled_for_error` / `sampled_for_error_replay` so a stored
+  error session can be told apart from an ordinary one.
+
 ## v0.2.2
 
 - 🐛 The settings cache no longer grows by one entry per release of your site. Entries are keyed by

packages/core/src/transport/flushController.ts

@@ -78,6 +78,7 @@ export function createFlushController({
   }
 
   return {
+    flush,
     flushObservable,
     get messagesCount() {
       return currentMessagesCount

packages/core/src/transport/startBatchWithReplica.ts

@@ -6,6 +6,7 @@ import type { RawError } from '../domain/error/error.types'
 import type { Encoder } from '../tools/encoder'
 import { createBatch } from './batch'
 import { createHttpRequest } from './httpRequest'
+import type { FlushReason } from './flushController'
 import { createFlushController } from './flushController'
 
 export interface BatchConfiguration {
@@ -45,6 +46,10 @@ export function startBatchWithReplica<T extends Context>(
   }
 
   return {
+    flush: (reason: FlushReason) => {
+      primaryBatch.flushController.flush(reason)
+      replicaBatch?.flushController.flush(reason)
+    },
     flushObservable: primaryBatch.flushController.flushObservable,
 
     add(message: T, replicated = true) {

packages/core/test/emulate/mockFlushController.ts

@@ -8,7 +8,7 @@ export function createMockFlushController() {
   let currentMessagesCount = 0
   let currentBytesCount = 0
 
-  return {
+  const controller = {
     notifyBeforeAddMessage: jasmine
       .createSpy<FlushController['notifyBeforeAddMessage']>()
       .and.callFake((messageBytesCount) => {
@@ -33,6 +33,11 @@ export function createMockFlushController() {
       return currentBytesCount
     },
     flushObservable,
+    flush(reason: FlushReason) {
+      if (currentMessagesCount > 0) {
+        controller.notifyFlush(reason)
+      }
+    },
     notifyFlush(reason: FlushReason = 'bytes_limit') {
       if (currentMessagesCount === 0) {
         throw new Error(
@@ -53,4 +58,5 @@ export function createMockFlushController() {
       })
     },
   } satisfies Record<any, any> & FlushController
+  return controller
 }

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

@@ -104,6 +104,11 @@ export function startRum(
   }
 
   const pageMayExitObservable = createPageMayExitObservable(configuration)
+  // Subscribed before the batch below, and it has to stay that way. The batch flushes on this same
+  // observable, and observers run in the order they subscribed - so the withheld event buffer, which
+  // releases on the lifecycle notification raised here, has to get its events into the batch before
+  // the flush that is the page's last chance to send them. The same holds for the session expiry
+  // relay in `startRumSessionManager`, which the session manager registers just below.
   const pageMayExitSubscription = pageMayExitObservable.subscribe((event) => {
     lifeCycle.notify(LifeCycleEventType.PAGE_MAY_EXIT, event)
   })
@@ -122,6 +127,9 @@ export function startRum(
     : startRumSessionManager(configuration, lifeCycle, trackingConsentState)
   cleanupTasks.push(session.stop)
 
+  // Subscribed before the batch below, and it has to stay that way: the withheld event buffer runs
+  // on the same event, and only sees a session as released if this has already marked it. Reorder
+  // them and the release waits for whatever event happens to come next.
   const sessionErrorTracking = startSessionErrorTracking(lifeCycle, session)
   cleanupTasks.push(() => sessionErrorTracking.stop())
 
@@ -139,7 +147,7 @@ export function startRum(
       telemetry.observable,
       reportError,
       pageMayExitObservable,
-      session.expireObservable,
+      session,
       createEncoder
     )
     cleanupTasks.push(() => batch.stop())

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

@@ -140,6 +140,109 @@ describe('validateAndBuildRumConfiguration', () => {
     })
   })
 
+  describe('sessionOnError', () => {
+    it('is carried into the built configuration', () => {
+      expect(
+        validateAndBuildRumConfiguration({ ...DEFAULT_INIT_CONFIGURATION, sessionOnError: true })!.sessionOnError
+      ).toBeTrue()
+    })
+
+    it('defaults to collecting no error-only session at all', () => {
+      expect(validateAndBuildRumConfiguration(DEFAULT_INIT_CONFIGURATION)!.sessionOnError).toBeFalse()
+    })
+
+    it('is read as a switch, whatever it was given', () => {
+      expect(
+        validateAndBuildRumConfiguration({
+          ...DEFAULT_INIT_CONFIGURATION,
+          sessionOnError: 'yes' as unknown as boolean,
+        })!.sessionOnError
+      ).toBeTrue()
+    })
+
+    it('warns when the replay it would withhold is never recorded', () => {
+      validateAndBuildRumConfiguration({
+        ...DEFAULT_INIT_CONFIGURATION,
+        sessionSampleRate: 20,
+        sessionOnError: true,
+        sessionReplaySampleRate: 50,
+        startSessionReplayRecordingManually: true,
+      })
+
+      expect(displayWarnSpy).toHaveBeenCalledTimes(1)
+      expect(displayWarnSpy.calls.argsFor(0)[0]).toContain('startSessionReplayRecordingManually')
+    })
+
+    it('says nothing about a replay it could never withhold anyway', () => {
+      validateAndBuildRumConfiguration({
+        ...DEFAULT_INIT_CONFIGURATION,
+        sessionOnError: true,
+        sessionReplaySampleRate: 30,
+        startSessionReplayRecordingManually: true,
+      })
+
+      // the switch cannot apply at all here, which is the one thing worth saying
+      expect(displayWarnSpy).toHaveBeenCalledTimes(1)
+      expect(displayWarnSpy.calls.argsFor(0)[0]).toContain('sessionSampleRate did not draw')
+    })
+
+    it('does not warn about manual recording when replay is disabled for the on-error session', () => {
+      // there is nothing to withhold on the replay side, so the manual-start warning does not apply -
+      // even though the plain session rate leaves room for the switch and recording is manual
+      validateAndBuildRumConfiguration({
+        ...DEFAULT_INIT_CONFIGURATION,
+        sessionSampleRate: 20,
+        sessionOnError: true,
+        sessionReplaySampleRate: 0,
+        startSessionReplayRecordingManually: true,
+      })
+
+      expect(displayWarnSpy).not.toHaveBeenCalled()
+    })
+
+    it('warns when the default session rate leaves it nothing to apply to', () => {
+      validateAndBuildRumConfiguration({
+        ...DEFAULT_INIT_CONFIGURATION,
+        sessionOnError: true,
+      })
+
+      expect(displayWarnSpy).toHaveBeenCalledTimes(1)
+    })
+
+    it('stays silent under remote configuration, where the console owns the session rate', () => {
+      // the documented remote-config setup: the site omits the rate and lets the console deliver it,
+      // so the init default of 100 is a fallback, not the rate the switch will face
+      validateAndBuildRumConfiguration({
+        ...DEFAULT_INIT_CONFIGURATION,
+        sessionOnError: true,
+        remoteConfigurationEnabled: true,
+      })
+
+      expect(displayWarnSpy).not.toHaveBeenCalled()
+    })
+
+    it('says nothing once the plain session rate leaves room for it', () => {
+      validateAndBuildRumConfiguration({
+        ...DEFAULT_INIT_CONFIGURATION,
+        sessionSampleRate: 20,
+        sessionOnError: true,
+      })
+
+      expect(displayWarnSpy).not.toHaveBeenCalled()
+    })
+
+    it('makes the replay-on-error switch meaningful even with no plainly sampled session', () => {
+      validateAndBuildRumConfiguration({
+        ...DEFAULT_INIT_CONFIGURATION,
+        sessionSampleRate: 0,
+        sessionOnError: true,
+        sessionReplayOnError: true,
+      })
+
+      expect(displayWarnSpy).not.toHaveBeenCalled()
+    })
+  })
+
   describe('traceSampleRate', () => {
     it('defaults to 100 if the option is not provided', () => {
       expect(validateAndBuildRumConfiguration(DEFAULT_INIT_CONFIGURATION)!.traceSampleRate).toBe(100)
@@ -650,6 +753,7 @@ describe('serializeRumConfiguration', () => {
       subdomain: 'foo',
       sessionReplaySampleRate: 60,
       sessionReplayOnError: true,
+      sessionOnError: true,
       startSessionReplayRecordingManually: true,
       sessionReplayDirectUpload: true,
       trackUserInteractions: true,
@@ -685,6 +789,7 @@ describe('serializeRumConfiguration', () => {
                 | 'beforeSampling'
                 // not reported yet: needs a rum-events-format schema change first
                 | 'sessionReplayOnError'
+                | 'sessionOnError'
             ? never
             : CamelToSnakeCase<Key>
     // By specifying the type here, we can ensure that serializeConfiguration is returning an

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

@@ -209,6 +209,19 @@ export interface RumInitConfiguration extends InitConfiguration {
    * the withheld minute is uploaded and recording continues normally for the rest of the session.
    */
   sessionReplayOnError?: boolean | undefined
+  /**
+   * Whether the sessions that `sessionSampleRate` did not draw still collect events, uploaded only
+   * if the session reports an error. Default: false. It only applies to what the plain rate missed,
+   * so with the default `sessionSampleRate` of 100 there is nothing left for it to apply to.
+   *
+   * Such a session collects from the start and keeps at most the last minute of it in memory. If it
+   * never reports an error, nothing is uploaded and the session is not stored. On the first error,
+   * the withheld minute is uploaded and collection continues normally.
+   *
+   * A session kept this way never uploads its replay ahead of its events: until the events are
+   * released the session does not exist yet, and a replay sent then would have nothing to attach to.
+   */
+  sessionOnError?: boolean | undefined
   /**
    * If the session is sampled for Session Replay, only start the recording when `startSessionReplayRecording()` is called, instead of at the beginning of the session.
    *
@@ -317,6 +330,7 @@ export interface RumConfiguration extends Configuration {
   enablePrivacyForActionName: boolean
   sessionReplaySampleRate: number
   sessionReplayOnError: boolean
+  sessionOnError: boolean
   startSessionReplayRecordingManually: boolean
   sessionReplayDirectUpload: boolean
   trackUserInteractions: boolean
@@ -402,32 +416,57 @@ export function validateAndBuildRumConfiguration(
 
   const sessionReplaySampleRate = initConfiguration.sessionReplaySampleRate ?? 0
   const sessionReplayOnError = !!initConfiguration.sessionReplayOnError
+  const sessionOnError = !!initConfiguration.sessionOnError
 
-  // Each of these is a combination the customer can set that cannot apply to a single session. It
-  // is valid, so validation lets it through - but silence would leave them waiting for data that is
-  // never coming.
-  if (sessionReplayOnError) {
-    if (sessionReplaySampleRate === 100) {
+  // Each of the cases below is a combination the customer can set that cannot apply to a single
+  // session. It is valid, so validation lets it through - but silence would leave someone waiting
+  // for data that is never coming.
+  //
+  // Only judged against the init rates when the console cannot change them: under remote
+  // configuration these values are a fallback until the first fetch lands, so the console may
+  // deliver the very rate that leaves the switch room to apply. Warning on the init values there
+  // would fire on the documented remote-config setup - a site that omits the rate and lets the
+  // console own it - which is exactly not a misconfiguration.
+  if (!initConfiguration.remoteConfigurationEnabled) {
+    if (sessionOnError && (initConfiguration.sessionSampleRate ?? 100) === 100) {
       display.warn(
-        'sessionReplayOnError only applies to sessions sessionReplaySampleRate did not draw, and that rate is 100: it will never apply.'
+        'sessionOnError only applies to sessions sessionSampleRate did not draw, and that rate is 100: it will never apply.'
       )
     }
-    if ((initConfiguration.sessionSampleRate ?? 100) === 0) {
-      display.warn('sessionReplayOnError has no effect while sessionSampleRate is 0: no session is tracked.')
-    }
-    if (initConfiguration.startSessionReplayRecordingManually) {
-      display.warn(
-        'sessionReplayOnError needs the recording to already be running when the error happens, and startSessionReplayRecordingManually keeps it stopped until you start it: there would be nothing to release.'
-      )
+    if (sessionReplayOnError) {
+      if (sessionReplaySampleRate === 100) {
+        display.warn(
+          'sessionReplayOnError only applies to sessions sessionReplaySampleRate did not draw, and that rate is 100: it will never apply.'
+        )
+      }
+      if ((initConfiguration.sessionSampleRate ?? 100) === 0 && !sessionOnError) {
+        display.warn(
+          'sessionReplayOnError has no effect while sessionSampleRate is 0 and sessionOnError is off: no session is tracked.'
+        )
+      }
     }
   }
 
+  // A session kept on error withholds whichever replay it draws, so the same trap is reachable
+  // through the plain replay rate as well - and there it is worse than silence, since the released
+  // views would report a replay for a recording that never ran.
+  if (
+    initConfiguration.startSessionReplayRecordingManually &&
+    (sessionReplayOnError ||
+      (sessionOnError && sessionReplaySampleRate > 0 && (initConfiguration.sessionSampleRate ?? 100) < 100))
+  ) {
+    display.warn(
+      'A replay kept until the session errors has to be recording before that error, and startSessionReplayRecordingManually keeps it stopped until you start it: there would be nothing to release.'
+    )
+  }
+
   return {
     applicationId: initConfiguration.applicationId,
     version: initConfiguration.version || undefined,
     actionNameAttribute: initConfiguration.actionNameAttribute,
     sessionReplaySampleRate,
     sessionReplayOnError,
+    sessionOnError,
     startSessionReplayRecordingManually:
       initConfiguration.startSessionReplayRecordingManually !== undefined
         ? !!initConfiguration.startSessionReplayRecordingManually
@@ -525,7 +564,7 @@ export function serializeRumConfiguration(configuration: RumInitConfiguration) {
 
   return {
     session_replay_sample_rate: configuration.sessionReplaySampleRate,
-    // `session_replay_on_error` is deliberately not reported yet: the telemetry
+    // `session_replay_on_error` and `session_on_error` are deliberately not reported yet: the telemetry
     // configuration type is generated from the rum-events-format schema, so adding it needs a schema
     // change first, and that is a separate repository.
     start_session_replay_recording_manually: configuration.startSessionReplayRecordingManually,

packages/rum-core/src/domain/configuration/remoteConfiguration.spec.ts

@@ -121,13 +121,17 @@ describe('remoteConfiguration', () => {
       start(configurationWith())
     })
 
-    it('keeps the replay-on-error switch the server reports, either way it is set', (done) => {
+    it('keeps the on-error switches the server reports, either way they are set', (done) => {
       interceptor.withMockXhr((xhr) => {
-        xhr.complete(200, body({ rum: { sessionReplaySampleRate: 10, sessionReplayOnError: false } }))
+        xhr.complete(
+          200,
+          body({ rum: { sessionReplaySampleRate: 10, sessionReplayOnError: false, sessionOnError: true } })
+        )
 
         expect(readRemoteConfig(setup)).toEqual({
           sessionReplaySampleRate: 10,
           sessionReplayOnError: false,
+          sessionOnError: true,
           version: 3,
         })
         done()

packages/rum-core/src/domain/configuration/remoteConfiguration.ts

@@ -108,6 +108,11 @@ export interface RemoteConfigValues {
    * either withholds its replay from the start or never does.
    */
   sessionReplayOnError?: boolean
+  /**
+   * Whether the sessions `sessionSampleRate` did not draw still collect, uploaded only if the
+   * session errors. Same footing as the replay switch above.
+   */
+  sessionOnError?: boolean
   /**
    * Which version of the settings these rates came from. Reported back on the next request so the
    * console can say how far a change has actually reached — a question the events cannot answer,
@@ -270,6 +275,9 @@ function readStoredValues(parsed: unknown): RemoteConfigValues {
   if (isSwitch(stored.sessionReplayOnError)) {
     values.sessionReplayOnError = stored.sessionReplayOnError
   }
+  if (isSwitch(stored.sessionOnError)) {
+    values.sessionOnError = stored.sessionOnError
+  }
   if (isBag(stored.custom)) {
     values.custom = stored.custom
   }
@@ -498,6 +506,9 @@ function store(setup: RemoteConfigSetup, response: RemoteConfigurationResponse)
     if (isSwitch(response.rum.sessionReplayOnError)) {
       values.sessionReplayOnError = response.rum.sessionReplayOnError
     }
+    if (isSwitch(response.rum.sessionOnError)) {
+      values.sessionOnError = response.rum.sessionOnError
+    }
   }
   // The custom bag rides along untouched — the platform's job is delivery, its meaning belongs to
   // the host application. Gone from the response (or the kill switch off) means gone from storage.