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

* 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>

* changelog

* ref(replay): Trim the v9 AnchoredClock TODOs

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

* test(replay): Advance the ticker during the executor delay

The executor-delay test only moved the wall clock while the frame task
was queued, so it no longer guarded the 1h cap once that cap moved onto
the monotonic ticker: checking the deadline inside the task would still
pass. Advancing the ticker as well makes it fail on that regression.

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

* ref(replay): Suppress detekt size checks on the capture strategies

The monotonic ticker brings the capture-strategy constructors to seven
parameters now that main injects a persisting executor, and the
executor-delay ticker advance tips SessionCaptureStrategyTest over the
LargeClass threshold.

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

---------

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

Author: runningcode

CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## Unreleased
+
+### Fixes
+
+- Measure Session Replay's 1h recording cap and its touch-move debounce on a monotonic clock, so a device time change no longer stops a healthy recording early, keeps a finished one alive, or suppresses gesture events ([#6090](https://github.com/getsentry/sentry-java/pull/6090))
+
 ## 8.61.0
 
 ### Fixes

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

@@ -228,6 +228,7 @@ public class ReplayIntegration(
             options,
             scopes,
             dateProvider,
+            options.monotonicTicker,
             replayExecutor,
             persistingExecutor,
             replayCacheProvider,
@@ -237,6 +238,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

@@ -35,24 +35,30 @@ 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
 
 @SuppressLint("UseRequiresApi")
 @TargetApi(26)
-internal abstract class BaseCaptureStrategy(
+internal abstract class BaseCaptureStrategy
+@Suppress("LongParameterList")
+constructor(
   private val options: SentryOptions,
   private val scopes: IScopes?,
-  private val dateProvider: ICurrentDateProvider,
+  // TODO [v9]: We should consider replacing this with AnchoredClock in V9.
+  dateProvider: ICurrentDateProvider,
+  private val ticker: MonotonicTicker,
   protected val replayExecutor: ScheduledExecutorService,
   protected val persistingExecutor: ScheduledExecutorService,
   private val replayCacheProvider: ((replayId: SentryId) -> ReplayCache)? = null,
@@ -63,7 +69,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
@@ -85,7 +91,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
   private var recordingMetadata: RecordingMetadata? by
     persistableAtomicNullable(propertyName = "") { _, _, newValue ->
       persistMetadataValue(SEGMENT_KEY_RELEASE, newValue?.release)
@@ -123,7 +133,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)
     // the same values MainEventProcessor applies to current-run segments
     recordingMetadata =
       RecordingMetadata(
@@ -152,7 +162,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 java.io.File
 import java.util.Date
@@ -39,10 +40,13 @@ import java.util.concurrent.ScheduledExecutorService
  */
 @SuppressLint("UseRequiresApi")
 @TargetApi(26)
-internal class BufferCaptureStrategy(
+internal class BufferCaptureStrategy
+@Suppress("LongParameterList")
+constructor(
   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,
@@ -51,6 +55,7 @@ internal class BufferCaptureStrategy(
     options,
     scopes,
     dateProvider,
+    ticker,
     executor,
     persistingExecutor,
     replayCacheProvider = replayCacheProvider,
@@ -172,7 +177,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 java.util.Date
 import java.util.concurrent.ScheduledExecutorService
@@ -27,10 +28,13 @@ import java.util.concurrent.ScheduledExecutorService
  *
  * See [BufferCaptureStrategy] for the on-error counterpart.
  */
-internal class SessionCaptureStrategy(
+internal class SessionCaptureStrategy
+@Suppress("LongParameterList")
+constructor(
   private val options: SentryOptions,
   private val scopes: IScopes?,
   private val dateProvider: ICurrentDateProvider,
+  ticker: MonotonicTicker,
   executor: ScheduledExecutorService,
   persistingExecutor: ScheduledExecutorService,
   replayCacheProvider: ((replayId: SentryId) -> ReplayCache)? = null,
@@ -39,6 +43,7 @@ internal class SessionCaptureStrategy(
     options,
     scopes,
     dateProvider,
+    ticker,
     executor,
     persistingExecutor,
     replayCacheProvider,
@@ -110,6 +115,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)
@@ -157,7 +163,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,27 @@ 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 [v9]: Replace this with AnchoredClock in V9
+  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 +37,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

@@ -1377,6 +1377,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 {
@@ -1761,6 +1762,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

@@ -36,11 +36,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
@@ -62,6 +65,7 @@ import org.mockito.kotlin.never
 import org.mockito.kotlin.verify
 import org.mockito.kotlin.whenever
 
+@Suppress("LargeClass")
 class SessionCaptureStrategyTest {
   @get:Rule val tmpDir = TemporaryFolder()
 
@@ -114,6 +118,8 @@ class SessionCaptureStrategyTest {
         bitRate = 20_000,
       )
 
+    val ticker = TestMonotonicTicker()
+
     fun getSut(
       dateProvider: ICurrentDateProvider = CurrentDateProvider.getInstance(),
       replayCacheDir: File? = null,
@@ -131,6 +137,7 @@ class SessionCaptureStrategyTest {
         options,
         scopes,
         dateProvider,
+        ticker,
         replayExecutor,
         mock {
           doAnswer { invocation ->
@@ -441,6 +448,7 @@ class SessionCaptureStrategyTest {
 
     strategy.onScreenshotRecorded(mock<Bitmap>()) {}
     now += fixture.options.sessionReplay.sessionDuration
+    fixture.ticker.advance(fixture.options.sessionReplay.sessionDuration, MILLISECONDS)
     tasks.forEach(Runnable::run)
 
     verify(fixture.scopes, never()).captureReplay(any(), any())
@@ -498,6 +506,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>()) {}