perf: Avoid per-transaction Timer thread in SentryTracer (JAVA-596) (#5670)

* 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 a dedicated, shared
ISentryExecutorService held by SentryOptions instead, so no thread is
created per transaction. It is kept separate from the main executor so
timeout callbacks (which finish transactions) don't contend with cached
event sending, and it is not prewarmed: its single worker thread is
spawned lazily on the first scheduled timeout and reused thereafter. The
dedicated executor uses removeOnCancelPolicy so cancelled timeouts (idle
timers are rescheduled per child span) don't accumulate in its queue. On
finish only the scheduled futures are cancelled; the executor is closed
with the SDK.

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

* changelog

* fix(core): Keep timer executor alive across SDK restart (JAVA-570)

The shared timer executor introduced for transaction idle/deadline
timeouts was shut down on every Scopes.close(), including SDK restart.
This cancelled the pending idle timeout of any transaction started
before the restart (e.g. an in-flight activity transaction), so it
never auto-finished and its envelope was never sent.

Only close the timer executor on a full close, not on restart, matching
the pre-existing per-transaction Timer behaviour. Enable core-thread
timeout on the timer executor so the instance abandoned by a restart
self-terminates once idle instead of leaking a thread.

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

* refactor(core): Look up shared timer executor on demand (JAVA-570)

SentryTracer cached the shared timer executor in a field for the
lifetime of the transaction. Replace that field with a boolean flag
tracking whether timeouts may still be scheduled, and fetch the
executor from the options each time one is scheduled. This ensures the
tracer always uses the executor currently held by the options (e.g. the
fresh one installed after an SDK restart) rather than a stale reference.

Also make the timer executor's keep-alive duration a constructor
argument backed by the named TIMER_KEEP_ALIVE_SECONDS constant, and
raise it from 10s to 30s so the shared worker thread is less likely to
be torn down and respawned between transactions under normal use.

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

---------

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

Author: runningcode

CHANGELOG.md

@@ -35,6 +35,10 @@
 - Prevent logs and metrics from remaining queued after a flush scheduling race ([#5756](https://github.com/getsentry/sentry-java/pull/5756))
 - Fix main thread identification for tombstone (native crash) events ([#5742](https://github.com/getsentry/sentry-java/pull/5742))
 
+### Performance
+
+- Schedule transaction idle/deadline timeouts on a shared, dedicated executor instead of spawning a `Timer` thread per transaction ([#5670](https://github.com/getsentry/sentry-java/pull/5670))
+
 ### Dependencies
 
 - Bump OpenTelemetry to support Spring Boot 4.1 ([#5573](https://github.com/getsentry/sentry-java/pull/5573))

sentry-android-core/src/test/java/io/sentry/android/core/ActivityLifecycleIntegrationTest.kt

@@ -23,6 +23,7 @@ import io.sentry.Scopes
 import io.sentry.Sentry
 import io.sentry.SentryDate
 import io.sentry.SentryDateProvider
+import io.sentry.SentryExecutorService
 import io.sentry.SentryNanotimeDate
 import io.sentry.SentryTraceHeader
 import io.sentry.SentryTracer
@@ -919,6 +920,8 @@ class ActivityLifecycleIntegrationTest {
           it.idleTimeout = 100
         }
       )
+    // the transaction idle timeout is scheduled on the dedicated timer executor
+    fixture.options.timerExecutorService = SentryExecutorService()
     sut.register(fixture.scopes, fixture.options)
     sut.onActivityCreated(activity, fixture.bundle)
 

sentry/api/sentry.api

@@ -3719,6 +3719,7 @@ public class io/sentry/SentryOptions {
 	public fun getSslSocketFactory ()Ljavax/net/ssl/SSLSocketFactory;
 	public fun getTags ()Ljava/util/Map;
 	public fun getThreadChecker ()Lio/sentry/util/thread/IThreadChecker;
+	public fun getTimerExecutorService ()Lio/sentry/ISentryExecutorService;
 	public fun getTracePropagationTargets ()Ljava/util/List;
 	public fun getTracesSampleRate ()Ljava/lang/Double;
 	public fun getTracesSampler ()Lio/sentry/SentryOptions$TracesSamplerCallback;
@@ -3884,6 +3885,7 @@ public class io/sentry/SentryOptions {
 	public fun setStrictTraceContinuation (Z)V
 	public fun setTag (Ljava/lang/String;Ljava/lang/String;)V
 	public fun setThreadChecker (Lio/sentry/util/thread/IThreadChecker;)V
+	public fun setTimerExecutorService (Lio/sentry/ISentryExecutorService;)V
 	public fun setTraceOptionsRequests (Z)V
 	public fun setTracePropagationTargets (Ljava/util/List;)V
 	public fun setTraceSampling (Z)V

sentry/src/main/java/io/sentry/Scopes.java

@@ -467,6 +467,12 @@ public void close(final boolean isRestarting) {
         getOptions().getContinuousProfiler().close(true);
         getOptions().getCompositePerformanceCollector().close();
         getOptions().getConnectionStatusProvider().close();
+        // On restart we intentionally leave the timer executor running so that pending idle/
+        // deadline timeouts of transactions started before the restart still fire and finish
+        // those transactions. It self-terminates once idle (allowCoreThreadTimeOut).
+        if (!isRestarting) {
+          getOptions().getTimerExecutorService().close(getOptions().getShutdownTimeoutMillis());
+        }
         final @NotNull ISentryExecutorService executorService = getOptions().getExecutorService();
         if (isRestarting) {
           try {

sentry/src/main/java/io/sentry/Sentry.java

@@ -353,6 +353,12 @@ private static void init(final @NotNull SentryOptions options, final boolean glo
           options.setExecutorService(new SentryExecutorService(options));
         }
 
+        if (options.getTimerExecutorService().isClosed()) {
+          options.setTimerExecutorService(
+              new SentryExecutorService(
+                  options, true, SentryExecutorService.TIMER_KEEP_ALIVE_SECONDS, TimeUnit.SECONDS));
+        }
+
         // load lazy fields of the options in a separate thread
         try {
           options.getExecutorService().submit(() -> options.loadLazyFields());

sentry/src/main/java/io/sentry/SentryExecutorService.java

@@ -22,6 +22,12 @@ public final class SentryExecutorService implements ISentryExecutorService {
    */
   private static final int MAX_QUEUE_SIZE = 271;
 
+  /**
+   * How long the timer executor's worker thread stays alive while idle before self-terminating, so
+   * an instance abandoned on SDK restart doesn't leak a live thread once its queue drains.
+   */
+  static final long TIMER_KEEP_ALIVE_SECONDS = 30;
+
   private final @NotNull ScheduledThreadPoolExecutor executorService;
   private final @NotNull AutoClosableReentrantLock lock = new AutoClosableReentrantLock();
 
@@ -39,6 +45,19 @@ public SentryExecutorService(final @Nullable SentryOptions options) {
     this(new ScheduledThreadPoolExecutor(1, new SentryExecutorServiceThreadFactory()), options);
   }
 
+  SentryExecutorService(
+      final @Nullable SentryOptions options,
+      final boolean removeOnCancelPolicy,
+      final long keepAliveTime,
+      final @NotNull TimeUnit keepAliveTimeUnit) {
+    this(options);
+    // removes cancelled tasks from the work queue immediately instead of leaving them until their
+    // scheduled time; useful for executors that frequently reschedule (e.g. transaction timeouts)
+    executorService.setRemoveOnCancelPolicy(removeOnCancelPolicy);
+    executorService.setKeepAliveTime(keepAliveTime, keepAliveTimeUnit);
+    executorService.allowCoreThreadTimeOut(true);
+  }
+
   public SentryExecutorService() {
     this(new ScheduledThreadPoolExecutor(1, new SentryExecutorServiceThreadFactory()), null);
   }

sentry/src/main/java/io/sentry/SentryOptions.java

@@ -44,6 +44,7 @@
 import java.util.concurrent.ConcurrentHashMap;
 import java.util.concurrent.CopyOnWriteArrayList;
 import java.util.concurrent.CopyOnWriteArraySet;
+import java.util.concurrent.TimeUnit;
 import java.util.concurrent.atomic.AtomicBoolean;
 import javax.net.ssl.SSLSocketFactory;
 import org.jetbrains.annotations.ApiStatus;
@@ -317,6 +318,14 @@ public class SentryOptions {
   /** Sentry Executor Service that sends cached events and envelopes on App. start. */
   private @NotNull ISentryExecutorService executorService = NoOpSentryExecutorService.getInstance();
 
+  /**
+   * Dedicated executor for scheduling transaction idle/deadline timeouts. Kept separate from {@link
+   * #executorService} so timeout callbacks (which finish transactions) don't contend with cached
+   * event sending.
+   */
+  private @NotNull ISentryExecutorService timerExecutorService =
+      NoOpSentryExecutorService.getInstance();
+
   /**
    * Whether SpotlightIntegration has already been loaded via reflection. This prevents re-adding it
    * if the user removed it in their configuration callback and activate() is called again.
@@ -683,6 +692,15 @@ public void activate() {
       executorService = new SentryExecutorService(this);
     }
 
+    if (timerExecutorService instanceof NoOpSentryExecutorService) {
+      // Not prewarmed: its single worker thread is spawned lazily on the first scheduled timeout
+      // and then reused across all transactions. removeOnCancelPolicy keeps the work queue from
+      // accumulating cancelled timeouts (idle timers are cancelled and rescheduled per child span).
+      timerExecutorService =
+          new SentryExecutorService(
+              this, true, SentryExecutorService.TIMER_KEEP_ALIVE_SECONDS, TimeUnit.SECONDS);
+    }
+
     // SpotlightIntegration is loaded via reflection to allow the sentry-spotlight module
     // to be excluded from release builds, preventing insecure HTTP URLs from appearing in APKs.
     // Only attempt once to avoid re-adding after user removal in their configuration callback.
@@ -1570,6 +1588,30 @@ public void setExecutorService(final @NotNull ISentryExecutorService executorSer
     }
   }
 
+  /**
+   * Returns the dedicated executor used to schedule transaction idle/deadline timeouts.
+   *
+   * @return the timer executor service
+   */
+  @ApiStatus.Internal
+  @NotNull
+  public ISentryExecutorService getTimerExecutorService() {
+    return timerExecutorService;
+  }
+
+  /**
+   * Sets the dedicated executor used to schedule transaction idle/deadline timeouts.
+   *
+   * @param timerExecutorService the timer executor service
+   */
+  @ApiStatus.Internal
+  @TestOnly
+  public void setTimerExecutorService(final @NotNull ISentryExecutorService timerExecutorService) {
+    if (timerExecutorService != null) {
+      this.timerExecutorService = timerExecutorService;
+    }
+  }
+
   /**
    * Returns the connection timeout in milliseconds.
    *

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,12 @@ 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;
+  // Whether timeout tasks may still be scheduled. Set to false once the tracer is finished. The
+  // executor itself is owned by the options (shared SDK-wide) and obtained from there when needed.
+  private volatile boolean timersEnabled = false;
   private final @NotNull AutoClosableReentrantLock timerLock = new AutoClosableReentrantLock();
   private final @NotNull AutoClosableReentrantLock tracerLock = new AutoClosableReentrantLock();
 
@@ -99,7 +100,7 @@ public SentryTracer(
 
     if (transactionOptions.getIdleTimeout() != null
         || transactionOptions.getDeadlineTimeout() != null) {
-      timer = new Timer(true);
+      timersEnabled = true;
 
       scheduleDeadlineTimeout();
       scheduleFinish();
@@ -109,22 +110,19 @@ public SentryTracer(
   @Override
   public void scheduleFinish() {
     try (final @NotNull ISentryLifecycleToken ignored = timerLock.acquire()) {
-      if (timer != null) {
+      if (timersEnabled) {
         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 =
+                scopes
+                    .getOptions()
+                    .getTimerExecutorService()
+                    .schedule(this::onIdleTimeoutReached, idleTimeout);
           } catch (Throwable e) {
             scopes
                 .getOptions()
@@ -265,13 +263,12 @@ public void finish(
           });
       final SentryTransaction transaction = new SentryTransaction(this);
 
-      if (timer != null) {
+      if (timersEnabled) {
         try (final @NotNull ISentryLifecycleToken ignored = timerLock.acquire()) {
-          if (timer != null) {
+          if (timersEnabled) {
             cancelIdleTimer();
             cancelDeadlineTimer();
-            timer.cancel();
-            timer = null;
+            timersEnabled = false;
           }
         }
       }
@@ -295,10 +292,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 +304,15 @@ private void scheduleDeadlineTimeout() {
     final @Nullable Long deadlineTimeOut = transactionOptions.getDeadlineTimeout();
     if (deadlineTimeOut != null) {
       try (final @NotNull ISentryLifecycleToken ignored = timerLock.acquire()) {
-        if (timer != null) {
+        if (timersEnabled) {
           cancelDeadlineTimer();
           isDeadlineTimerRunning.set(true);
-          deadlineTimeoutTask =
-              new TimerTask() {
-                @Override
-                public void run() {
-                  onDeadlineTimeoutReached();
-                }
-              };
           try {
-            timer.schedule(deadlineTimeoutTask, deadlineTimeOut);
+            deadlineTimeoutFuture =
+                scopes
+                    .getOptions()
+                    .getTimerExecutorService()
+                    .schedule(this::onDeadlineTimeoutReached, deadlineTimeOut);
           } catch (Throwable e) {
             scopes
                 .getOptions()
@@ -335,10 +329,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 +967,19 @@ 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;
+  boolean areTimersEnabled() {
+    return timersEnabled;
   }
 
   @TestOnly

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

@@ -1946,6 +1946,32 @@ class ScopesTest {
     verify(executor).close(any())
   }
 
+  @Test
+  fun `Scopes with isRestarting true should not close the timer executor`() {
+    val timerExecutor = mock<ISentryExecutorService>()
+    val options =
+      SentryOptions().apply {
+        dsn = "https://key@sentry.io/proj"
+        setTimerExecutorService(timerExecutor)
+      }
+    val sut = createScopes(options)
+    sut.close(true)
+    verify(timerExecutor, never()).close(any())
+  }
+
+  @Test
+  fun `Scopes with isRestarting false should close the timer executor`() {
+    val timerExecutor = mock<ISentryExecutorService>()
+    val options =
+      SentryOptions().apply {
+        dsn = "https://key@sentry.io/proj"
+        setTimerExecutorService(timerExecutor)
+      }
+    val sut = createScopes(options)
+    sut.close(false)
+    verify(timerExecutor).close(any())
+  }
+
   @Test
   fun `Scopes close should clear the scope`() {
     val options = SentryOptions().apply { dsn = "https://key@sentry.io/proj" }

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

@@ -1,5 +1,6 @@
 package io.sentry
 
+import io.sentry.test.getProperty
 import java.util.concurrent.BlockingQueue
 import java.util.concurrent.Callable
 import java.util.concurrent.CancellationException
@@ -93,6 +94,22 @@ class SentryExecutorServiceTest {
     sentryExecutor.close(15000)
   }
 
+  @Test
+  fun `SentryExecutorService enables removeOnCancelPolicy when requested`() {
+    val sentryExecutor = SentryExecutorService(null, true, 30, TimeUnit.SECONDS)
+    val executor = sentryExecutor.getProperty<ScheduledThreadPoolExecutor>("executorService")
+    assertTrue(executor.removeOnCancelPolicy)
+    sentryExecutor.close(15000)
+  }
+
+  @Test
+  fun `SentryExecutorService does not enable removeOnCancelPolicy by default`() {
+    val sentryExecutor = SentryExecutorService(null)
+    val executor = sentryExecutor.getProperty<ScheduledThreadPoolExecutor>("executorService")
+    assertFalse(executor.removeOnCancelPolicy)
+    sentryExecutor.close(15000)
+  }
+
   @Test
   fun `SentryExecutorService isClosed returns true if executor is shutdown`() {
     val executor = mock<ScheduledThreadPoolExecutor>()