Review: everything going out as 0.2.1 (do not merge)

CHANGELOG.md

@@ -18,6 +18,117 @@
 
 ---
 
+## v0.3.0
+
+- ✨ 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.
+
+  Known limitations of the on-error switches:
+
+  - A site that gates recording on consent by calling `startSessionReplayRecording()` itself must set
+    `startSessionReplayRecordingManually: true` explicitly. With `remoteConfigurationEnabled` on and an
+    init replay rate of 0, the recorder now starts on its own so a console-delivered rate has something
+    to withhold — which would otherwise begin recording before the consent call.
+  - On a single-page app, the released replay reaches back only to the start of the view the error
+    happened in, while the released events reach back the full minute across views.
+  - Leaving the page within a few seconds of a session's first error can lose part of a large release
+    (roughly above 64 KiB, such as a busy minute of requests), compressed or not: a browser only
+    guarantees a bounded amount of data at page exit. The views and the errors are sent first, so what
+    is lost is the oldest of the other events, and possibly the page's final view update.
+  - On a page with a very large DOM that changes constantly, a withheld replay re-takes a full snapshot
+    each time its buffer overflows. Every visitor the plain replay rate did not draw pays that main
+    thread cost, and the replay released before the error gets shorter. Prefer `sessionOnError` alone
+    on such pages.
+  - Withdrawing tracking consent after a session has reported its error still uploads what was withheld
+    for it, all of which was collected while consent stood.
+
+- 🐛 With `remoteConfigurationEnabled` on and an init `sessionReplaySampleRate` of 0 (or none), a Session
+  Replay rate set in the console now takes effect: recording starts, and replays are uploaded and
+  billed. Before, the rate was delivered but never started the recorder. Pass
+  `startSessionReplayRecordingManually: true` to keep recording off until you start it yourself.
+
+## v0.2.3
+
+- ✨ A session sample rate published from the console that rises above 0 now ends the running
+  session of a visitor whose session was drawn at 0, so collection starts at their next interaction
+  instead of waiting for that session to end on its own — up to four hours. This is the case where
+  waiting shows an operator who has just switched collection on nothing at all, which is
+  indistinguishable from a broken integration. It joins the two changes that already did not wait:
+  a stricter Session Replay privacy level, and a rate of 0. Nothing here happens without
+  `remoteConfigurationEnabled: true`.
+- 📝 Only a session drawn AT 0 is re-drawn, not every session that is not being collected. Those
+  are different populations: a visitor who lost a draw at 30 had a coin flipped for them, and
+  re-rolling the losers while the winners keep their sessions would put the real rate above the
+  published one. While a rate of 0 is in force nothing is collected and no coin is flipped, so
+  re-drawing everyone lands exactly on the new rate. A rate rising from one real value to another
+  therefore still waits for the next session, as before.
+- 📝 The rate a sampled-out session was drawn at is now recorded alongside the one a collected
+  session was drawn at, in the same single `localStorage` entry this SDK already keeps for the
+  draw. No new entry, no extra request. Without it a page that did not perform the draw — the
+  second page of a visit, or another tab — could not tell the two populations above apart. The
+  decision reads that record straight off storage rather than off what the page last saw of the
+  draw: two sampled-out sessions look alike to the session store, so a tab can miss another tab
+  ending one and drawing the next, and storage is the one place the current draw is always found.
+- 📝 What you will see on the day you lift a rate off 0: visitors who were invisible start
+  appearing within seconds of loading a page rather than at their next session, so collected volume
+  climbs the same day rather than the next. That is the change taking effect, not a defect.
+
+---
+
+## v0.2.2
+
+- 🐛 The settings cache no longer grows by one entry per release of your site. Entries are keyed by
+  application version, because two releases served at the same time are entitled to different rates
+  — but the entry a previous release used was never read or removed again, so on a site that
+  deploys often they accumulated in the storage quota the page shares. New entries now record when
+  they were refreshed, and one left untouched for two days is removed when the SDK starts. Entries
+  written by older SDK builds are kept because they carry no refresh time, leaving a finite legacy
+  residue while preventing the cache from growing without bound.
+
+## v0.2.1
+
+- ✨ Two changes published from the console now end the running session, so they reach the visitor
+  at their next interaction instead of waiting for that session to end on its own: a stricter
+  Session Replay privacy level, and a session sample rate of 0 — the emergency stop, which took up
+  to four hours to stop anything before this. Both apply only while the visitor is being collected;
+  one who is not records nothing and sends nothing, so neither change has anything to act on there.
+  The session that ends is collected to its end as it began, so no recording is left masked in one
+  half and plain in the other. Every other change still waits for the next session, including a
+  loosening privacy level and a rate rising to 100 — for "collect this visitor now" there is
+  `setForcedSession()`. Custom values wait on their own too, but not once `beforeSampling` turns
+  them into a rate of 0. Nothing here happens without `remoteConfigurationEnabled: true`.
+- 📝 How soon "does not wait" is depends on when this client next hears of the change, and it hears
+  only at page load and at each new session — there is no timer. A visitor who keeps loading pages
+  hears within seconds of the publish and their session ends there. A single tab that is never
+  reloaded hears nothing until its session reaches the four-hour cap, so an always-on screen is the
+  case this does least for; any other tab the same visitor loads ends the session they share.
+- 📝 What you will see on the day you publish one of the two: session counts rise and average
+  session length drops, because each affected visitor's running session is split at that moment,
+  and a replay in progress ends at the split — the session that follows draws again, so it carries
+  a new recording only if that draw keeps one. That is the change taking effect, not a defect.
+- 📝 The two act on what actually changed, not on the activation mode recorded with the publish: a
+  change the console files as "next session" still ends the running session if it is one of them.
+- 📝 `beforeSampling` is now also consulted when settings arrive, away from any draw, to work out
+  which rate would apply. It must stay free of side effects and answer the same way for the same
+  input: a callback that draws its own lottery — answering 0 at random — can end a session that a
+  steady answer would have left running.
+- 📝 A session forced with `setForcedSession()` is not ended by a rate: forcing decides whether this
+  visitor is collected, and every draw the page makes is collected whatever the console says, so
+  ending it would only produce the same session again. A stricter privacy level still ends it,
+  because forcing says nothing about how much of the page may be uploaded in the clear. The page
+  forces the next session on its own, so the visit continues as two sessions.
+- 📝 Turning remote configuration off is itself a change: the rates go back to the ones passed to
+  `init`. On a site whose init rate is 0, switching it off stops collection at once rather than at
+  the next session.
+
 ## v0.2.0
 
 - 💥 **Breaking**: `remoteConfigurationId` is gone from `RumInitConfiguration`. It fetched a

