Skip to content

fix: buffer session replay snapshots until first remote config resolves - #590

Merged
ioannisj merged 12 commits into
mainfrom
fix/respect-replay-flag-after-config
Jul 2, 2026
Merged

ioannisj merged 12 commits into
mainfrom
fix/respect-replay-flag-after-config

Conversation

@ioannisj

@ioannisj ioannisj commented Jun 26, 2026 •

Copy link
Copy Markdown
Contributor

💡 Motivation and Context

Session replay starts at cold start from the disk-cached sessionRecording config, set before any network call. Remote-config resolution is async, so when the cached decision disagrees with the freshly-fetched config (cached-on, fresh-off) there is a stale-cache window where the SDK records — and uploads — a session the fresh config disallows. Fresh installs are already safe, so this is a returning-user bug. There was also a latent gap where a mid-session fresh "off" only took effect at the next session rotation.

This is the Android slice of a multi-target session-replay fix (iOS counterpart: PostHog/posthog-ios#679). Tracking issue: #575.

Recording still starts optimistically off the cached value, but snapshots are buffered (not persisted, not sent) until the first live remote config resolves; on resolve the buffered window migrates to the replay queue only if the current session is recordable under the fresh config, and is dropped otherwise. No stale-cache $snapshot reaches the persisted queue or the network.

What changed

Buffer-and-decide gate (PostHogReplayIntegration)

  • An awaitingFirstRemoteConfig gate (guarded by bufferingLock) routes captured snapshots into the in-memory buffer until the first /config attempt resolves, then disarms exactly once. The gate is only armed when a remote-config fetch will actually happen — if neither remoteConfig nor preloadFeatureFlags is enabled, nothing would ever resolve it, so it stays disarmed and snapshots persist normally.
  • The minimum-duration migrate trigger is suppressed while the gate is armed, so a cached minimumDuration can't drain stale-cache frames to the persisted queue before the fresh decision lands. A snapshot that reaches the persist boundary while replay is inactive is dropped rather than enqueued.

Resolve uses the full recordability decision, not just the flag

  • On resolve, the buffered window migrates only when the session is recordable under the fresh config — recording flag on and sampled in for the current session id and not waiting on an event trigger. A sampled-out or trigger-gated session drops the window instead of uploading it.
  • Migration is handed to the existing minimum-duration gate rather than force-flushed: a short opening window keeps buffering until it spans minimumDuration.
  • A not-recordable resolve runs stop → clear buffer → disarm in that order, so an in-flight add() racing the disarm finds the buffer cleared and replay inactive and drops its snapshot.

linkedFlag handling — single-callback on Android

  • Unlike iOS (which gets a separate /flags callback after /config and defers the resolve to it), Android's loadRemoteConfig loads /flags nested and synchronously (notifyRemoteConfigLoaded = false) and fires exactly one onRemoteConfig. The linked flag is already merged and fresh at that single callback, so Android resolves the buffer there directly. There is no second callback to defer to, and deferring would leave the gate armed for the whole session (silently buffering, never sending). This is the one place the Android realization intentionally diverges from the iOS deferral.

Mid-session re-evaluation

  • After the gate disarms, onRemoteConfig re-evaluates recording: a subsequent config that turns recording off stops it promptly instead of waiting for session rotation; one that turns it back on resumes recording for the current session. stopIfActive flips the active flag synchronously before posting stop(), so a concurrent add() can't persist a snapshot after the off decision.

Concurrency / reset

  • A bufferingGeneration counter lets an in-flight resolve detect a concurrent session rotation (reset() / identity change re-arming and clearing the buffer) and no-op instead of migrating or clearing the wrong session's window.
  • The gate re-resolves from the cached config after reset() on the next /flags reload, so the post-reset opening window isn't dropped.

Failure / quota paths (PostHogRemoteConfig)

  • A failed first /config (offline launch) falls back to the disk-cached decision and emits a single fallback log line.
  • A quota-limited /flags response resolves via the not-recordable path (a live response, not a fetch failure) and re-arms the session-recording / error-tracking / capture-performance decisions from the cached config instead of losing them.
  • Tracks whether the live config resolved for the current identity via hasRemoteConfigFetched(), reset on clear().

The in-memory buffer is intentionally not size-capped — replay needs the complete opening snapshot sequence, so a frame-dropping cap would migrate an unplayable partial window. A slow or absent /config can grow it until the config resolves; it is bounded by session activity and self-heals on the next resolution.

💚 How did you test it?

Unit tests (./gradlew :posthog:test :posthog-android:testDebugUnitTest :posthog-android:testReleaseUnitTest spotlessCheck apiCheck — all green), covering the gate lifecycle in PostHogReplayIntegrationTest and the remote-config paths in PostHogRemoteConfigTest / PostHogTest:

  • while awaiting the first config, add() routes snapshots to the buffer, not the persisted queue;
  • a single onRemoteConfig delivery resolves the gate — flag-on migrates the buffered window, and a snapshot added afterwards persists directly (no second callback needed);
  • flag-off clears the buffer and stops recording, leaving already-persisted events untouched (clearBuffer scoping);
  • a minimum-duration-elapsed event while awaiting the first config does not migrate (suppression while armed);
  • mid-session flag-off stops recording synchronously — a snapshot added before the posted stop() runs is not persisted;
  • a subsequent config resumes recording once the config is already fetched;
  • the gate does not arm when neither remoteConfig nor preloadFeatureFlags will fetch;
  • hasRemoteConfigFetched() flips true on both the /config and /flags paths and resets on clear(); a quota-limited flags reload resolves and notifies.

Manual runs on the sample app against a local mock server that flips the configs. No manual on-device testing was performed.

📝 Checklist

  • I reviewed the submitted code.
  • I added tests to verify the changes.
  • I updated the docs if needed.
  • No breaking change or entry added to the changelog.

If releasing new changes

  • Ran pnpm changeset to generate a changeset file

🤖 Agent context

DRI: @ioannisj
Autonomy: Human-driven (agent-assisted)

@ioannisj ioannisj self-assigned this Jun 26, 2026
@github-actions

github-actions Bot commented Jun 26, 2026 •

Copy link
Copy Markdown
Contributor

posthog-android Compliance Report

Date: 2026-07-02 10:00:45 UTC
Duration: 117710ms

✅ All Tests Passed!

45/45 tests passed


Capture Tests

✅ 29/29 tests passed

View Details
Test Status Duration
Format Validation.Event Has Required Fields ✅ 383ms
Format Validation.Event Has Uuid ✅ 27ms
Format Validation.Event Has Lib Properties ✅ 27ms
Format Validation.Distinct Id Is String ✅ 22ms
Format Validation.Token Is Present ✅ 23ms
Format Validation.Custom Properties Preserved ✅ 23ms
Format Validation.Event Has Timestamp ✅ 21ms
Retry Behavior.Retries On 503 ✅ 7025ms
Retry Behavior.Does Not Retry On 400 ✅ 4022ms
Retry Behavior.Does Not Retry On 401 ✅ 4024ms
Retry Behavior.Respects Retry After Header ✅ 7026ms
Retry Behavior.Implements Backoff ✅ 17032ms
Retry Behavior.Retries On 500 ✅ 7019ms
Retry Behavior.Retries On 502 ✅ 7018ms
Retry Behavior.Retries On 504 ✅ 7019ms
Retry Behavior.Max Retries Respected ✅ 17035ms
Deduplication.Generates Unique Uuids ✅ 36ms
Deduplication.Preserves Uuid On Retry ✅ 7017ms
Deduplication.Preserves Uuid And Timestamp On Retry ✅ 12029ms
Deduplication.Preserves Uuid And Timestamp On Batch Retry ✅ 7018ms
Deduplication.No Duplicate Events In Batch ✅ 35ms
Deduplication.Different Events Have Different Uuids ✅ 22ms
Compression.Sends Gzip When Enabled ✅ 26ms
Batch Format.Uses Proper Batch Structure ✅ 18ms
Batch Format.Flush With No Events Sends Nothing ✅ 10ms
Batch Format.Multiple Events Batched Together ✅ 29ms
Error Handling.Does Not Retry On 403 ✅ 4018ms
Error Handling.Does Not Retry On 413 ✅ 4020ms
Error Handling.Retries On 408 ✅ 5025ms

Feature_Flags Tests

✅ 16/16 tests passed

View Details
Test Status Duration
Request Payload.Request With Person Properties Device Id ✅ 31ms
Request Payload.Flags Request Uses V2 Query Param ✅ 20ms
Request Payload.Flags Request Hits Flags Path Not Decide ✅ 22ms
Request Payload.Flags Request Omits Authorization Header ✅ 29ms
Request Payload.Token In Flags Body Matches Init ✅ 20ms
Request Payload.Groups Round Trip ✅ 18ms
Request Payload.Groups Default To Empty Object ✅ 18ms
Request Payload.Person Properties Distinct Id Auto Populated When Caller Omits It ✅ 24ms
Request Payload.Disable Geoip False Propagates As Geoip Disable False ✅ 26ms
Request Payload.Disable Geoip Omitted Defaults To False ✅ 22ms
Request Payload.Flag Keys To Evaluate Contains Only Requested Key ✅ 23ms
Request Lifecycle.No Flags Request On Init Alone ✅ 9ms
Request Lifecycle.No Flags Request On Normal Capture ✅ 27ms
Request Lifecycle.Two Flag Calls Produce Two Remote Requests ✅ 34ms
Request Lifecycle.Mock Response Value Is Returned To Caller ✅ 19ms
Side Effect Events.Get Feature Flag Captures Feature Flag Called Event ✅ 19ms

@greptile-apps

greptile-apps Bot commented Jun 26, 2026 •

Copy link
Copy Markdown
Contributor

Comments Outside Diff (1)

  1. posthog/src/test/java/com/posthog/internal/PostHogRemoteConfigTest.kt, line 99-148 (link)

    P2 Two nearly-identical tests should be parameterised

    hasRemoteConfigFetched flips true on a flags reload and resets on clear and hasRemoteConfigFetched flips true on a remote config load share the same assertion shape: start false, trigger a load, assert true, clear, assert false. The only difference is the load trigger (loadFeatureFlags vs loadRemoteConfig). Per the project's preference for parameterised tests, these could be collapsed into a single @ParameterizedTest that covers both resolution paths, reducing duplication while keeping full coverage.

    Context Used: Do not attempt to comment on incorrect alphabetica... (source)

    Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

Reviews (1): Last reviewed commit: "fix: respect session replay remote confi..." | Re-trigger Greptile

@ioannisj
ioannisj marked this pull request as ready for review June 26, 2026 14:08
@ioannisj
ioannisj requested a review from a team as a code owner June 26, 2026 14:08
@greptile-apps

greptile-apps Bot commented Jun 26, 2026

Copy link
Copy Markdown
Contributor

Reviews (2): Last reviewed commit: "fix: keep session replay opening window ..." | Re-trigger Greptile

@ioannisj ioannisj changed the title fix: respect session replay remote config flag at cold start fix: buffer session replay snapshots until first remote config resolves Jun 26, 2026
@ioannisj
ioannisj marked this pull request as draft June 26, 2026 18:21
@turnipdabeets
turnipdabeets requested a review from a team June 27, 2026 23:39
@ioannisj
ioannisj force-pushed the fix/respect-replay-flag-after-config branch from a03f9b9 to b202c07 Compare July 1, 2026 18:11
@ioannisj
ioannisj marked this pull request as ready for review July 1, 2026 18:12
@greptile-apps

greptile-apps Bot commented Jul 1, 2026

Copy link
Copy Markdown
Contributor

Reviews (3): Last reviewed commit: "fix: resolve session replay buffer on th..." | Re-trigger Greptile

@ioannisj
ioannisj requested a review from turnipdabeets July 2, 2026 08:20
@marandaneto

Copy link
Copy Markdown
Member

We have the same issue with error tracking, surveys, etc, everything that depends on remote config, right?
we should open new issues for those if not fixing right away

@ioannisj

ioannisj commented Jul 2, 2026

Copy link
Copy Markdown
Contributor Author

We have the same issue with error tracking, surveys, etc, everything that depends on remote config, right? we should open new issues for those if not fixing right away

Yeah I'll do a rundown later today on this and open some issues if needed

@ioannisj
ioannisj merged commit 77aa107 into main Jul 2, 2026
16 checks passed
@ioannisj
ioannisj deleted the fix/respect-replay-flag-after-config branch July 2, 2026 10:19
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants