Skip to content

fix(replay): Keep the replay timeline anchored across wall-clock jumps - #6542

Open
runningcode wants to merge 9 commits into
mainfrom
no/java-829-replay-anchored-clock
Open

runningcode wants to merge 9 commits into
mainfrom
no/java-829-replay-anchored-clock

Conversation

@runningcode

@runningcode runningcode commented Nov 10, 2026 •

Copy link
Copy Markdown
Contributor

📜 Description

Session Replay stamped frames, segment boundaries, the buffer window and touches with the wall clock, so changing the device clock mid-recording broke the video. A backward change dropped frames until the clock caught up, a forward change cut a frozen 5s segment on every frame, and buffer mode could produce negative durations or rotate out the whole buffer.

Each recording now stamps on one AnchoredClock, held by a new internal ReplayClock. Every captured frame compares it with the wall clock. When the two differ by more than 1s, the current segment closes where the old timeline ended and the next one starts on a new anchor at the wall clock. Breadcrumbs and errors, which are still stamped from the wall clock, stay aligned with the video, and the jump shows once in the replay as a gap or an overlap.

For example, when the clock is set back 2 minutes mid-segment:

wall clock   10:00:00 ──────────────── 10:00:07 ⟲ 09:58:07 ─────────────▶
                                       (clock set back 2 min)
