Skip to content

perf(android): Defer SentryFrameMetricsCollector thread startup #5641

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
runningcode wants to merge 2 commits into
base: main
Choose a base branch
from
+44 −7
Open

perf(android): Defer SentryFrameMetricsCollector thread startup #5641

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
87bc6be
perf(android): Start frame metrics thread lazily on first collection
runningcode Jun 25, 2026
b557893
changelog
runningcode Jun 25, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,11 @@
# Changelog

## Unreleased

### Performance

- Start the frame metrics thread lazily on first collection instead of during SDK init ([#5641](https://github.com/getsentry/sentry-java/pull/5641))

## 8.45.0

### Features
Expand Down
35 changes: 28 additions & 7 deletions ...-core/src/main/java/io/sentry/android/core/internal/util/SentryFrameMetricsCollector.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand All @@ -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<>();
Expand Down Expand Up @@ -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.

@runningcode runningcode Jun 26, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I feel like this comment isn't useful here since this isn't where one would look for it. I'll remove it after a review unless anyone thinks otherwise.

@0xadam-brown 0xadam-brown Jun 26, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agreed ⚡

// 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.
Expand Down Expand Up @@ -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.

@0xadam-brown 0xadam-brown Jun 26, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🥇

*/
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());
}
}

@0xadam-brown 0xadam-brown Jun 26, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

m: Thoughts about catching Exception? (eg, looks like there's an off chance handlerThread.getLooper() could return null + cause the Handler constructor to throw an NPE if the thread dies before its looper is prepared).

(I realize we didn't do so before, but now we'll be starting the handler thread outside of Sentry.init() at a time when developers may be less likely to have their own try-catch or when it's harder to diagnose.)

}

public void stopCollection(final @Nullable String listenerId) {
if (!isAvailable) {
return;
Expand Down
10 changes: 10 additions & 0 deletions ...ore/src/test/java/io/sentry/android/core/internal/util/SentryFrameMetricsCollectorTest.kt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
Loading