feat: add local sampleRate config for session recording (#3169)

Author: marandaneto

.changeset/tidy-bats-like.md

@@ -0,0 +1,6 @@
+---
+'posthog-js': minor
+'@posthog/types': minor
+---
+
+feat: add local sampleRate config for session recording

packages/browser/src/__tests__/extensions/replay/sessionRecording-onRemoteConfig.test.ts

@@ -361,6 +361,71 @@ describe('SessionRecording', () => {
             expect(sessionRecording['_lazyLoadedSessionRecording']['_sampleRate']).toBe(0.7)
         })
 
+        it('local sampleRate takes precedence over remote config', () => {
+            posthog.config.session_recording.sampleRate = 0.3
+
+            sessionRecording.onRemoteConfig(
+                makeFlagsResponse({
+                    sessionRecording: { endpoint: '/s/', sampleRate: '0.70' },
+                })
+            )
+
+            expect(posthog.get_property(SESSION_RECORDING_REMOTE_CONFIG).sampleRate).toBe(0.3)
+            expect(sessionRecording['_lazyLoadedSessionRecording']['_sampleRate']).toBe(0.3)
+        })
+
+        it('local sampleRate of 0 takes precedence over remote config', () => {
+            posthog.config.session_recording.sampleRate = 0
+
+            sessionRecording.onRemoteConfig(
+                makeFlagsResponse({
+                    sessionRecording: { endpoint: '/s/', sampleRate: '0.70' },
+                })
+            )
+
+            expect(posthog.get_property(SESSION_RECORDING_REMOTE_CONFIG).sampleRate).toBe(0)
+            expect(sessionRecording['_lazyLoadedSessionRecording']['_sampleRate']).toBe(0)
+        })
+
+        it('falls back to remote config when local sampleRate is undefined', () => {
+            posthog.config.session_recording.sampleRate = undefined
+
+            sessionRecording.onRemoteConfig(
+                makeFlagsResponse({
+                    sessionRecording: { endpoint: '/s/', sampleRate: '0.50' },
+                })
+            )
+
+            expect(posthog.get_property(SESSION_RECORDING_REMOTE_CONFIG).sampleRate).toBe(0.5)
+            expect(sessionRecording['_lazyLoadedSessionRecording']['_sampleRate']).toBe(0.5)
+        })
+
+        it('ignores local sampleRate greater than 1 and falls back to remote config', () => {
+            posthog.config.session_recording.sampleRate = 1.5
+
+            sessionRecording.onRemoteConfig(
+                makeFlagsResponse({
+                    sessionRecording: { endpoint: '/s/', sampleRate: '0.70' },
+                })
+            )
+
+            expect(posthog.get_property(SESSION_RECORDING_REMOTE_CONFIG).sampleRate).toBe(0.7)
+            expect(sessionRecording['_lazyLoadedSessionRecording']['_sampleRate']).toBe(0.7)
+        })
+
+        it('ignores local sampleRate less than 0 and falls back to remote config', () => {
+            posthog.config.session_recording.sampleRate = -0.5
+
+            sessionRecording.onRemoteConfig(
+                makeFlagsResponse({
+                    sessionRecording: { endpoint: '/s/', sampleRate: '0.70' },
+                })
+            )
+
+            expect(posthog.get_property(SESSION_RECORDING_REMOTE_CONFIG).sampleRate).toBe(0.7)
+            expect(sessionRecording['_lazyLoadedSessionRecording']['_sampleRate']).toBe(0.7)
+        })
+
         it('starts session recording, saves setting and endpoint when enabled', () => {
             posthog.persistence?.register({ [SESSION_RECORDING_REMOTE_CONFIG]: undefined })
             sessionRecording.onRemoteConfig(

packages/browser/src/extensions/replay/session-recording.ts

@@ -148,6 +148,18 @@ export class SessionRecording {
         this._instance.persistence?.unregister(SESSION_RECORDING_IS_SAMPLED)
     }
 
+    private _validateSampleRate(rate: unknown, source: string): number | null {
+        if (isNullish(rate)) {
+            return null
+        }
+        const parsed = parseFloat(rate as string)
+        if (isNaN(parsed) || parsed < 0 || parsed > 1) {
+            logger.warn(`${source} must be between 0 and 1. Ignoring invalid value:`, rate)
+            return null
+        }
+        return parsed
+    }
+
     private _persistRemoteConfig(response: RemoteConfig): void {
         if (this._instance.persistence) {
             const persistence = this._instance.persistence
@@ -156,9 +168,15 @@ export class SessionRecording {
                 const sessionRecordingConfigResponse =
                     response.sessionRecording === false ? undefined : response.sessionRecording
 
-                const receivedSampleRate = sessionRecordingConfigResponse?.sampleRate
-
-                const parsedSampleRate = isNullish(receivedSampleRate) ? null : parseFloat(receivedSampleRate)
+                const localSampleRate = this._validateSampleRate(
+                    this._instance.config.session_recording?.sampleRate,
+                    'session_recording.sampleRate'
+                )
+                const remoteSampleRate = this._validateSampleRate(
+                    sessionRecordingConfigResponse?.sampleRate,
+                    'remote config sampleRate'
+                )
+                const parsedSampleRate = localSampleRate ?? remoteSampleRate
                 if (isNullish(parsedSampleRate)) {
                     this._resetSampling()
                 }

packages/types/src/__tests__/__snapshots__/config-snapshot.spec.ts.snap

@@ -411,6 +411,10 @@ exports[`config snapshot for PostHogConfig 1`] = `
       "undefined",
       "false",
       "true"
+    ],
+    "sampleRate": [
+      "undefined",
+      "number"
     ]
   },
   "error_tracking": {

packages/types/src/posthog-config.ts

@@ -527,6 +527,17 @@ export interface SessionRecordingOptions {
      * @default false
      */
     strictMinimumDuration?: boolean
+
+    /**
+     * The sample rate for session recordings, a number between 0 and 1.
+     * For example, 0.5 means roughly 50% of sessions will be recorded.
+     *
+     * When `undefined`, falls back to the remote config setting.
+     * When set, takes precedence over the remote config.
+     *
+     * @default undefined
+     */
+    sampleRate?: number
 }
 
 // we used to call a request that was sent to the queue with options attached `RequestQueueOptions`
@@ -867,6 +878,9 @@ export interface PostHogConfig {
 
     /**
      * Determines whether PostHog should enable recording console logs.
+     *
+     * This is related to the Session Recording feature. For more session recording
+     * settings, see the `session_recording` and `capture_performance` configuration option.
      * When undefined, it falls back to the remote config setting.
      *
      * @default undefined
@@ -1017,6 +1031,8 @@ export interface PostHogConfig {
     /**
      * Determines the session recording options.
      *
+     * For more session recording settings, see the `enable_recording_console_log` and `capture_performance` configuration option.
+     *
      * @see `SessionRecordingOptions`
      * @default {}
      */
@@ -1246,7 +1262,10 @@ export interface PostHogConfig {
 
     /**
      * Determines whether to capture performance metrics.
-     * These include Network Timing and Web Vitals.
+     * These include Network Timing for Session Replay and Web Vitals.
+     *
+     * The `network_timing` option is only used by the Session Replay feature.
+     * For more session recording settings, see the `session_recording` and `enable_recording_console_log` configuration option.
      *
      * When `undefined`, fallback to the remote configuration.
      * If `false`, neither network timing nor web vitals will work.