developer-extension/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flashcatcloud/browser-sdk-developer-extension",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "private": true,
   "scripts": {
     "build": "rm -rf dist && webpack --mode production",

lerna.json

@@ -1,4 +1,4 @@
 {
   "npmClient": "yarn",
-  "version": "0.2.0"
+  "version": "0.3.0"
 }

packages/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flashcatcloud/browser-core",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "license": "Apache-2.0",
   "main": "cjs/index.js",
   "module": "esm/index.js",

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

@@ -665,7 +665,7 @@ describe('startSessionManager', () => {
       const sessionManager = startSessionManagerWithDefaults()
       sessionManager.sessionStateUpdateObservable.subscribe(sessionStateUpdateSpy)
 
-      sessionManager.updateSessionState({ extra: 'extra' })
+      sessionManager.updateSessionState(() => ({ extra: 'extra' }))
 
       expectSessionIdToBeDefined(sessionManager)
       expect(sessionStateUpdateSpy).toHaveBeenCalledTimes(1)

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

@@ -20,13 +20,19 @@ export interface SessionManager<TrackingType extends string> {
   expireObservable: Observable<void>
   sessionStateUpdateObservable: Observable<{ previousState: SessionState; newState: SessionState }>
   expire: () => void
-  updateSessionState: (state: Partial<SessionState>) => void
+  updateSessionState: (update: (state: SessionState) => Partial<SessionState> | undefined) => void
 }
 
 export interface SessionContext<TrackingType extends string> extends Context {
   id: string
   trackingType: TrackingType
   isReplayForced: boolean
+  /**
+   * Whether an error has already been reported during this session. Persisted in the session store
+   * so it survives page navigation: an error session must not go back to withholding its replay
+   * just because the user moved to another page.
+   */
+  hasError: boolean
   anonymousId: string | undefined
 }
 
@@ -92,6 +98,7 @@ export function startSessionManager<TrackingType extends string>(
       id: sessionStore.getSession().id!,
       trackingType: sessionStore.getSession()[productKey] as TrackingType,
       isReplayForced: !!sessionStore.getSession().forcedReplay,
+      hasError: !!sessionStore.getSession().hasError,
       anonymousId: sessionStore.getSession().anonymousId,
     }
   }

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

@@ -596,7 +596,7 @@ describe('session store', () => {
       sessionStoreManager = setupSessionStore(updateSpy)
       otherSessionStoreManager = setupSessionStore(otherUpdateSpy)
 
-      sessionStoreManager.updateSessionState({ extra: 'extra' })
+      sessionStoreManager.updateSessionState(() => ({ extra: 'extra' }))
 
       expect(updateSpy).toHaveBeenCalledTimes(1)
 

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

@@ -29,7 +29,12 @@ export interface SessionStore {
   sessionStateUpdateObservable: Observable<{ previousState: SessionState; newState: SessionState }>
   expire: () => void
   stop: () => void
-  updateSessionState: (state: Partial<SessionState>) => void
+  /**
+   * Applies a change to the stored session under the store lock. The producer sees the state the
+   * change would land on and returns `undefined` to make it a no-op - which is how a write meant for
+   * one session avoids landing on the one that replaced it while the write was waiting for the lock.
+   */
+  updateSessionState: (update: (state: SessionState) => Partial<SessionState> | undefined) => void
 }
 
 /**
@@ -216,10 +221,13 @@ export function startSessionStore<TrackingType extends string>(
     renewObservable.notify()
   }
 
-  function updateSessionState(partialSessionState: Partial<SessionState>) {
+  function updateSessionState(update: (state: SessionState) => Partial<SessionState> | undefined) {
     processSessionStoreOperations(
       {
-        process: (sessionState) => ({ ...sessionState, ...partialSessionState }),
+        process: (sessionState) => {
+          const partialSessionState = update(sessionState)
+          return partialSessionState && { ...sessionState, ...partialSessionState }
+        },
         after: synchronizeSession,
       },
       sessionStoreStrategy

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

@@ -1,3 +1,4 @@
+import { startFakeTelemetry } from '../telemetry'
 import type { MockStorage } from '../../../test'
 import { mockClock, mockCookie, mockLocalStorage } from '../../../test'
 import type { CookieOptions } from '../../browser/cookie'
@@ -232,6 +233,7 @@ const DEFAULT_INIT_CONFIGURATION = { trackAnonymousUser: true } as Configuration
 
       it('should abort after a max number of retry', () => {
         const clock = mockClock()
+        const telemetry = startFakeTelemetry()
 
         sessionStoreStrategy.persistSession(initialSession)
         storage.setSpy.calls.reset()
@@ -246,6 +248,7 @@ const DEFAULT_INIT_CONFIGURATION = { trackAnonymousUser: true } as Configuration
         expect(processSpy).not.toHaveBeenCalled()
         expect(afterSpy).not.toHaveBeenCalled()
         expect(storage.setSpy).not.toHaveBeenCalled()
+        expect(telemetry).toContain(jasmine.objectContaining({ message: 'Session store lock retries exhausted' }))
 
         clock.cleanup()
       })

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

@@ -1,3 +1,4 @@
+import { addTelemetryDebug } from '../telemetry'
 import { setTimeout } from '../../tools/timer'
 import { generateUUID } from '../../tools/utils/stringUtils'
 import type { SessionStoreStrategy } from './storeStrategies/sessionStoreStrategy'
@@ -43,6 +44,7 @@ export function processSessionStoreOperations(
     return
   }
   if (isLockEnabled && numberOfRetries >= LOCK_MAX_TRIES) {
+    addTelemetryDebug('Session store lock retries exhausted', { retries: numberOfRetries })
     next(sessionStoreStrategy)
     return
   }

packages/core/src/domain/telemetry/telemetry.ts

@@ -4,7 +4,9 @@ import { NO_ERROR_STACK_PRESENT_MESSAGE, isError } from '../error/error'
 import { toStackTraceString } from '../../tools/stackTrace/handlingStack'
 import { getExperimentalFeatures } from '../../tools/experimentalFeatures'
 import type { Configuration } from '../configuration'
-import { INTAKE_SITE_STAGING } from '../configuration'
+// Import the constant without loading configuration construction, which uses session storage.
+// eslint-disable-next-line local-rules/disallow-protected-directory-import
+import { INTAKE_SITE_STAGING } from '../configuration/intakeSites'
 import { Observable } from '../../tools/observable'
 import { timeStampNow } from '../../tools/utils/timeUtils'
 import { displayIfDebugEnabled, startMonitorErrorCollection } from '../../tools/monitor'

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/flagging/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flashcatcloud/browser-flagging",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "license": "Apache-2.0",
   "private": true,
   "main": "cjs/entries/main.js",
@@ -18,7 +18,7 @@
     "@flashcatcloud/browser-core": "workspace:*"
   },
   "peerDependencies": {
-    "@flashcatcloud/browser-rum": "0.2.0"
+    "@flashcatcloud/browser-rum": "0.3.0"
   },
   "peerDependenciesMeta": {
     "@flashcatcloud/browser-rum": {

packages/logs/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flashcatcloud/browser-logs",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "license": "Apache-2.0",
   "main": "cjs/entries/main.js",
   "module": "esm/entries/main.js",
@@ -17,7 +17,7 @@
     "@flashcatcloud/browser-core": "workspace:*"
   },
   "peerDependencies": {
-    "@flashcatcloud/browser-rum": "0.2.0"
+    "@flashcatcloud/browser-rum": "0.3.0"
   },
   "peerDependenciesMeta": {
     "@flashcatcloud/browser-rum": {

packages/rum-core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flashcatcloud/browser-rum-core",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "license": "Apache-2.0",
   "main": "cjs/index.js",
   "module": "esm/index.js",