perf: Avoid per-transaction Timer thread in SentryTracer (JAVA-570)

Transactions with an idle or deadline timeout each created a
java.util.Timer, which spawns a thread synchronously on the calling
thread (often the main thread on Android). At scale (screen loads, HTTP
spans) this was the dominant source of SDK thread churn.

Schedule the idle/deadline timeouts on the shared SentryExecutorService
instead, so no thread is created per transaction. On finish only the
scheduled futures are cancelled; the shared executor is never shut down
here since it is used SDK-wide.

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

Author: runningcode

sentry/src/main/java/io/sentry/SentryTracer.java

@@ -12,9 +12,8 @@
 import java.util.List;
 import java.util.ListIterator;
 import java.util.Map;
-import java.util.Timer;
-import java.util.TimerTask;
 import java.util.concurrent.CopyOnWriteArrayList;
+import java.util.concurrent.Future;
 import java.util.concurrent.atomic.AtomicBoolean;
 import java.util.concurrent.atomic.AtomicReference;
 import org.jetbrains.annotations.ApiStatus;
@@ -37,10 +36,13 @@ public final class SentryTracer implements ITransaction {
    */
   private @NotNull FinishStatus finishStatus = FinishStatus.NOT_FINISHED;
 
-  private volatile @Nullable TimerTask idleTimeoutTask;
-  private volatile @Nullable TimerTask deadlineTimeoutTask;
+  private volatile @Nullable Future<?> idleTimeoutFuture;
+  private volatile @Nullable Future<?> deadlineTimeoutFuture;
 
-  private volatile @Nullable Timer timer = null;
+  // Shared executor used to schedule the timeout tasks. Null once the tracer is finished, at which
+  // point no more timeouts may be scheduled. It is never shut down here since it is shared
+  // SDK-wide.
+  private volatile @Nullable ISentryExecutorService timerExecutorService = null;
   private final @NotNull AutoClosableReentrantLock timerLock = new AutoClosableReentrantLock();
   private final @NotNull AutoClosableReentrantLock tracerLock = new AutoClosableReentrantLock();
 
@@ -99,7 +101,7 @@ public SentryTracer(
 
     if (transactionOptions.getIdleTimeout() != null
         || transactionOptions.getDeadlineTimeout() != null) {
-      timer = new Timer(true);
+      timerExecutorService = scopes.getOptions().getExecutorService();
 
       scheduleDeadlineTimeout();
       scheduleFinish();
@@ -109,22 +111,16 @@ public SentryTracer(
   @Override
   public void scheduleFinish() {
     try (final @NotNull ISentryLifecycleToken ignored = timerLock.acquire()) {
-      if (timer != null) {
+      if (timerExecutorService != null) {
         final @Nullable Long idleTimeout = transactionOptions.getIdleTimeout();
 
         if (idleTimeout != null) {
           cancelIdleTimer();
           isIdleFinishTimerRunning.set(true);
-          idleTimeoutTask =
-              new TimerTask() {
-                @Override
-                public void run() {
-                  onIdleTimeoutReached();
-                }
-              };
 
           try {
-            timer.schedule(idleTimeoutTask, idleTimeout);
+            idleTimeoutFuture =
+                timerExecutorService.schedule(this::onIdleTimeoutReached, idleTimeout);
           } catch (Throwable e) {
             scopes
                 .getOptions()
@@ -265,13 +261,12 @@ public void finish(
           });
       final SentryTransaction transaction = new SentryTransaction(this);
 
-      if (timer != null) {
+      if (timerExecutorService != null) {
         try (final @NotNull ISentryLifecycleToken ignored = timerLock.acquire()) {
-          if (timer != null) {
+          if (timerExecutorService != null) {
             cancelIdleTimer();
             cancelDeadlineTimer();
-            timer.cancel();
-            timer = null;
+            timerExecutorService = null;
           }
         }
       }
@@ -295,10 +290,10 @@ public void finish(
 
   private void cancelIdleTimer() {
     try (final @NotNull ISentryLifecycleToken ignored = timerLock.acquire()) {
-      if (idleTimeoutTask != null) {
-        idleTimeoutTask.cancel();
+      if (idleTimeoutFuture != null) {
+        idleTimeoutFuture.cancel(false);
         isIdleFinishTimerRunning.set(false);
-        idleTimeoutTask = null;
+        idleTimeoutFuture = null;
       }
     }
   }
@@ -307,18 +302,12 @@ private void scheduleDeadlineTimeout() {
     final @Nullable Long deadlineTimeOut = transactionOptions.getDeadlineTimeout();
     if (deadlineTimeOut != null) {
       try (final @NotNull ISentryLifecycleToken ignored = timerLock.acquire()) {
-        if (timer != null) {
+        if (timerExecutorService != null) {
           cancelDeadlineTimer();
           isDeadlineTimerRunning.set(true);
-          deadlineTimeoutTask =
-              new TimerTask() {
-                @Override
-                public void run() {
-                  onDeadlineTimeoutReached();
-                }
-              };
           try {
-            timer.schedule(deadlineTimeoutTask, deadlineTimeOut);
+            deadlineTimeoutFuture =
+                timerExecutorService.schedule(this::onDeadlineTimeoutReached, deadlineTimeOut);
           } catch (Throwable e) {
             scopes
                 .getOptions()
@@ -335,10 +324,10 @@ public void run() {
 
   private void cancelDeadlineTimer() {
     try (final @NotNull ISentryLifecycleToken ignored = timerLock.acquire()) {
-      if (deadlineTimeoutTask != null) {
-        deadlineTimeoutTask.cancel();
+      if (deadlineTimeoutFuture != null) {
+        deadlineTimeoutFuture.cancel(false);
         isDeadlineTimerRunning.set(false);
-        deadlineTimeoutTask = null;
+        deadlineTimeoutFuture = null;
       }
     }
   }
@@ -973,20 +962,20 @@ Span getRoot() {
 
   @TestOnly
   @Nullable
-  TimerTask getIdleTimeoutTask() {
-    return idleTimeoutTask;
+  Future<?> getIdleTimeoutFuture() {
+    return idleTimeoutFuture;
   }
 
   @TestOnly
   @Nullable
-  TimerTask getDeadlineTimeoutTask() {
-    return deadlineTimeoutTask;
+  Future<?> getDeadlineTimeoutFuture() {
+    return deadlineTimeoutFuture;
   }
 
   @TestOnly
   @Nullable
-  Timer getTimer() {
-    return timer;
+  ISentryExecutorService getTimerExecutorService() {
+    return timerExecutorService;
   }
 
   @TestOnly

sentry/src/test/java/io/sentry/SentryTracerTest.kt

@@ -13,6 +13,7 @@ import kotlin.test.assertEquals
 import kotlin.test.assertFalse
 import kotlin.test.assertNotEquals
 import kotlin.test.assertNotNull
+import kotlin.test.assertNotSame
 import kotlin.test.assertNull
 import kotlin.test.assertSame
 import kotlin.test.assertTrue
@@ -913,15 +914,15 @@ class SentryTracerTest {
   @Test
   fun `when initialized without deadlineTimeout, does not schedule finish timer`() {
     val transaction = fixture.getSut()
-    assertNull(transaction.deadlineTimeoutTask)
+    assertNull(transaction.deadlineTimeoutFuture)
   }
 
   @Test
   fun `when initialized with deadlineTimeout, schedules finish timer`() {
     val transaction = fixture.getSut(deadlineTimeout = 50)
 
     assertTrue(transaction.isDeadlineTimerRunning.get())
-    assertNotNull(transaction.deadlineTimeoutTask)
+    assertNotNull(transaction.deadlineTimeoutFuture)
   }
 
   @Test
@@ -949,7 +950,7 @@ class SentryTracerTest {
     transaction.finish(SpanStatus.OK)
 
     assertEquals(transaction.isDeadlineTimerRunning.get(), false)
-    assertNull(transaction.deadlineTimeoutTask)
+    assertNull(transaction.deadlineTimeoutFuture)
     assertEquals(transaction.isFinished, true)
     assertEquals(SpanStatus.OK, transaction.status)
     assertEquals(SpanStatus.OK, span.status)
@@ -958,26 +959,26 @@ class SentryTracerTest {
   @Test
   fun `when initialized with idleTimeout it has no influence on deadline timeout`() {
     val transaction = fixture.getSut(idleTimeout = 3000, deadlineTimeout = 20)
-    val deadlineTimeoutTask = transaction.deadlineTimeoutTask
+    val deadlineTimeoutFuture = transaction.deadlineTimeoutFuture
 
     val span = transaction.startChild("op")
     // when the span finishes, it re-schedules the idle task
     span.finish()
 
     // but the deadline timeout task should not be re-scheduled
-    assertEquals(deadlineTimeoutTask, transaction.deadlineTimeoutTask)
+    assertSame(deadlineTimeoutFuture, transaction.deadlineTimeoutFuture)
   }
 
   @Test
   fun `when initialized without idleTimeout, does not schedule finish timer`() {
     val transaction = fixture.getSut()
-    assertNull(transaction.idleTimeoutTask)
+    assertNull(transaction.idleTimeoutFuture)
   }
 
   @Test
   fun `when initialized with idleTimeout, schedules finish timer`() {
     val transaction = fixture.getSut(idleTimeout = 50)
-    assertNotNull(transaction.idleTimeoutTask)
+    assertNotNull(transaction.idleTimeoutFuture)
   }
 
   @Test
@@ -1008,22 +1009,23 @@ class SentryTracerTest {
 
     transaction.startChild("op")
 
-    assertNull(transaction.idleTimeoutTask)
+    assertNull(transaction.idleTimeoutFuture)
   }
 
   @Test
   fun `when a child is finished and the transaction is idle, resets the timer`() {
     val transaction = fixture.getSut(waitForChildren = true, idleTimeout = 3000)
 
-    val initialTime = transaction.idleTimeoutTask!!.scheduledExecutionTime()
+    val initialFuture = transaction.idleTimeoutFuture
 
     val span = transaction.startChild("op")
-    Thread.sleep(1)
     span.finish()
 
-    val timerAfterFinishingChild = transaction.idleTimeoutTask!!.scheduledExecutionTime()
+    // finishing the child re-schedules the idle timeout, replacing the pending future
+    val futureAfterFinishingChild = transaction.idleTimeoutFuture
 
-    assertTrue { timerAfterFinishingChild > initialTime }
+    assertNotNull(futureAfterFinishingChild)
+    assertNotSame(initialFuture, futureAfterFinishingChild)
   }
 
   @Test
@@ -1035,7 +1037,7 @@ class SentryTracerTest {
     Thread.sleep(1)
     span.finish()
 
-    assertNull(transaction.idleTimeoutTask)
+    assertNull(transaction.idleTimeoutFuture)
   }
 
   @Test
@@ -1080,7 +1082,7 @@ class SentryTracerTest {
         trimEnd = true,
         samplingDecision = TracesSamplingDecision(true),
       )
-    assertNotNull(transaction.timer)
+    assertNotNull(transaction.timerExecutorService)
   }
 
   @Test
@@ -1092,7 +1094,7 @@ class SentryTracerTest {
         trimEnd = true,
         samplingDecision = TracesSamplingDecision(true),
       )
-    assertNull(transaction.timer)
+    assertNull(transaction.timerExecutorService)
   }
 
   @Test
@@ -1104,9 +1106,9 @@ class SentryTracerTest {
         trimEnd = true,
         samplingDecision = TracesSamplingDecision(true),
       )
-    assertNotNull(transaction.timer)
+    assertNotNull(transaction.timerExecutorService)
     transaction.finish(SpanStatus.OK)
-    assertNull(transaction.timer)
+    assertNull(transaction.timerExecutorService)
   }
 
   @Test
@@ -1539,18 +1541,18 @@ class SentryTracerTest {
   }
 
   @Test
-  fun `when timer is cancelled, schedule finish does not crash`() {
+  fun `when timer executor is shut down, schedule finish does not crash`() {
     val tracer = fixture.getSut(idleTimeout = 50, deadlineTimeout = 100)
-    tracer.timer!!.cancel()
+    fixture.options.executorService.close(0)
     tracer.scheduleFinish()
   }
 
   @Test
-  fun `when timer is cancelled, schedule finish finishes the transaction immediately`() {
+  fun `when timer executor is shut down, schedule finish finishes the transaction immediately`() {
     val tracer = fixture.getSut(idleTimeout = 50)
     tracer.startChild("load").finish()
 
-    tracer.timer!!.cancel()
+    fixture.options.executorService.close(0)
     tracer.scheduleFinish()
 
     assertTrue(tracer.isFinished)