fix(android): Measure debounce windows on the monotonic ticker (JAVA-729) (#6590)

* fix(android): Measure debounce windows on the monotonic ticker (JAVA-729)

Debouncer read AndroidCurrentDateProvider, which is
SystemClock.uptimeMillis() and stops in deep sleep. A window that
expired while the device slept still looked open, so the first
low-memory or battery breadcrumb after a long Doze could be dropped.

Debouncer now measures its window with a Deadline on
options.getMonotonicTicker(), which is CLOCK_BOOTTIME on Android. The
screenshot, view hierarchy, system events and app components debouncers
all use it.

AndroidEnvelopeCache still uses AndroidCurrentDateProvider: it compares
against TimeSpan's uptime start, so it can't move on its own.

Refs JAVA-729

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

* changelog

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

Author: runningcode

CHANGELOG.md

@@ -5,6 +5,12 @@
 > - Java 8 support will be dropped. SDK 9.0.0 requires Java 11+. See [#6469](https://github.com/getsentry/sentry-java/issues/6469).
 > - The Android `minSdk` will be raised from 21 to 24. See [#5508](https://github.com/getsentry/sentry-java/issues/5508).
 
+## Unreleased
+
+### Fixes
+
+- Android: Count deep sleep in breadcrumb, screenshot and view hierarchy debounce windows, so the first low-memory or battery breadcrumb after a long Doze is no longer dropped ([#6590](https://github.com/getsentry/sentry-java/pull/6590))
+
 ## 8.64.0
 
 ### Breaking Changes

sentry-android-core/src/main/java/io/sentry/android/core/AppComponentsBreadcrumbsIntegration.java

@@ -12,7 +12,6 @@
 import io.sentry.Integration;
 import io.sentry.SentryLevel;
 import io.sentry.SentryOptions;
-import io.sentry.android.core.internal.util.AndroidCurrentDateProvider;
 import io.sentry.android.core.internal.util.Debouncer;
 import io.sentry.android.core.internal.util.DeviceOrientations;
 import io.sentry.protocol.Device;
@@ -34,10 +33,7 @@ public final class AppComponentsBreadcrumbsIntegration
   private @Nullable IScopes scopes;
   private @Nullable SentryAndroidOptions options;
 
-  // TODO: JAVA-729
-  @SuppressWarnings("deprecation")
-  private final @NotNull Debouncer trimMemoryDebouncer =
-      new Debouncer(AndroidCurrentDateProvider.getInstance(), DEBOUNCE_WAIT_TIME_MS, 0);
+  private volatile @Nullable Debouncer trimMemoryDebouncer;
 
   public AppComponentsBreadcrumbsIntegration(final @NotNull Context context) {
     this.context =
@@ -51,6 +47,8 @@ public void register(final @NotNull IScopes scopes, final @NotNull SentryOptions
         Objects.requireNonNull(
             (options instanceof SentryAndroidOptions) ? (SentryAndroidOptions) options : null,
             "SentryAndroidOptions is required");
+    this.trimMemoryDebouncer =
+        new Debouncer(this.options.getMonotonicTicker(), DEBOUNCE_WAIT_TIME_MS, 0);
 
     this.options
         .getLogger()
@@ -121,7 +119,8 @@ public void onTrimMemory(final int level) {
       return;
     }
 
-    if (trimMemoryDebouncer.checkForDebounce()) {
+    final @Nullable Debouncer trimMemoryDebouncer = this.trimMemoryDebouncer;
+    if (trimMemoryDebouncer != null && trimMemoryDebouncer.checkForDebounce()) {
       // if we received trim_memory within 1 minute time, ignore this call
       return;
     }

sentry-android-core/src/main/java/io/sentry/android/core/ScreenshotEventProcessor.java

@@ -9,7 +9,6 @@
 import io.sentry.Hint;
 import io.sentry.SentryEvent;
 import io.sentry.SentryLevel;
-import io.sentry.android.core.internal.util.AndroidCurrentDateProvider;
 import io.sentry.android.core.internal.util.Debouncer;
 import io.sentry.android.core.internal.util.ScreenshotUtils;
 import io.sentry.internal.eventprocessor.SentryEventProcessor;
@@ -39,8 +38,6 @@ public final class ScreenshotEventProcessor implements SentryEventProcessor {
   private final boolean isReplayAvailable;
   private final AtomicBoolean isReplayModuleAbsenceLogged = new AtomicBoolean(false);
 
-  // TODO: JAVA-729
-  @SuppressWarnings("deprecation")
   public ScreenshotEventProcessor(
       final @NotNull SentryAndroidOptions options,
       final @NotNull BuildInfoProvider buildInfoProvider,
@@ -49,10 +46,7 @@ public ScreenshotEventProcessor(
     this.buildInfoProvider =
         Objects.requireNonNull(buildInfoProvider, "BuildInfoProvider is required");
     this.debouncer =
-        new Debouncer(
-            AndroidCurrentDateProvider.getInstance(),
-            DEBOUNCE_WAIT_TIME_MS,
-            DEBOUNCE_MAX_EXECUTIONS);
+        new Debouncer(options.getMonotonicTicker(), DEBOUNCE_WAIT_TIME_MS, DEBOUNCE_MAX_EXECUTIONS);
 
     this.isReplayAvailable = isReplayAvailable;
 

sentry-android-core/src/main/java/io/sentry/android/core/SystemEventsBreadcrumbsIntegration.java

@@ -35,7 +35,6 @@
 import io.sentry.Integration;
 import io.sentry.SentryLevel;
 import io.sentry.SentryOptions;
-import io.sentry.android.core.internal.util.AndroidCurrentDateProvider;
 import io.sentry.android.core.internal.util.Debouncer;
 import io.sentry.util.AutoClosableReentrantLock;
 import io.sentry.util.Objects;
@@ -300,15 +299,14 @@ final class SystemEventsBroadcastReceiver extends BroadcastReceiver {
     private final @NotNull IScopes scopes;
     private final @NotNull SentryAndroidOptions options;
 
-    // TODO: JAVA-729
-    @SuppressWarnings("deprecation")
-    private final @NotNull Debouncer batteryChangedDebouncer =
-        new Debouncer(AndroidCurrentDateProvider.getInstance(), DEBOUNCE_WAIT_TIME_MS, 0);
+    private final @NotNull Debouncer batteryChangedDebouncer;
 
     SystemEventsBroadcastReceiver(
         final @NotNull IScopes scopes, final @NotNull SentryAndroidOptions options) {
       this.scopes = scopes;
       this.options = options;
+      this.batteryChangedDebouncer =
+          new Debouncer(options.getMonotonicTicker(), DEBOUNCE_WAIT_TIME_MS, 0);
     }
 
     @Override

sentry-android-core/src/main/java/io/sentry/android/core/ViewHierarchyEventProcessor.java

@@ -13,7 +13,6 @@
 import io.sentry.SentryEvent;
 import io.sentry.SentryLevel;
 import io.sentry.android.core.internal.gestures.ViewUtils;
-import io.sentry.android.core.internal.util.AndroidCurrentDateProvider;
 import io.sentry.android.core.internal.util.AndroidThreadChecker;
 import io.sentry.android.core.internal.util.ClassUtil;
 import io.sentry.android.core.internal.util.Debouncer;
@@ -47,15 +46,10 @@ public final class ViewHierarchyEventProcessor implements SentryEventProcessor {
   private static final long DEBOUNCE_WAIT_TIME_MS = 2000;
   private static final int DEBOUNCE_MAX_EXECUTIONS = 3;
 
-  // TODO: JAVA-729
-  @SuppressWarnings("deprecation")
   public ViewHierarchyEventProcessor(final @NotNull SentryAndroidOptions options) {
     this.options = Objects.requireNonNull(options, "SentryAndroidOptions is required");
     this.debouncer =
-        new Debouncer(
-            AndroidCurrentDateProvider.getInstance(),
-            DEBOUNCE_WAIT_TIME_MS,
-            DEBOUNCE_MAX_EXECUTIONS);
+        new Debouncer(options.getMonotonicTicker(), DEBOUNCE_WAIT_TIME_MS, DEBOUNCE_MAX_EXECUTIONS);
 
     if (options.isAttachViewHierarchy()) {
       addIntegrationToSdkVersion("ViewHierarchy");

sentry-android-core/src/main/java/io/sentry/android/core/internal/util/Debouncer.java

@@ -1,40 +1,43 @@
 package io.sentry.android.core.internal.util;
 
-import io.sentry.transport.ICurrentDateProvider;
+import io.sentry.time.Deadline;
+import io.sentry.time.MonotonicTicker;
+import java.util.concurrent.TimeUnit;
 import java.util.concurrent.atomic.AtomicInteger;
-import java.util.concurrent.atomic.AtomicLong;
 import org.jetbrains.annotations.ApiStatus;
 import org.jetbrains.annotations.NotNull;
 
-/** A simple time-based debouncing mechanism */
+/**
+ * A simple time-based debouncing mechanism.
+ *
+ * <p>The window is measured on a {@link MonotonicTicker}, which on Android keeps counting through
+ * deep sleep, so a window that expired while the device slept is treated as expired.
+ */
 @ApiStatus.Internal
 public final class Debouncer {
 
+  private final @NotNull MonotonicTicker ticker;
   private final long waitTimeMs;
-  private final @NotNull ICurrentDateProvider timeProvider;
-  private final @NotNull AtomicInteger executions = new AtomicInteger(0);
   private final int maxExecutions;
-
-  private final @NotNull AtomicLong lastExecutionTime = new AtomicLong(0);
+  private final @NotNull AtomicInteger executions = new AtomicInteger(0);
+  private volatile @NotNull Deadline windowEnd;
 
   public Debouncer(
-      final @NotNull ICurrentDateProvider timeProvider,
-      final long waitTimeMs,
-      final int maxExecutions) {
-    this.timeProvider = timeProvider;
+      final @NotNull MonotonicTicker ticker, final long waitTimeMs, final int maxExecutions) {
+    this.ticker = ticker;
     this.waitTimeMs = waitTimeMs;
     this.maxExecutions = maxExecutions <= 0 ? 1 : maxExecutions;
+    this.windowEnd = Deadline.passed(ticker);
   }
 
   /**
    * Returns true if the execution should be debounced due to maxExecutions executions being made
    * within waitTimeMs, otherwise false.
    */
   public boolean checkForDebounce() {
-    final long now = timeProvider.getCurrentTimeMillis();
-    if (lastExecutionTime.get() == 0 || (lastExecutionTime.get() + waitTimeMs) <= now) {
+    if (windowEnd.hasPassed()) {
       executions.set(0);
-      lastExecutionTime.set(now);
+      windowEnd = Deadline.after(ticker, waitTimeMs, TimeUnit.MILLISECONDS);
       return false;
     }
     if (executions.incrementAndGet() < maxExecutions) {

sentry-android-core/src/test/java/io/sentry/android/core/internal/util/DebouncerTest.kt

@@ -1,28 +1,23 @@
 package io.sentry.android.core.internal.util
 
-import io.sentry.transport.ICurrentDateProvider
-import kotlin.test.BeforeTest
+import io.sentry.time.TestMonotonicTicker
+import java.util.concurrent.TimeUnit
 import kotlin.test.Test
 import org.junit.Assert.assertFalse
 import org.junit.Assert.assertTrue
 
 class DebouncerTest {
-  private class Fixture : ICurrentDateProvider {
-    var currentTimeMs: Long = 0
+  private class Fixture {
+    val ticker = TestMonotonicTicker()
 
-    override fun getCurrentTimeMillis(): Long = currentTimeMs
+    fun advance(millis: Long) = ticker.advance(millis, TimeUnit.MILLISECONDS)
 
     fun getDebouncer(waitTimeMs: Long = 3000, maxExecutions: Int = 1): Debouncer =
-      Debouncer(this, waitTimeMs, maxExecutions)
+      Debouncer(ticker, waitTimeMs, maxExecutions)
   }
 
   private val fixture = Fixture()
 
-  @BeforeTest
-  fun `set up`() {
-    fixture.currentTimeMs = 0
-  }
-
   @Test
   fun `Debouncer should not debounce on the first check`() {
     val debouncer = fixture.getDebouncer()
@@ -39,35 +34,41 @@ class DebouncerTest {
 
   @Test
   fun `Debouncer should signal debounce if the second invocation is too early`() {
-    fixture.currentTimeMs = 1000
     val debouncer = fixture.getDebouncer(3000)
     assertFalse(debouncer.checkForDebounce())
 
-    fixture.currentTimeMs = 3999
+    fixture.advance(2999)
     assertTrue(debouncer.checkForDebounce())
   }
 
   @Test
   fun `Debouncer should not signal debounce if the second invocation is late enough`() {
-    fixture.currentTimeMs = 1000
     val debouncer = fixture.getDebouncer(3000)
     assertFalse(debouncer.checkForDebounce())
 
-    fixture.currentTimeMs = 4000
+    fixture.advance(3000)
+    assertFalse(debouncer.checkForDebounce())
+  }
+
+  @Test
+  fun `Debouncer does not debounce after a window that expired during deep sleep`() {
+    val debouncer = fixture.getDebouncer(60_000)
+    assertFalse(debouncer.checkForDebounce())
+
+    // The ticker keeps counting while the device sleeps, so an hour asleep expires the window.
+    fixture.advance(TimeUnit.HOURS.toMillis(1))
     assertFalse(debouncer.checkForDebounce())
   }
 
   @Test
   fun `Debouncer maxExecutions is always greater than 0`() {
-    fixture.currentTimeMs = 1000
     val debouncer = fixture.getDebouncer(3000, -1)
     assertFalse(debouncer.checkForDebounce())
     assertTrue(debouncer.checkForDebounce())
   }
 
   @Test
   fun `Debouncer should signal debounce after maxExecutions calls`() {
-    fixture.currentTimeMs = 1000
     val debouncer = fixture.getDebouncer(3000, 3)
     assertFalse(debouncer.checkForDebounce())
     assertFalse(debouncer.checkForDebounce())
@@ -77,13 +78,12 @@ class DebouncerTest {
 
   @Test
   fun `Debouncer maxExecutions counter resets if the other invocation is late enough`() {
-    fixture.currentTimeMs = 1000
     val debouncer = fixture.getDebouncer(3000, 3)
     assertFalse(debouncer.checkForDebounce())
     assertFalse(debouncer.checkForDebounce())
 
     // After waitTimeMs passes, the maxExecutions counter is reset
-    fixture.currentTimeMs = 4000
+    fixture.advance(3000)
     assertFalse(debouncer.checkForDebounce())
     assertFalse(debouncer.checkForDebounce())
     assertFalse(debouncer.checkForDebounce())
@@ -92,7 +92,6 @@ class DebouncerTest {
 
   @Test
   fun `Debouncer maxExecutions counter resets after maxExecutions`() {
-    fixture.currentTimeMs = 1000
     val debouncer = fixture.getDebouncer(3000, 3)
     assertFalse(debouncer.checkForDebounce())
     assertFalse(debouncer.checkForDebounce())