fix(replay): Measure recording deadlines on a monotonic clock (JAVA-575)

Session Replay derives every interval from the wall clock. Two of those
intervals are pure control flow, and a clock step corrupts both:

- The 1h `sessionDuration` cap was `frameTimestamp - replayStartTimestamp`.
  A forward step past the cap kills a healthy recording on the next frame;
  a backward step lets one run indefinitely.
- The 50ms ACTION_MOVE debounce was `lastCapturedMoveEvent + 50 > now`.
  A backward step suppresses every move event until the wall clock catches
  back up.

Both now use `io.sentry.time.Deadline` on the options' `MonotonicTicker`,
which is `SystemClock.elapsedRealtimeNanos()` on Android. That clock
advances across device suspend just as the wall clock does, so the
conversion preserves today's semantics and only removes the step.

The cap is still evaluated when a frame is captured rather than when its
queued task runs, so a busy replay executor cannot trip it.

Everything else JAVA-575 lists — segment timestamps and durations, frame
filenames, buffer cutoffs, gesture `timeOffset`s — stays on the wall clock:
those values are serialized, and fixing them means re-basing them onto an
`AnchoredClock`, which is a v9 change. `// TODO [MAJOR]` markers record that
at both `ICurrentDateProvider` injection sites.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: runningcode

sentry-android-replay/src/main/java/io/sentry/android/replay/ReplayIntegration.kt

