From bb468433fe007f214bb134ebee7fe09e5771778c Mon Sep 17 00:00:00 2001 From: Giancarlo Buenaflor Date: Tue, 7 Jul 2026 22:59:27 +0200 Subject: [PATCH 01/11] 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 02/11] 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. From 9ede78436a6f92f96fc3f7e17843e6d35696f0c2 Mon Sep 17 00:00:00 2001 From: Giancarlo Buenaflor Date: Mon, 13 Jul 2026 10:24:48 +0200 Subject: [PATCH 03/11] docs(android): Align app start examples with page style Use the page established indentation for the new XML, Java, and Kotlin snippets. Present the SDK version note with the existing inline convention. Co-Authored-By: Claude --- .../automatic-instrumentation.mdx | 42 +++++++++---------- 1 file changed, 19 insertions(+), 23 deletions(-) diff --git a/docs/platforms/android/tracing/instrumentation/automatic-instrumentation.mdx b/docs/platforms/android/tracing/instrumentation/automatic-instrumentation.mdx index 41229450701ea..242a3a5b3c7a4 100644 --- a/docs/platforms/android/tracing/instrumentation/automatic-instrumentation.mdx +++ b/docs/platforms/android/tracing/instrumentation/automatic-instrumentation.mdx @@ -173,7 +173,7 @@ To enable standalone app start tracing, add the following to your `AndroidManife ```xml {filename:AndroidManifest.xml} - + ``` @@ -183,7 +183,7 @@ Or, configure it manually in code: import io.sentry.android.core.SentryAndroid; SentryAndroid.init(this, options -> { - options.setEnableStandaloneAppStartTracing(true); + options.setEnableStandaloneAppStartTracing(true); }); ``` @@ -191,7 +191,7 @@ SentryAndroid.init(this, options -> { import io.sentry.android.core.SentryAndroid SentryAndroid.init(this) { options -> - options.isEnableStandaloneAppStartTracing = true + options.isEnableStandaloneAppStartTracing = true } ``` @@ -201,13 +201,13 @@ Since standalone app start transactions use the `app.start` operation, you can u 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; - }); + options.setEnableStandaloneAppStartTracing(true); + options.setTracesSampler(context -> { + if ("app.start".equals(context.getTransactionContext().getOperation())) { + return 1.0; + } + return 0.1; + }); }); ``` @@ -216,24 +216,20 @@ 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 - } + 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`. - - +_(New in 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()`. @@ -250,7 +246,7 @@ ISpan extendedSpan = Sentry.getExtendedAppStartSpan(); ISpan child = extendedSpan != null ? extendedSpan.startChild("preload", "Preload resources") : null; // ... extra launch-time work ... if (child != null) { - child.finish(); + child.finish(); } Sentry.finishExtendedAppStart(); From 9665925885a7d4bd59cd092dda082abe592f63f6 Mon Sep 17 00:00:00 2001 From: Giancarlo Buenaflor Date: Mon, 13 Jul 2026 11:02:08 +0200 Subject: [PATCH 04/11] docs(android): Clarify extended app start deadline behavior Distinguish the standalone app.start transaction from cold and warm app start spans. Explain that a deadline suppresses the measurement while preserving the transaction and spans. Co-Authored-By: Claude --- .../tracing/instrumentation/automatic-instrumentation.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/platforms/android/tracing/instrumentation/automatic-instrumentation.mdx b/docs/platforms/android/tracing/instrumentation/automatic-instrumentation.mdx index 242a3a5b3c7a4..cea4f3d9b24ae 100644 --- a/docs/platforms/android/tracing/instrumentation/automatic-instrumentation.mdx +++ b/docs/platforms/android/tracing/instrumentation/automatic-instrumentation.mdx @@ -195,7 +195,7 @@ SentryAndroid.init(this) { options -> } ``` -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: +Unlike the `app.start.cold` and `app.start.warm` spans described above, standalone app start tracing uses the `app.start` operation for its transaction. 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; @@ -265,7 +265,7 @@ 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. +Make sure to call `Sentry.finishExtendedAppStart()` once your launch-time work is done. By default, if the extended app start isn't finished within the 30-second [deadline timeout](/platforms/android/configuration/options/#deadlineTimeout), the SDK finishes the extended span with `DEADLINE_EXCEEDED` and suppresses the cold or warm app start measurement. The standalone `app.start` transaction and its spans are still sent. 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. From 0fba9a37e92143e80e47144aaa06df6929757cfc Mon Sep 17 00:00:00 2001 From: Giancarlo Buenaflor Date: Mon, 13 Jul 2026 11:10:55 +0200 Subject: [PATCH 05/11] docs(android): Show app start extension placement Place the Java and Kotlin examples in Application.onCreate so developers call the extension while the app start window is open. Clarify initialization order for automatic and manual setup. Co-Authored-By: Claude --- .../automatic-instrumentation.mdx | 56 +++++++++++++------ 1 file changed, 38 insertions(+), 18 deletions(-) diff --git a/docs/platforms/android/tracing/instrumentation/automatic-instrumentation.mdx b/docs/platforms/android/tracing/instrumentation/automatic-instrumentation.mdx index cea4f3d9b24ae..bcb361511988f 100644 --- a/docs/platforms/android/tracing/instrumentation/automatic-instrumentation.mdx +++ b/docs/platforms/android/tracing/instrumentation/automatic-instrumentation.mdx @@ -233,36 +233,56 @@ _(New in 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. +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. With automatic initialization, the SDK is ready before `Application.onCreate` runs. If you initialize the SDK manually, call `SentryAndroid.init()` before `Sentry.extendAppStart()`. -```java +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 {filename:MyApplication.java} +import android.app.Application; import io.sentry.ISpan; import io.sentry.Sentry; -Sentry.extendAppStart(); +public final class MyApplication extends Application { + @Override + public void onCreate() { + super.onCreate(); + + 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(); + } -// 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(); + } } - -Sentry.finishExtendedAppStart(); ``` -```kotlin +```kotlin {filename:MyApplication.kt} +import android.app.Application import io.sentry.Sentry -Sentry.extendAppStart() +class MyApplication : Application() { + override fun onCreate() { + super.onCreate() + + 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() + // 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() + Sentry.finishExtendedAppStart() + } +} ``` Make sure to call `Sentry.finishExtendedAppStart()` once your launch-time work is done. By default, if the extended app start isn't finished within the 30-second [deadline timeout](/platforms/android/configuration/options/#deadlineTimeout), the SDK finishes the extended span with `DEADLINE_EXCEEDED` and suppresses the cold or warm app start measurement. The standalone `app.start` transaction and its spans are still sent. From 4754177a3fdffeb3513d65edeba475347f647ca8 Mon Sep 17 00:00:00 2001 From: Giancarlo Buenaflor Date: Mon, 13 Jul 2026 11:28:54 +0200 Subject: [PATCH 06/11] docs(android): Show asynchronous app start extension Finish extended app start tracing from an asynchronous completion callback so the examples demonstrate work that continues beyond the first frame. Co-Authored-By: Claude --- .../automatic-instrumentation.mdx | 25 +++++++++++-------- 1 file changed, 14 insertions(+), 11 deletions(-) diff --git a/docs/platforms/android/tracing/instrumentation/automatic-instrumentation.mdx b/docs/platforms/android/tracing/instrumentation/automatic-instrumentation.mdx index bcb361511988f..cc2216ddd0316 100644 --- a/docs/platforms/android/tracing/instrumentation/automatic-instrumentation.mdx +++ b/docs/platforms/android/tracing/instrumentation/automatic-instrumentation.mdx @@ -235,7 +235,7 @@ By default, the standalone app start transaction ends when the first frame is dr 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. With automatic initialization, the SDK is ready before `Application.onCreate` runs. If you initialize the SDK manually, call `SentryAndroid.init()` before `Sentry.extendAppStart()`. -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. +Retrieve the extended app start span with `Sentry.getExtendedAppStartSpan()` to add child spans that break down the extended launch period. Start your asynchronous launch work, then call `Sentry.finishExtendedAppStart()` from its completion callback when your app is fully ready. ```java {filename:MyApplication.java} import android.app.Application; @@ -255,12 +255,13 @@ public final class MyApplication extends Application { extendedSpan != null ? extendedSpan.startChild("preload", "Preload resources") : null; - // ... extra launch-time work ... - if (child != null) { - child.finish(); - } - - Sentry.finishExtendedAppStart(); + loadInitialDataAsync( + () -> { + if (child != null) { + child.finish(); + } + Sentry.finishExtendedAppStart(); + }); } } ``` @@ -277,14 +278,16 @@ class MyApplication : Application() { // 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() + loadInitialDataAsync { + child?.finish() + Sentry.finishExtendedAppStart() + } } } ``` +In these examples, `loadInitialDataAsync` represents your app's asynchronous launch work and calls its completion callback after the app is fully ready. + Make sure to call `Sentry.finishExtendedAppStart()` once your launch-time work is done. By default, if the extended app start isn't finished within the 30-second [deadline timeout](/platforms/android/configuration/options/#deadlineTimeout), the SDK finishes the extended span with `DEADLINE_EXCEEDED` and suppresses the cold or warm app start measurement. The standalone `app.start` transaction and its spans are still sent. 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. From 6352a10e3de4a8c4b41a47827176aeeaf8272a40 Mon Sep 17 00:00:00 2001 From: Giancarlo Buenaflor Date: Mon, 13 Jul 2026 11:47:54 +0200 Subject: [PATCH 07/11] docs(android): Simplify app start extension example Use a synchronous preloadResources call while retaining the optional child span. Remove the invented asynchronous helper and callback to keep the example focused on the SDK flow. Co-Authored-By: Claude --- .../automatic-instrumentation.mdx | 29 ++++++++++--------- 1 file changed, 15 insertions(+), 14 deletions(-) diff --git a/docs/platforms/android/tracing/instrumentation/automatic-instrumentation.mdx b/docs/platforms/android/tracing/instrumentation/automatic-instrumentation.mdx index cc2216ddd0316..a30114264c9ee 100644 --- a/docs/platforms/android/tracing/instrumentation/automatic-instrumentation.mdx +++ b/docs/platforms/android/tracing/instrumentation/automatic-instrumentation.mdx @@ -235,7 +235,7 @@ By default, the standalone app start transaction ends when the first frame is dr 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. With automatic initialization, the SDK is ready before `Application.onCreate` runs. If you initialize the SDK manually, call `SentryAndroid.init()` before `Sentry.extendAppStart()`. -Retrieve the extended app start span with `Sentry.getExtendedAppStartSpan()` to add child spans that break down the extended launch period. Start your asynchronous launch work, then call `Sentry.finishExtendedAppStart()` from its completion callback when your app is fully ready. +Retrieve the extended app start span with `Sentry.getExtendedAppStartSpan()` to optionally add child spans that break down the extended launch period. Perform your launch-time work, finish any child spans, and call `Sentry.finishExtendedAppStart()` when your app is fully ready. ```java {filename:MyApplication.java} import android.app.Application; @@ -255,13 +255,14 @@ public final class MyApplication extends Application { extendedSpan != null ? extendedSpan.startChild("preload", "Preload resources") : null; - loadInitialDataAsync( - () -> { - if (child != null) { - child.finish(); - } - Sentry.finishExtendedAppStart(); - }); + + preloadResources(); + + if (child != null) { + child.finish(); + } + + Sentry.finishExtendedAppStart(); } } ``` @@ -278,16 +279,16 @@ class MyApplication : Application() { // Optionally, retrieve the extended app start span to attach your own child spans val child = Sentry.getExtendedAppStartSpan()?.startChild("preload", "Preload resources") - loadInitialDataAsync { - child?.finish() - Sentry.finishExtendedAppStart() - } + + preloadResources() + + child?.finish() + + Sentry.finishExtendedAppStart() } } ``` -In these examples, `loadInitialDataAsync` represents your app's asynchronous launch work and calls its completion callback after the app is fully ready. - Make sure to call `Sentry.finishExtendedAppStart()` once your launch-time work is done. By default, if the extended app start isn't finished within the 30-second [deadline timeout](/platforms/android/configuration/options/#deadlineTimeout), the SDK finishes the extended span with `DEADLINE_EXCEEDED` and suppresses the cold or warm app start measurement. The standalone `app.start` transaction and its spans are still sent. 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. From 40b00f533aab50b672e67c1d4a2f8ea271806f57 Mon Sep 17 00:00:00 2001 From: Giancarlo Buenaflor Date: Mon, 13 Jul 2026 11:56:01 +0200 Subject: [PATCH 08/11] docs(android): Document app start finish alternatives Finish the extension span directly in the examples and document finishExtendedAppStart as the equivalent alternative. Clarify that child spans should finish before the extension. Co-Authored-By: Claude --- .../instrumentation/automatic-instrumentation.mdx | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/docs/platforms/android/tracing/instrumentation/automatic-instrumentation.mdx b/docs/platforms/android/tracing/instrumentation/automatic-instrumentation.mdx index a30114264c9ee..61b461cc95f88 100644 --- a/docs/platforms/android/tracing/instrumentation/automatic-instrumentation.mdx +++ b/docs/platforms/android/tracing/instrumentation/automatic-instrumentation.mdx @@ -262,7 +262,9 @@ public final class MyApplication extends Application { child.finish(); } - Sentry.finishExtendedAppStart(); + if (extendedSpan != null) { + extendedSpan.finish(); + } } } ``` @@ -278,18 +280,21 @@ class MyApplication : Application() { Sentry.extendAppStart() // Optionally, retrieve the extended app start span to attach your own child spans - val child = Sentry.getExtendedAppStartSpan()?.startChild("preload", "Preload resources") + val extendedSpan = Sentry.getExtendedAppStartSpan() + val child = extendedSpan?.startChild("preload", "Preload resources") preloadResources() child?.finish() - Sentry.finishExtendedAppStart() + extendedSpan?.finish() } } ``` -Make sure to call `Sentry.finishExtendedAppStart()` once your launch-time work is done. By default, if the extended app start isn't finished within the 30-second [deadline timeout](/platforms/android/configuration/options/#deadlineTimeout), the SDK finishes the extended span with `DEADLINE_EXCEEDED` and suppresses the cold or warm app start measurement. The standalone `app.start` transaction and its spans are still sent. +These examples finish the extended app start by calling `finish()` on the span returned by `Sentry.getExtendedAppStartSpan()`. Alternatively, call `Sentry.finishExtendedAppStart()` if you don't need the span reference. Both methods finish the same extension, so use only one. + +Finish any child spans first, then finish the extended app start once your launch-time work is done. By default, if the extended app start isn't finished within the 30-second [deadline timeout](/platforms/android/configuration/options/#deadlineTimeout), the SDK finishes the extended span with `DEADLINE_EXCEEDED` and suppresses the cold or warm app start measurement. The standalone `app.start` transaction and its spans are still sent. 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. From 62b2aac6a13bd8dd2ee7ed81c90aac3292272c22 Mon Sep 17 00:00:00 2001 From: Giancarlo Buenaflor Date: Mon, 13 Jul 2026 11:58:23 +0200 Subject: [PATCH 09/11] docs(android): Generalize app start finish guidance Keep the setup paragraph neutral about the completion method so it matches both the direct span finish example and the documented static API alternative. Co-Authored-By: Claude --- .../tracing/instrumentation/automatic-instrumentation.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/platforms/android/tracing/instrumentation/automatic-instrumentation.mdx b/docs/platforms/android/tracing/instrumentation/automatic-instrumentation.mdx index 61b461cc95f88..545e38176663a 100644 --- a/docs/platforms/android/tracing/instrumentation/automatic-instrumentation.mdx +++ b/docs/platforms/android/tracing/instrumentation/automatic-instrumentation.mdx @@ -235,7 +235,7 @@ By default, the standalone app start transaction ends when the first frame is dr 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. With automatic initialization, the SDK is ready before `Application.onCreate` runs. If you initialize the SDK manually, call `SentryAndroid.init()` before `Sentry.extendAppStart()`. -Retrieve the extended app start span with `Sentry.getExtendedAppStartSpan()` to optionally add child spans that break down the extended launch period. Perform your launch-time work, finish any child spans, and call `Sentry.finishExtendedAppStart()` when your app is fully ready. +Retrieve the extended app start span with `Sentry.getExtendedAppStartSpan()` to optionally add child spans that break down the extended launch period. Perform your launch-time work, finish any child spans, and finish the extended app start when your app is fully ready. ```java {filename:MyApplication.java} import android.app.Application; From d0552015ce9b9b5beef882567880a4ad288c546b Mon Sep 17 00:00:00 2001 From: Giancarlo Buenaflor Date: Mon, 13 Jul 2026 12:01:16 +0200 Subject: [PATCH 10/11] docs(android): Prefer app start finish helper Use the static finish helper as the primary completion path in the examples while documenting direct span completion as an equivalent alternative. Co-Authored-By: Claude --- .../instrumentation/automatic-instrumentation.mdx | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/docs/platforms/android/tracing/instrumentation/automatic-instrumentation.mdx b/docs/platforms/android/tracing/instrumentation/automatic-instrumentation.mdx index 545e38176663a..f4945689afbff 100644 --- a/docs/platforms/android/tracing/instrumentation/automatic-instrumentation.mdx +++ b/docs/platforms/android/tracing/instrumentation/automatic-instrumentation.mdx @@ -235,7 +235,7 @@ By default, the standalone app start transaction ends when the first frame is dr 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. With automatic initialization, the SDK is ready before `Application.onCreate` runs. If you initialize the SDK manually, call `SentryAndroid.init()` before `Sentry.extendAppStart()`. -Retrieve the extended app start span with `Sentry.getExtendedAppStartSpan()` to optionally add child spans that break down the extended launch period. Perform your launch-time work, finish any child spans, and finish the extended app start when your app is fully ready. +Optionally, retrieve the extended app start span with `Sentry.getExtendedAppStartSpan()` to add child spans that break down the extended launch period. Perform your launch-time work, finish any child spans, and call `Sentry.finishExtendedAppStart()` when your app is fully ready. ```java {filename:MyApplication.java} import android.app.Application; @@ -262,9 +262,7 @@ public final class MyApplication extends Application { child.finish(); } - if (extendedSpan != null) { - extendedSpan.finish(); - } + Sentry.finishExtendedAppStart(); } } ``` @@ -287,12 +285,12 @@ class MyApplication : Application() { child?.finish() - extendedSpan?.finish() + Sentry.finishExtendedAppStart() } } ``` -These examples finish the extended app start by calling `finish()` on the span returned by `Sentry.getExtendedAppStartSpan()`. Alternatively, call `Sentry.finishExtendedAppStart()` if you don't need the span reference. Both methods finish the same extension, so use only one. +These examples use `Sentry.finishExtendedAppStart()` to finish the extended app start. Alternatively, if you retrieved the extended span, you can call `finish()` on it directly. Both methods finish the same extension, so use only one. Finish any child spans first, then finish the extended app start once your launch-time work is done. By default, if the extended app start isn't finished within the 30-second [deadline timeout](/platforms/android/configuration/options/#deadlineTimeout), the SDK finishes the extended span with `DEADLINE_EXCEEDED` and suppresses the cold or warm app start measurement. The standalone `app.start` transaction and its spans are still sent. From 9bd9746d4176ade4e545b744fc1d2c841b256cb6 Mon Sep 17 00:00:00 2001 From: Giancarlo Buenaflor Date: Mon, 13 Jul 2026 14:58:22 +0200 Subject: [PATCH 11/11] Update docs/platforms/android/tracing/instrumentation/automatic-instrumentation.mdx Co-authored-by: Markus Hintersteiner --- .../tracing/instrumentation/automatic-instrumentation.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/platforms/android/tracing/instrumentation/automatic-instrumentation.mdx b/docs/platforms/android/tracing/instrumentation/automatic-instrumentation.mdx index f4945689afbff..11a6fa2623fd9 100644 --- a/docs/platforms/android/tracing/instrumentation/automatic-instrumentation.mdx +++ b/docs/platforms/android/tracing/instrumentation/automatic-instrumentation.mdx @@ -298,7 +298,7 @@ If you finish the extended app start before the first frame is drawn (the natura -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. +Extending the app start requires standalone app start tracing to be enabled. If `enableStandaloneAppStartTracing` is `false`, or the app start transaction was already created, `Sentry.getExtendedAppStartSpan()` returns `null` and `Sentry.finishExtendedAppStart()` is a no-op.