feat(session-replay-browser): add flushIntervalConfig to tune rrweb event-split cadence

[lewgordon-amplitude]

Summary

Adds flushIntervalConfig: { minIntervalMs, maxIntervalMs } to SessionReplayLocalConfig so customers (or specific deployments) can raise the rrweb event-split cadence without waiting on an SDK upgrade.

Context

Even after SR-4280 landed (honoring X-Session-Replay-Event-Skipped server back-pressure), we're still seeing significant 200+throttle traffic on v1.30.2. Walking the splitting logic (BaseEventsStore.shouldSplitEventsList) explains why:

• The interval starts at MIN_INTERVAL = 500ms and grows by 500ms after each split, capped at MAX_INTERVAL = 10s.
• A busy session fires roughly 10 batches in the first 30 seconds before settling at 6/min — comparable to 1.5 minutes of steady-state traffic packed into the first half-minute.
• All of that happens before the first server response can arrive, so SR-4280's flushPauseUntilMs doesn't dampen the upfront burst. The throttle pause only affects the next schedule, not in-flight or already-queued contexts.
• flushPauseUntilMs and killedSessions are in-memory and per-instance, so every fresh page load / SDK init repeats the burst from scratch.

This PR doesn't touch the defaults — it just exposes the knob. We can roll out higher values for specific high-volume customers (or recommend tuning for self-hosted standalone integrations) without shipping a behavior change to everyone.

What's in here

• flushIntervalConfig?: FlushIntervalConfig on SessionReplayLocalConfig, with minIntervalMs and maxIntervalMs fields (both optional).
• Validation in SessionReplayLocalConfig — clamps non-finite or sub-100ms values, raises max to match min if a caller inverts them, warns via the configured logger.
• Wires the values into createEventsManager('replay') (the interaction manager already had its own INTERACTION_MIN_INTERVAL plumbing).
• New test/config/local-config.test.ts covering defaults, custom values, clamping, and inversion.
• New tests in session-replay.test.ts verifying the values flow into createEventsManager.

Test plan

• pnpm --filter @amplitude/session-replay-browser build — clean
• npx jest --testPathIgnorePatterns=e2e — 915/915 pass, 100% coverage
• pnpm lint:eslint / pnpm lint:prettier — clean (warnings are pre-existing, unrelated files)
• Try a higher minIntervalMs (e.g., 3000ms) on a heavy-traffic test page and confirm the early-burst request count drops as expected

Follow-ups (not in this PR)

• Bumping default MIN_INTERVAL once we have data on customer impact of the new knob.
• Persisting flushPauseUntilMs / killedSessions to localStorage keyed by API key, so cold starts honor the server's last directive instead of re-discovering it.
• Exposing this via remote config so backend ops can dial cadence per-org.

🤖 Generated with Claude Code

---

Note

Medium Risk
Introduces new customer-facing tuning for replay flush cadence and fixes a timing initialization regression that affects when the first event split occurs, which can change request patterns in production. Changes are guarded behind optional config but touch core event batching/splitting behavior.

Overview
Adds flushIntervalConfig (minIntervalMs/maxIntervalMs) to SessionReplayLocalConfig to let callers tune rrweb event-split/flush cadence, including sanitization (100ms floor, Infinity support for max, and min/max cross-validation with warnings).

Wires the config through SessionReplay into createEventsManager('replay'), and fixes BaseEventsStore so the first split interval correctly honors caller-supplied minInterval (not the class-field default).

Adds unit/integration coverage for the validator and forwarding behavior, plus Playwright e2e tests and a configurable Playwright baseURL; updates the SR capture test page to accept interval params via querystring.

^{Reviewed by Cursor Bugbot for commit ce43e66. Bugbot is set up for automated code reviews on this repo. Configure here.}

[github-actions]

Session Replay Browser E2E Results

 119 passed

Details

 119 tests across 11 suites
 2 minutes, 45 seconds
 ce43e66

[lewgordon-amplitude]

bugbot run

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

1 issue from previous review remains unresolved.

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit c1d3f4e. Configure here.}

[lewgordon-amplitude]

bugbot run

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

Autofix Details

Bugbot Autofix prepared a fix for the issue found in the latest run.

• ✅ Fixed: Infinity for maxIntervalMs clamps to floor, creating maximum aggression
  • Separated non-finite value handling to clamp Infinity to MAX_INTERVAL instead of MIN_FLUSH_INTERVAL_FLOOR_MS, preserving the intent of 'no cap' for maximum intervals.

Or push these changes by commenting:

@cursor push 9407c5a6ac

Preview (9407c5a6ac)

diff --git a/packages/session-replay-browser/src/config/local-config.ts b/packages/session-replay-browser/src/config/local-config.ts
--- a/packages/session-replay-browser/src/config/local-config.ts
+++ b/packages/session-replay-browser/src/config/local-config.ts
@@ -134,8 +134,15 @@
     }
   }
   if (raw.maxIntervalMs !== undefined) {
-    if (!Number.isFinite(raw.maxIntervalMs) || raw.maxIntervalMs < MIN_FLUSH_INTERVAL_FLOOR_MS) {
+    if (!Number.isFinite(raw.maxIntervalMs)) {
+      // For maxIntervalMs, Infinity means "no cap" — clamp to MAX_INTERVAL to preserve that intent.
+      // NaN is invalid and also gets the large-default treatment for a maximum bound.
       loggerProvider.warn(
+        `flushIntervalConfig.maxIntervalMs ${raw.maxIntervalMs} is not finite; clamping to ${MAX_INTERVAL}ms.`,
+      );
+      sanitized.maxIntervalMs = MAX_INTERVAL;
+    } else if (raw.maxIntervalMs < MIN_FLUSH_INTERVAL_FLOOR_MS) {
+      loggerProvider.warn(
         `flushIntervalConfig.maxIntervalMs ${raw.maxIntervalMs} is below floor ${MIN_FLUSH_INTERVAL_FLOOR_MS}ms; clamping.`,
       );
       sanitized.maxIntervalMs = MIN_FLUSH_INTERVAL_FLOOR_MS;

_{You can send follow-ups to the cloud agent here.}

[lewgordon-amplitude]

bugbot run

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit c5d8d09. Configure here.}