@@ -223,6 +223,7 @@ public class ReplayIntegration(
             options,
             scopes,
             dateProvider,
+            options.monotonicTicker,
             replayExecutor,
             persistingExecutor,
             replayCacheProvider,
@@ -232,6 +233,7 @@ public class ReplayIntegration(
             options,
             scopes,
             dateProvider,
+            options.monotonicTicker,
             replayExecutor,
             persistingExecutor,
             replayCacheProvider,

sentry-android-replay/src/main/java/io/sentry/android/replay/capture/BaseCaptureStrategy.kt

@@ -29,14 +29,16 @@ import io.sentry.android.replay.gestures.ReplayGestureConverter
 import io.sentry.android.replay.util.ReplayRunnable
 import io.sentry.protocol.SentryId
 import io.sentry.rrweb.RRWebEvent
+import io.sentry.time.Deadline
+import io.sentry.time.MonotonicTicker
 import io.sentry.transport.ICurrentDateProvider
 import java.io.File
 import java.util.Date
 import java.util.Deque
 import java.util.concurrent.ConcurrentLinkedDeque
 import java.util.concurrent.ScheduledExecutorService
+import java.util.concurrent.TimeUnit.MILLISECONDS
 import java.util.concurrent.atomic.AtomicBoolean
-import java.util.concurrent.atomic.AtomicLong
 import java.util.concurrent.atomic.AtomicReference
 import kotlin.properties.ReadWriteProperty
 import kotlin.reflect.KProperty
@@ -46,7 +48,12 @@ import kotlin.reflect.KProperty
 internal abstract class BaseCaptureStrategy(
   private val options: SentryOptions,
   private val scopes: IScopes?,
+  // TODO [MAJOR]: every value this provider stamps is serialized — segment timestamps and
+  // durations, frame filenames, buffer cutoffs, gesture offsets — and they are all subtracted from
+  // each other, so a clock step corrupts a recording. Replacing it with an io.sentry.time
+  // .AnchoredClock re-bases those timestamps and is therefore v9-only. See JAVA-575.
   private val dateProvider: ICurrentDateProvider,
+  private val ticker: MonotonicTicker,
   protected val replayExecutor: ScheduledExecutorService,
   protected val persistingExecutor: ScheduledExecutorService,
   private val replayCacheProvider: ((replayId: SentryId) -> ReplayCache)? = null,
@@ -57,7 +64,7 @@ internal abstract class BaseCaptureStrategy(
     private const val MAX_CONTEXT_VALUES = 100
   }
 
-  private val gestureConverter = ReplayGestureConverter(dateProvider)
+  private val gestureConverter = ReplayGestureConverter(dateProvider, ticker)
 
   protected val isTerminating = AtomicBoolean(false)
   protected var cache: ReplayCache? = null
@@ -79,7 +86,11 @@ internal abstract class BaseCaptureStrategy(
         if (newValue == null) null else DateUtils.getTimestamp(newValue),
       )
     }
-  protected val replayStartTimestamp = AtomicLong()
+  /**
+   * When the recording reaches its `sessionDuration` cap, or `null` while nothing is being
+   * recorded. Only [SessionCaptureStrategy] enforces a cap; buffer mode records indefinitely.
+   */
+  @Volatile protected var replayDeadline: Deadline? = null
   protected var screenAtStart by
     persistableAtomicNullable<String>(propertyName = SEGMENT_KEY_REPLAY_SCREEN_AT_START)
   override var currentReplayId: SentryId by
@@ -109,7 +120,7 @@ internal abstract class BaseCaptureStrategy(
     this.replayType = replayType ?: (if (this is SessionCaptureStrategy) SESSION else BUFFER)
 
     segmentTimestamp = DateUtils.getCurrentDateTime()
-    replayStartTimestamp.set(dateProvider.currentTimeMillis)
+    replayDeadline = Deadline.after(ticker, options.sessionReplay.sessionDuration, MILLISECONDS)
   }
 
   override fun resume() {
@@ -125,7 +136,7 @@ internal abstract class BaseCaptureStrategy(
     replayExecutor.submit(
       ReplayRunnable("$TAG.stop") {
         cache?.close()
-        replayStartTimestamp.set(0)
+        replayDeadline = null
         segmentTimestamp = null
         currentReplayId = SentryId.EMPTY_ID
       }

sentry-android-replay/src/main/java/io/sentry/android/replay/capture/BufferCaptureStrategy.kt

@@ -20,6 +20,7 @@ import io.sentry.android.replay.capture.CaptureStrategy.ReplaySegment
 import io.sentry.android.replay.util.ReplayRunnable
 import io.sentry.clientreport.DiscardReason.RATELIMIT_BACKOFF
 import io.sentry.protocol.SentryId
+import io.sentry.time.MonotonicTicker
 import io.sentry.transport.ICurrentDateProvider
 import io.sentry.util.FileUtils
 import java.io.File
@@ -44,6 +45,7 @@ internal class BufferCaptureStrategy(
   private val options: SentryOptions,
   private val scopes: IScopes?,
   private val dateProvider: ICurrentDateProvider,
+  private val ticker: MonotonicTicker,
   executor: ScheduledExecutorService,
   persistingExecutor: ScheduledExecutorService,
   replayCacheProvider: ((replayId: SentryId) -> ReplayCache)? = null,
@@ -52,6 +54,7 @@ internal class BufferCaptureStrategy(
     options,
     scopes,
     dateProvider,
+    ticker,
     executor,
     persistingExecutor,
     replayCacheProvider = replayCacheProvider,
@@ -173,7 +176,14 @@ internal class BufferCaptureStrategy(
     // we hand over replayExecutor and persistingExecutor to the new strategy to preserve order of
     // execution
     val captureStrategy =
-      SessionCaptureStrategy(options, scopes, dateProvider, replayExecutor, persistingExecutor)
+      SessionCaptureStrategy(
+        options,
+        scopes,
+        dateProvider,
+        ticker,
+        replayExecutor,
+        persistingExecutor,
+      )
     captureStrategy.recorderConfig = recorderConfig
     captureStrategy.start(
       segmentId = currentSegment,

sentry-android-replay/src/main/java/io/sentry/android/replay/capture/SessionCaptureStrategy.kt

@@ -11,6 +11,7 @@ import io.sentry.android.replay.ScreenshotRecorderConfig
 import io.sentry.android.replay.capture.CaptureStrategy.ReplaySegment
 import io.sentry.android.replay.util.ReplayRunnable
 import io.sentry.protocol.SentryId
+import io.sentry.time.MonotonicTicker
 import io.sentry.transport.ICurrentDateProvider
 import io.sentry.util.FileUtils
 import java.util.Date
@@ -32,6 +33,7 @@ internal class SessionCaptureStrategy(
   private val options: SentryOptions,
   private val scopes: IScopes?,
   private val dateProvider: ICurrentDateProvider,
+  ticker: MonotonicTicker,
   executor: ScheduledExecutorService,
   persistingExecutor: ScheduledExecutorService,
   replayCacheProvider: ((replayId: SentryId) -> ReplayCache)? = null,
@@ -40,6 +42,7 @@ internal class SessionCaptureStrategy(
     options,
     scopes,
     dateProvider,
+    ticker,
     executor,
     persistingExecutor,
     replayCacheProvider,
@@ -111,6 +114,7 @@ internal class SessionCaptureStrategy(
     // reflecting the exact time of when it was captured
     val currentConfig = recorderConfig
     val frameTimestamp = dateProvider.currentTimeMillis
+    val deadlineExceeded = replayDeadline?.hasPassed() == true
     replayExecutor.submit(
       ReplayRunnable("$TAG.add_frame") {
         cache?.store(frameTimestamp)
@@ -158,7 +162,7 @@ internal class SessionCaptureStrategy(
           }
         }
 
-        if (frameTimestamp - replayStartTimestamp.get() >= options.sessionReplay.sessionDuration) {
+        if (deadlineExceeded) {
           options.replayController.stop()
           options.logger.log(INFO, "Session replay deadline exceeded (1h), stopping recording")
         }

sentry-android-replay/src/main/java/io/sentry/android/replay/gestures/ReplayGestureConverter.kt

@@ -7,18 +7,28 @@ import io.sentry.rrweb.RRWebInteractionEvent
 import io.sentry.rrweb.RRWebInteractionEvent.InteractionType
 import io.sentry.rrweb.RRWebInteractionMoveEvent
 import io.sentry.rrweb.RRWebInteractionMoveEvent.Position
+import io.sentry.time.Deadline
+import io.sentry.time.MonotonicTicker
 import io.sentry.transport.ICurrentDateProvider
+import java.util.concurrent.TimeUnit.MILLISECONDS
 
-internal class ReplayGestureConverter(private val dateProvider: ICurrentDateProvider) {
+internal class ReplayGestureConverter(
+  // TODO [MAJOR]: the timestamps and timeOffsets stamped from this provider are serialized, so
+  // moving them onto an io.sentry.time.AnchoredClock is v9-only. See JAVA-575.
+  private val dateProvider: ICurrentDateProvider,
+  private val ticker: MonotonicTicker,
+) {
   internal companion object {
     // rrweb values
-    private const val TOUCH_MOVE_DEBOUNCE_THRESHOLD = 50
+    private const val TOUCH_MOVE_DEBOUNCE_THRESHOLD = 50L
     private const val CAPTURE_MOVE_EVENT_THRESHOLD = 500
   }
 
   private val currentPositions = LinkedHashMap<Int, ArrayList<Position>>(10)
   private var touchMoveBaseline = 0L
-  private var lastCapturedMoveEvent = 0L
+
+  /** When the next move event may be captured, or `null` before the first one. */
+  private var moveDebounce: Deadline? = null
 
   fun convert(
     event: MotionEvent,
@@ -28,12 +38,10 @@ internal class ReplayGestureConverter(private val dateProvider: ICurrentDateProv
       MotionEvent.ACTION_MOVE -> {
         // we only throttle move events as those can be overwhelming
         val now = dateProvider.currentTimeMillis
-        if (
-          lastCapturedMoveEvent != 0L && lastCapturedMoveEvent + TOUCH_MOVE_DEBOUNCE_THRESHOLD > now
-        ) {
+        if (moveDebounce?.hasPassed() == false) {
           return null
         }
-        lastCapturedMoveEvent = now
+        moveDebounce = Deadline.after(ticker, TOUCH_MOVE_DEBOUNCE_THRESHOLD, MILLISECONDS)
 
         currentPositions.keys.forEach { pId ->
           val pIndex = event.findPointerIndex(pId)

sentry-android-replay/src/test/java/io/sentry/android/replay/ReplayIntegrationTest.kt

@@ -1254,6 +1254,7 @@ class ReplayIntegrationTest {
             ICurrentDateProvider {
               System.currentTimeMillis() + fixture.options.sessionReplay.sessionSegmentDuration
             },
+            fixture.options.monotonicTicker,
             // run tasks synchronously in tests
             mock {
               whenever(mock.submit(any<Runnable>())).doAnswer {
@@ -1638,6 +1639,7 @@ class ReplayIntegrationTest {
       options,
       null,
       CurrentDateProvider.getInstance(),
+      options.monotonicTicker,
       executor =
         mock {
           whenever(mock.submit(any<Runnable>())).doAnswer {

sentry-android-replay/src/test/java/io/sentry/android/replay/capture/BufferCaptureStrategyTest.kt

@@ -23,6 +23,7 @@ import io.sentry.android.replay.capture.BufferCaptureStrategyTest.Fixture.Compan
 import io.sentry.clientreport.DiscardReason
 import io.sentry.clientreport.DiscardedEvent
 import io.sentry.protocol.SentryId
+import io.sentry.time.TestMonotonicTicker
 import io.sentry.transport.CurrentDateProvider
 import io.sentry.transport.ICurrentDateProvider
 import io.sentry.transport.RateLimiter
@@ -108,6 +109,8 @@ class BufferCaptureStrategyTest {
         ?.discardedEvents
         .orEmpty()
 
+    val ticker = TestMonotonicTicker()
+
     fun getSut(
       dateProvider: ICurrentDateProvider = CurrentDateProvider.getInstance(),
       replayCacheDir: File? = null,
@@ -117,6 +120,7 @@ class BufferCaptureStrategyTest {
         options,
         scopes,
         dateProvider,
+        ticker,
         mock {
           whenever(it.submit(any<Runnable>())).doAnswer { invocation ->
             (invocation.arguments[0] as Runnable).run()

sentry-android-replay/src/test/java/io/sentry/android/replay/capture/SessionCaptureStrategyTest.kt

@@ -30,11 +30,14 @@ import io.sentry.protocol.SentryId
 import io.sentry.rrweb.RRWebBreadcrumbEvent
 import io.sentry.rrweb.RRWebMetaEvent
 import io.sentry.rrweb.RRWebOptionsEvent
+import io.sentry.time.TestMonotonicTicker
 import io.sentry.transport.CurrentDateProvider
 import io.sentry.transport.ICurrentDateProvider
 import java.io.File
 import java.util.Date
 import java.util.concurrent.ScheduledExecutorService
+import java.util.concurrent.TimeUnit.MILLISECONDS
+import java.util.concurrent.TimeUnit.SECONDS
 import kotlin.test.Test
 import kotlin.test.assertContentEquals
 import kotlin.test.assertEquals
@@ -108,6 +111,8 @@ class SessionCaptureStrategyTest {
         bitRate = 20_000,
       )
 
+    val ticker = TestMonotonicTicker()
+
     fun getSut(
       dateProvider: ICurrentDateProvider = CurrentDateProvider.getInstance(),
       replayCacheDir: File? = null,
@@ -125,6 +130,7 @@ class SessionCaptureStrategyTest {
         options,
         scopes,
         dateProvider,
+        ticker,
         replayExecutor,
         mock {
           doAnswer { invocation ->
@@ -447,6 +453,37 @@ class SessionCaptureStrategyTest {
     strategy.start()
     strategy.onConfigurationChanged(mock<ScreenshotRecorderConfig>())
     now += fixture.options.sessionReplay.sessionDuration * 2
+    fixture.ticker.advance(fixture.options.sessionReplay.sessionDuration * 2, MILLISECONDS)
+
+    strategy.onScreenshotRecorded(mock<Bitmap>()) {}
+
+    verify(fixture.options.replayController).stop()
+  }
+
+  @Test
+  fun `onScreenshotRecorded does not stop replay when the wall clock jumps past the deadline`() {
+    var now = System.currentTimeMillis()
+    val strategy = fixture.getSut(dateProvider = { now })
+    strategy.start()
+    strategy.onConfigurationChanged(mock<ScreenshotRecorderConfig>())
+    // the device corrects its clock two hours forwards a second into the recording
+    now += fixture.options.sessionReplay.sessionDuration * 2
+    fixture.ticker.advance(1, SECONDS)
+
+    strategy.onScreenshotRecorded(mock<Bitmap>()) {}
+
+    verify(fixture.options.replayController, never()).stop()
+  }
+
+  @Test
+  fun `onScreenshotRecorded stops replay when the wall clock steps backwards past the deadline`() {
+    var now = System.currentTimeMillis()
+    val strategy = fixture.getSut(dateProvider = { now })
+    strategy.start()
+    strategy.onConfigurationChanged(mock<ScreenshotRecorderConfig>())
+    // an hour of recording, during which the device drags its clock back to before the start
+    fixture.ticker.advance(fixture.options.sessionReplay.sessionDuration, MILLISECONDS)
+    now -= 1000
 
     strategy.onScreenshotRecorded(mock<Bitmap>()) {}