perf(android): Defer SentryFrameMetricsCollector thread startup (#5641)

* perf(android): Start frame metrics thread lazily on first collection

SentryFrameMetricsCollector created and started its HandlerThread in the
constructor, blocking the calling thread (the main thread during SDK
init) on HandlerThread.getLooper(). The handler is only needed once
startCollection() registers a listener, so start the thread lazily there
instead. Apps that never collect frame metrics no longer start the
thread at all.

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

* changelog

---------

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

Author: runningcode

CHANGELOG.md

@@ -15,6 +15,7 @@
 - Speed up touch gesture target detection on deeply nested view hierarchies by hit-testing in local coordinates instead of calling `getLocationOnScreen` per view ([#5595](https://github.com/getsentry/sentry-java/pull/5595))
 - Probe class availability without initializing the class during SDK init ([#5635](https://github.com/getsentry/sentry-java/pull/5635))
 - Avoid constructing an exception per view when resolving view ids during view-hierarchy and gesture capture ([#5631](https://github.com/getsentry/sentry-java/pull/5631))
+- Start the frame metrics thread lazily on first collection instead of during SDK init ([#5641](https://github.com/getsentry/sentry-java/pull/5641))
 
 ## 8.46.0
 

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

@@ -14,12 +14,14 @@
 import android.view.Window;
 import androidx.annotation.RequiresApi;
 import io.sentry.ILogger;
+import io.sentry.ISentryLifecycleToken;
 import io.sentry.SentryLevel;
 import io.sentry.SentryOptions;
 import io.sentry.SentryUUID;
 import io.sentry.android.core.BuildInfoProvider;
 import io.sentry.android.core.ContextUtils;
 import io.sentry.android.core.SentryFramesDelayResult;
+import io.sentry.util.AutoClosableReentrantLock;
 import io.sentry.util.Objects;
 import java.lang.ref.WeakReference;
 import java.lang.reflect.Field;
@@ -45,7 +47,8 @@ public final class SentryFrameMetricsCollector implements Application.ActivityLi
   private final @NotNull Set<Window> trackedWindows = new CopyOnWriteArraySet<>();
 
   private final @NotNull ILogger logger;
-  private @Nullable Handler handler;
+  private volatile @Nullable Handler handler;
+  private final @NotNull AutoClosableReentrantLock handlerLock = new AutoClosableReentrantLock();
   private @Nullable WeakReference<Window> currentWindow;
   private final @NotNull Map<String, FrameMetricsCollectorListener> listenerMap =
       new ConcurrentHashMap<>();
@@ -113,12 +116,8 @@ public SentryFrameMetricsCollector(
     }
     isAvailable = true;
 
-    HandlerThread handlerThread =
-        new HandlerThread("io.sentry.android.core.internal.util.SentryFrameMetricsCollector");
-    handlerThread.setUncaughtExceptionHandler(
-        (thread, e) -> logger.log(SentryLevel.ERROR, "Error during frames measurements.", e));
-    handlerThread.start();
-    handler = new Handler(handlerThread.getLooper());
+    // The frame metrics HandlerThread is started lazily on the first startCollection() call.
+    // Starting it here would block the main thread on HandlerThread.getLooper() during SDK init.
 
     // We have to register the lifecycle callback, even if no profile is started, otherwise when we
     // start a profile, we wouldn't have the current activity and couldn't get the frameMetrics.
@@ -281,12 +280,34 @@ public void onActivityDestroyed(@NotNull Activity activity) {}
     if (!isAvailable) {
       return null;
     }
+    ensureHandlerThreadStarted();
     final String uid = SentryUUID.generateSentryId();
     listenerMap.put(uid, listener);
     trackCurrentWindow();
     return uid;
   }
 
+  /**
+   * Lazily starts the background HandlerThread used to receive frame metrics. Deferred out of the
+   * constructor because {@link HandlerThread#getLooper()} blocks the caller (the main thread during
+   * SDK init) until the thread is ready, and the handler is only needed once collection starts.
+   */
+  private void ensureHandlerThreadStarted() {
+    if (handler != null) {
+      return;
+    }
+    try (final @NotNull ISentryLifecycleToken ignored = handlerLock.acquire()) {
+      if (handler == null) {
+        final HandlerThread handlerThread =
+            new HandlerThread("io.sentry.android.core.internal.util.SentryFrameMetricsCollector");
+        handlerThread.setUncaughtExceptionHandler(
+            (thread, e) -> logger.log(SentryLevel.ERROR, "Error during frames measurements.", e));
+        handlerThread.start();
+        handler = new Handler(handlerThread.getLooper());
+      }
+    }
+  }
+
   public void stopCollection(final @Nullable String listenerId) {
     if (!isAvailable) {
       return;

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

@@ -141,6 +141,16 @@ class SentryFrameMetricsCollectorTest {
     assertNotNull(id)
   }
 
+  @Test
+  fun `handler thread is started lazily on first startCollection`() {
+    val collector = fixture.getSut(context)
+    // not started during construction (would block the main thread on getLooper at SDK init)
+    assertNull(collector.getProperty<Handler?>("handler"))
+
+    collector.startCollection(mock())
+    assertNotNull(collector.getProperty<Handler?>("handler"))
+  }
+
   @Test
   fun `collector calls addOnFrameMetricsAvailableListener when an activity starts`() {
     val collector = fixture.getSut(context)