From bb468433fe007f214bb134ebee7fe09e5771778c Mon Sep 17 00:00:00 2001 From: Giancarlo Buenaflor Date: Tue, 7 Jul 2026 22:59:27 +0200 Subject: [PATCH 1/2] docs(android): Document standalone app start tracing and extend API Mirror the Apple auto-instrumentation page for Android. Add a Standalone App Start Tracing section with enablement (manifest and code) and an app.start tracesSampler example, plus an Extending the App Start subsection covering extendAppStart(), getExtendedAppStartSpan(), and finishExtendedAppStart() in Java and Kotlin. Co-Authored-By: Claude --- .../automatic-instrumentation.mdx | 120 +++++++++++++++++- 1 file changed, 119 insertions(+), 1 deletion(-) diff --git a/docs/platforms/android/tracing/instrumentation/automatic-instrumentation.mdx b/docs/platforms/android/tracing/instrumentation/automatic-instrumentation.mdx index f9d364d15f36d..1d0078a124a61 100644 --- a/docs/platforms/android/tracing/instrumentation/automatic-instrumentation.mdx +++ b/docs/platforms/android/tracing/instrumentation/automatic-instrumentation.mdx @@ -159,6 +159,122 @@ You can opt out of Activity Instrumentation and App Start Instrumentation using Cold and warm start are Mobile Vitals, which you can learn about in the [full documentation](/product/dashboards/sentry-dashboards/mobile/mobile-vitals). +### Standalone App Start Tracing + + + +This feature is experimental. The API is subject to change and may introduce breaking changes in future releases. + + + +By default, app start data is attached as spans to the first transaction in your app. Standalone app start tracing sends app start data as its own separate transaction instead. This gives you more accurate app start measurements, since they aren't dependent on another transaction being started. + +To enable standalone app start tracing, add the following to your `AndroidManifest.xml`: + +```xml {filename:AndroidManifest.xml} + + + +``` + +Or, configure it manually in code: + +```java +import io.sentry.android.core.SentryAndroid; + +SentryAndroid.init(this, options -> { + options.setEnableStandaloneAppStartTracing(true); +}); +``` + +```kotlin +import io.sentry.android.core.SentryAndroid + +SentryAndroid.init(this) { options -> + options.isEnableStandaloneAppStartTracing = true +} +``` + +Since standalone app start transactions use the `app.start` operation, you can use a custom `tracesSampler` to set a dedicated sample rate for app starts without increasing your overall sample rate: + +```java +import io.sentry.android.core.SentryAndroid; + +SentryAndroid.init(this, options -> { + options.setEnableStandaloneAppStartTracing(true); + options.setTracesSampler(context -> { + if ("app.start".equals(context.getTransactionContext().getOperation())) { + return 1.0; + } + return 0.1; + }); +}); +``` + +```kotlin +import io.sentry.SentryOptions.TracesSamplerCallback +import io.sentry.android.core.SentryAndroid + +SentryAndroid.init(this) { options -> + options.isEnableStandaloneAppStartTracing = true + options.tracesSampler = TracesSamplerCallback { context -> + if (context.transactionContext.operation == "app.start") { + 1.0 + } else { + 0.1 + } + } +} +``` + +#### Extending the App Start + + + +Available since version `8.48.0`. + + + +By default, the standalone app start transaction ends when the first frame is drawn. If your app performs additional work after that — such as loading initial data from a server or database — you can extend the app start transaction to include that time by calling `Sentry.extendAppStart()`. + +Call `Sentry.extendAppStart()` in `Application.onCreate`, after the SDK is initialized, so the SDK doesn't automatically finish the app start transaction when the first frame is drawn. Retrieve the extended app start span with `Sentry.getExtendedAppStartSpan()` to add child spans that break down the extended launch period, and call `Sentry.finishExtendedAppStart()` when your app is fully ready. + +```java +import io.sentry.ISpan; +import io.sentry.Sentry; + +Sentry.extendAppStart(); + +// Optionally, retrieve the extended app start span to attach your own child spans +ISpan extendedSpan = Sentry.getExtendedAppStartSpan(); +ISpan child = extendedSpan != null ? extendedSpan.startChild("preload", "Preload resources") : null; +// ... extra launch-time work ... +if (child != null) { + child.finish(); +} + +Sentry.finishExtendedAppStart(); +``` + +```kotlin +import io.sentry.Sentry + +Sentry.extendAppStart() + +// Optionally, retrieve the extended app start span to attach your own child spans +val child = Sentry.getExtendedAppStartSpan()?.startChild("preload", "Preload resources") +// ... extra launch-time work ... +child?.finish() + +Sentry.finishExtendedAppStart() +``` + + + +Extending the app start requires standalone app start tracing to be enabled. If `enableStandaloneAppStartTracing` is off, or the app start transaction was already created, `Sentry.getExtendedAppStartSpan()` returns `null` and `Sentry.finishExtendedAppStart()` is a no-op. + + + ### Slow and Frozen Frames @@ -352,6 +468,7 @@ To change the timeouts you can: ``` + ```java import io.sentry.android.core.SentryAndroid; @@ -360,6 +477,7 @@ SentryAndroid.init(this, options -> { options.setDeadlineTimeout(0); // disable deadline timeout }); ``` + ```kotlin import io.sentry.android.core.SentryAndroid @@ -436,7 +554,7 @@ When the UI transaction is not finished yet, but the user makes a new interactio _(New in version 6.10.0)_ -By adding a span for each launch of an activity, time to initial display (TTID) provides insight into how long it takes for your activities to launch and draw their first UI frame. The SDK sets the span operation to `ui.load.initial-display` and the span description to the activity's name, followed by `initial display` - for example, `MainActivity initial display`. +By adding a span for each launch of an activity, time to initial display (TTID) provides insight into how long it takes for your activities to launch and draw their first UI frame. The SDK sets the span operation to `ui.load.initial-display` and the span description to the activity's name, followed by `initial display` - for example, `MainActivity initial display`. The span starts when each Activity is launched, which is defined as an application launch for the first Activity, and the `onPause` method of the previous Activity for each subsequent Activity launched. From 4c14611f951eae8fba879bcd898ee0c504338a15 Mon Sep 17 00:00:00 2001 From: Giancarlo Buenaflor Date: Tue, 7 Jul 2026 23:02:28 +0200 Subject: [PATCH 2/2] docs(android): Note extended app start timeout and early-finish behavior Document that the extended app start span auto-finishes after 30 seconds (dropping the app start measurement) and that finishing before the first frame falls back to the natural app start end. Co-Authored-By: Claude --- .../tracing/instrumentation/automatic-instrumentation.mdx | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/platforms/android/tracing/instrumentation/automatic-instrumentation.mdx b/docs/platforms/android/tracing/instrumentation/automatic-instrumentation.mdx index 1d0078a124a61..41229450701ea 100644 --- a/docs/platforms/android/tracing/instrumentation/automatic-instrumentation.mdx +++ b/docs/platforms/android/tracing/instrumentation/automatic-instrumentation.mdx @@ -269,6 +269,10 @@ child?.finish() Sentry.finishExtendedAppStart() ``` +Make sure to call `Sentry.finishExtendedAppStart()` once your launch-time work is done. If the extended app start isn't finished within 30 seconds, the SDK finishes the span automatically and drops the app start measurement, so no app start is reported. + +If you finish the extended app start before the first frame is drawn (the natural end of the app start), the SDK uses the natural app start end instead, so the reported measurement is never shorter than the actual app start. + Extending the app start requires standalone app start tracing to be enabled. If `enableStandaloneAppStartTracing` is off, or the app start transaction was already created, `Sentry.getExtendedAppStartSpan()` returns `null` and `Sentry.finishExtendedAppStart()` is a no-op.