segments     [ seg 0  10:00:00–:05 ][ seg 1  :05–:07 ][ seg 2  09:58:07–…
             └──────── old timeline ─────────────────┘└── new timeline ──

What each frame does:

on each frame (screenshot thread), under timelineLock:
  if wall clock and replay clock differ by > 1s:
    oldEnd = replayClock.now()
    re-anchor replayClock on the wall clock
    start a new touch-event queue
  stamp = replayClock.now()

then on replayExecutor:
  if the frame re-anchored:
    close the current segment at oldEnd (with the old touches)
    start the next segment at stamp; drop old-timeline frames left in the cache
  store the frame at stamp

Without a jump, every serialized value is what the wall clock gives today, within 1ms. Stamps stay epoch millis, so the frame cache on disk and crash recovery are unchanged.

Behavior worth a look: a forward jump longer than sessionDuration (1h) ends a session-mode recording, as reaching the cap does. Buffer mode keeps recording but drops what it buffered before the jump, so a later error doesn't send a replay spanning hours or years.

Concurrency

  • timelineLock makes the jump check, the re-anchor and starting a new touch-event queue one step. It is never held across submit, an SDK call or the logger.
  • A segment request that raced a jump re-reads its times on executorTimeline, the timeline the executor's queued work is on, and keeps the old timeline's touches.

Compatibility: no public API change. Every constructor keeps its ICurrentDateProvider (sentry-dart calls the 4-arg ReplayIntegration constructor), which becomes the anchor's wall clock.

Not addressed here: the player lagging on the overlap after a backward jump, buffer-mode crash recovery after a jump (only the frames after it are recovered), and caller-supplied stamps in onScreenshotRecorded(File, Long).

💡 Motivation and Context

📝 Checklist

  • I added GH Issue ID & Linear ID
  • I added tests to verify the changes.
  • No new PII added or SDK only sends newly added PII if sendDefaultPII is enabled.
  • I updated the docs if needed.
  • I updated the wizard if needed.
  • Review from the native team if needed.
  • No breaking change or entry added to the changelog.
  • No breaking change for hybrid SDKs or communicated to hybrid SDKs.
  • Public API changes reviewed by another Mobile SDK team member or implemented according to the develop docs spec.

🔮 Next steps

  • Remove ICurrentDateProvider from the replay strategies in v9 (JAVA-827).

🤖 Generated with Claude Code

@linear-code

linear-code Bot commented Nov 10, 2026

Copy link
Copy Markdown

JAVA-829

@sentry

sentry Bot commented Nov 10, 2026 •

Copy link
Copy Markdown

📲 Install Builds

Android

🔗 App Name App ID Version Configuration
SDK Size io.sentry.tests.size 8.64.0 (1) release

⚙️ sentry-android Build Distribution Settings

@runningcode
runningcode force-pushed the no/java-829-replay-anchored-clock branch from ee1e8b3 to 76e20a4 Compare November 16, 2026 13:57
@runningcode
runningcode marked this pull request as ready for review November 16, 2026 13:59
@runningcode
runningcode requested review from a team and adinauer as code owners November 16, 2026 13:59
@runningcode
runningcode requested review from 0xadam-brown and markushi and removed request for a team November 16, 2026 13:59
@github-actions github-actions Bot added the risk: medium PR risk score: medium label Nov 16, 2026

@cursor cursor Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Stale Bugbot comment from a previous run.

runningcode and others added 7 commits November 17, 2026 11:02
Session Replay stamped frames, cut segments, trimmed the buffer and
stamped gestures from repeated wall-clock reads. A device clock change
mid-recording then dropped frames (backward) or sent one frozen 5s
segment per frame until the segment start caught up (forward); buffer
mode got negative durations or rotated out the whole buffer.

Each recording now stamps on an AnchoredClock (ReplayClock). Every
captured frame compares it with the wall clock; past a 1s tolerance the
current segment closes where the old timeline ended and the next one
starts on a new anchor, so the jump shows once as a gap or an overlap
and breadcrumbs, errors and spans stay aligned with the video. Touch
events stamped on the old timeline go into the closing segment. A
forward jump longer than sessionDuration stops a session recording the
way the cap does. Buffered segments age on the timeline they were
stamped on. Without a jump, every serialized value matches the wall
clock as before.

Fixes GH-6522
Fixes JAVA-829

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ent requests

Buffer mode now drops what it recorded before a forward wall-clock jump
longer than sessionDuration: the pre-jump frames, touch events and
already buffered segments. It keeps recording on the new timeline, so an
error soon after no longer sends one replay spanning hours or years.
Session mode already stops at the same jump.

Segment requests (pause, flush, stop, configuration change, error flush)
read their times when made, so a busy executor doesn't stretch the
segment. If a frame moved the recording onto a new timeline in between,
those times and the frames the task finds were on different timelines:
a backward jump could produce a frozen segment minutes long, and a
buffer flush right after a forward jump could stretch one frame over the
whole jump. The strategies now track the timeline their queued work is
on, and a request's task reads its times again on that timeline when it
differs from the one the request read. Without a jump nothing is re-read,
so every value stays what it was.

resume() no longer re-anchors the clock. Otherwise every request until
its queued task runs would look like it raced a jump. A jump while
paused is followed by the first frame after resume, like any other.

Refs GH-6522
Refs JAVA-829

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The function references and generateSequence pulled in
kotlin.jvm.internal.FunctionReferenceImpl and kotlin.sequences.SequencesKt,
which R8 reports as missing in the SDK size app. A lambda and a plain loop
keep replay's Kotlin stdlib footprint as it was.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… jump

A frame that followed a jump drained every queued touch event into the
segment closing the old timeline at stamp time. A segment task already
queued before it, such as a 5s boundary or a pause, then built its
recording without its touches, and the closing segment dropped them
because they were stamped before its start.

Each timeline now has its own touch-event queue. The jump starts a new
one for touches, and segments built on the replay executor keep using
the old one until the jump's task moves the executor onto the new
timeline.

Refs JAVA-829

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@runningcode
runningcode force-pushed the no/java-829-replay-anchored-clock branch from 019fbd3 to 5259890 Compare November 17, 2026 10:05
@runningcode runningcode changed the title fix(replay): Keep the replay timeline anchored across wall-clock jumps (JAVA-829) fix(replay): Keep the replay timeline anchored across wall-clock jumps Nov 17, 2026

@cursor cursor Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Stale Bugbot comment from a previous run.

Resolve CHANGELOG.md conflict by keeping both Unreleased Fixes entries (#6542 and #6634).

@cursor cursor Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Fix All in Cursor

❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.

Reviewed by Cursor Bugbot for commit eb8b9cd. Configure here.

Resolve CHANGELOG.md conflict by keeping both Unreleased Fixes entries (#6542 and #6599).

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

risk: medium PR risk score: medium

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Session Replay segment, buffer and gesture timestamps read the wall clock

2 participants