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>

Author: runningcode

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

@@ -354,7 +354,9 @@ private static void init(final @NotNull SentryOptions options, final boolean glo
         }
 
         if (options.getTimerExecutorService().isClosed()) {
-          options.setTimerExecutorService(new SentryExecutorService(options, true));
+          options.setTimerExecutorService(
+              new SentryExecutorService(
+                  options, true, SentryExecutorService.TIMER_KEEP_ALIVE_SECONDS, TimeUnit.SECONDS));
         }
 
         // load lazy fields of the options in a separate thread

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,14 +45,16 @@ public SentryExecutorService(final @Nullable SentryOptions options) {
     this(new ScheduledThreadPoolExecutor(1, new SentryExecutorServiceThreadFactory()), options);
   }
 
-  SentryExecutorService(final @Nullable SentryOptions options, final boolean removeOnCancelPolicy) {
+  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);
-    // let the worker thread die when idle so an executor abandoned on SDK restart (its pending
-    // timeouts still fire) doesn't leak a live thread once its queue drains
-    executorService.setKeepAliveTime(10, TimeUnit.SECONDS);
+    executorService.setKeepAliveTime(keepAliveTime, keepAliveTimeUnit);
     executorService.allowCoreThreadTimeOut(true);
   }
 

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;
@@ -695,7 +696,9 @@ public void activate() {
       // 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);
+      timerExecutorService =
+          new SentryExecutorService(
+              this, true, SentryExecutorService.TIMER_KEEP_ALIVE_SECONDS, TimeUnit.SECONDS);
     }
 
     // SpotlightIntegration is loaded via reflection to allow the sentry-spotlight module

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

@@ -39,10 +39,9 @@ public final class SentryTracer implements ITransaction {
   private volatile @Nullable Future<?> idleTimeoutFuture;
   private volatile @Nullable Future<?> deadlineTimeoutFuture;
 
-  // 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;
+  // 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();
 
@@ -101,7 +100,7 @@ public SentryTracer(
 
     if (transactionOptions.getIdleTimeout() != null
         || transactionOptions.getDeadlineTimeout() != null) {
-      timerExecutorService = scopes.getOptions().getTimerExecutorService();
+      timersEnabled = true;
 
       scheduleDeadlineTimeout();
       scheduleFinish();
@@ -111,7 +110,7 @@ public SentryTracer(
   @Override
   public void scheduleFinish() {
     try (final @NotNull ISentryLifecycleToken ignored = timerLock.acquire()) {
-      if (timerExecutorService != null) {
+      if (timersEnabled) {
         final @Nullable Long idleTimeout = transactionOptions.getIdleTimeout();
 
         if (idleTimeout != null) {
@@ -120,7 +119,10 @@ public void scheduleFinish() {
 
           try {
             idleTimeoutFuture =
-                timerExecutorService.schedule(this::onIdleTimeoutReached, idleTimeout);
+                scopes
+                    .getOptions()
+                    .getTimerExecutorService()
+                    .schedule(this::onIdleTimeoutReached, idleTimeout);
           } catch (Throwable e) {
             scopes
                 .getOptions()
@@ -261,12 +263,12 @@ public void finish(
           });
       final SentryTransaction transaction = new SentryTransaction(this);
 
-      if (timerExecutorService != null) {
+      if (timersEnabled) {
         try (final @NotNull ISentryLifecycleToken ignored = timerLock.acquire()) {
-          if (timerExecutorService != null) {
+          if (timersEnabled) {
             cancelIdleTimer();
             cancelDeadlineTimer();
-            timerExecutorService = null;
+            timersEnabled = false;
           }
         }
       }
@@ -302,12 +304,15 @@ private void scheduleDeadlineTimeout() {
     final @Nullable Long deadlineTimeOut = transactionOptions.getDeadlineTimeout();
     if (deadlineTimeOut != null) {
       try (final @NotNull ISentryLifecycleToken ignored = timerLock.acquire()) {
-        if (timerExecutorService != null) {
+        if (timersEnabled) {
           cancelDeadlineTimer();
           isDeadlineTimerRunning.set(true);
           try {
             deadlineTimeoutFuture =
-                timerExecutorService.schedule(this::onDeadlineTimeoutReached, deadlineTimeOut);
+                scopes
+                    .getOptions()
+                    .getTimerExecutorService()
+                    .schedule(this::onDeadlineTimeoutReached, deadlineTimeOut);
           } catch (Throwable e) {
             scopes
                 .getOptions()
@@ -973,9 +978,8 @@ Future<?> getDeadlineTimeoutFuture() {
   }
 
   @TestOnly
-  @Nullable
-  ISentryExecutorService getTimerExecutorService() {
-    return timerExecutorService;
+  boolean areTimersEnabled() {
+    return timersEnabled;
   }
 
   @TestOnly

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
@@ -95,7 +96,7 @@ class SentryExecutorServiceTest {
 
   @Test
   fun `SentryExecutorService enables removeOnCancelPolicy when requested`() {
-    val sentryExecutor = SentryExecutorService(null, true)
+    val sentryExecutor = SentryExecutorService(null, true, 30, TimeUnit.SECONDS)
     val executor = sentryExecutor.getProperty<ScheduledThreadPoolExecutor>("executorService")
     assertTrue(executor.removeOnCancelPolicy)
     sentryExecutor.close(15000)

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

@@ -1082,7 +1082,7 @@ class SentryTracerTest {
         trimEnd = true,
         samplingDecision = TracesSamplingDecision(true),
       )
-    assertNotNull(transaction.timerExecutorService)
+    assertTrue(transaction.areTimersEnabled())
   }
 
   @Test
@@ -1094,7 +1094,7 @@ class SentryTracerTest {
         trimEnd = true,
         samplingDecision = TracesSamplingDecision(true),
       )
-    assertNull(transaction.timerExecutorService)
+    assertFalse(transaction.areTimersEnabled())
   }
 
   @Test
@@ -1106,9 +1106,9 @@ class SentryTracerTest {
         trimEnd = true,
         samplingDecision = TracesSamplingDecision(true),
       )
-    assertNotNull(transaction.timerExecutorService)
+    assertTrue(transaction.areTimersEnabled())
     transaction.finish(SpanStatus.OK)
-    assertNull(transaction.timerExecutorService)
+    assertFalse(transaction.areTimersEnabled())
   }
 
   @Test