feat(android): Add standalone app start tracing by buenaflor · Pull Request #5342 · getsentry/sentry-java

buenaflor · 2026-04-28T14:51:10Z

📜 Description

Adds standalone Android app-start transaction support behind the opt-in enableStandaloneAppStartTracing option and the io.sentry.standalone-app-start-tracing.enable manifest key.

This PR also covers the non-activity startup path so cold starts triggered by broadcasts or foreground services can emit an App Start Cold/Warm transaction without waiting for an activity. The legacy flag-off behavior is preserved: activity app-start data remains nested under the ui.load transaction.

Additionally this PR adds two new attributes:

app.vitals.start.reason
app.vitals.start.screen

💡 Motivation and Context

Resolves: #5046

Standalone app-start traces make app-start performance visible independently from activity load transactions, and they let Android report app starts where no activity is launched. The implementation keeps the default behavior unchanged and adds tests for the new option, manifest metadata, transaction context trace reuse, app-start metrics, event processing, and activity lifecycle behavior.

App-start creation paths

This PR preserves the existing flag-off behavior and adds a separate standalone app-start branch when enableStandaloneAppStartTracing is enabled.

Scenario	How app start is created	Resulting trace shape
Activity launch, flag ON	`ActivityLifecycleIntegration` starts a standalone `App Start` transaction and the normal activity `ui.load` transaction on the same trace.	Two sibling transactions: `app.start` for app-start phases, and `ui.load` for TTID/TTFD. The `ui.load` transaction does not contain an `app.start.cold/warm` child.
Activity launch, flag OFF	Legacy activity lifecycle tracing creates app start as a child span of the activity transaction.	One `ui.load` transaction with nested `app.start.cold/warm`, plus app-start phase spans under that child.
Non-activity process start, flag ON, Gradle plugin instrumentation present	The Gradle plugin records `Application.onCreate` start/end through `AppStartMetrics.onApplicationCreate/PostCreate`. When no activity starts, `ActivityLifecycleIntegration` emits from that completed app-start span.	One standalone `App Start` transaction and no `ui.load`; includes `process.load` and `application.load` phase spans.
Non-activity process start, flag ON, no Gradle plugin on API 35+	`AppStartMetrics` reads `ApplicationStartInfo` from `ActivityManager` to determine start type and use the platform `APPLICATION_ONCREATE` timestamp as the app-start end time.	One standalone `App Start` transaction and no `ui.load`; includes `process.load`, but not `application.load` because the SDK does not have plugin instrumentation for that phase.
Non-activity process start, flag ON, no Gradle plugin on API <35	`ApplicationStartInfo` is unavailable, so `AppStartMetrics` defaults the no-activity process start to cold and uses the class-loaded timestamp fallback for the app-start end time.	One standalone `App Start` transaction and no `ui.load`; includes `process.load` only and remains classified as cold.
Non-activity process start followed by activity	The non-activity `App Start` transaction stores its trace ID for a later activity.	The later activity `ui.load` reuses the stored trace ID and does not create a second standalone app-start transaction.
Non-activity process start, flag OFF	The non-activity listener is not installed.	Broadcasts/services emit no app-start transaction.

💚 How did you test it?

./gradlew spotlessApply apiDump
Targeted unit coverage for the option, manifest metadata, app-start metric resolution, event processing, lifecycle integration, and transaction context trace reuse.
Manual end-to-end harness runs from scripts/test-standalone-app-start.sh, summarized below.

End-to-end Sentry verification

#	What it tests	Locally emitted shape	Trace ID link
1a	Launcher activity cold start, standalone flag ON. Standalone `App Start` emits alongside sibling `MainActivity ui.load`; shared trace ID; `ui.load` has no `app.start.*` child.	`app.start` (`app_start_cold=1156ms`) + `activity.load` x2 + `process.load` + `application.load`; sibling `ui.load` (`time_to_initial_display=1156ms`)	`52154e91...`
1c	Launcher activity cold start, standalone flag OFF. Legacy shape preserved: single `ui.load` with `app.start.cold` nested inside.	`ui.load` (`time_to_initial_display=1536ms`) -> nested `app.start.cold` (`app_start_cold=1537ms`) -> `process.load` + `activity.load` x2	`d3f0e049...`
2a	Broadcast cold, tier-1 end-time resolution with Gradle-plugin timing simulation.	`app.start` (`app_start_cold=1408ms`) + `process.load` + `application.load`; no `ui.load`	`81ae80f6...`
2b	Broadcast cold, tier-2 end-time resolution via Android 15 `ApplicationStartInfo`.	`app.start` (`app_start_cold=525ms`) + `process.load` only; no `ui.load`	`0dcd120e...`
2c	Broadcast cold, tier-3 fallback on API 33 using `CLASS_LOADED_UPTIME_MS`.	`app.start` (`app_start_cold=614ms`) + `process.load` only; correctly classified Cold	`ac8a9189...`
2d	Foreground service cold start through the non-activity path.	`app.start` (`app_start_cold=4605ms`) + `process.load` + `application.load`; no `ui.load`	`905262ce...`
2e	Broadcast then launcher: trace reuse without duplicate standalone transaction.	Same trace: broadcast `app.start` (`app_start_cold=1751ms`) + later sibling `ui.load` (`time_to_initial_display=4563ms`); no duplicate standalone	`5da4a88f...`
2f	Broadcast + standalone flag OFF.	No transaction emitted	--

📝 Checklist

I added GH Issue ID & Linear ID
I added tests to verify the changes.
No new PII added or SDK only sends newly added PII if sendDefaultPII is enabled.
I updated the docs if needed.
I updated the wizard if needed.
Review from the native team if needed.
No breaking change or entry added to the changelog.
No breaking change for hybrid SDKs or communicated to hybrid SDKs.

🔮 Next steps

Introduce experimental `enableStandaloneAppStartTracing` option that creates a separate app start transaction instead of attaching app start as a child span of the first activity transaction. This is the happy path only (foreground importance, activity launch, first frame drawn as end time). The standalone transaction shares the same trace ID as the activity transaction but is not bound to the scope. App start measurements and child spans (process init, content providers, application.onCreate) are attached to the standalone transaction instead of the activity transaction. Includes foreground importance check branching to prepare for the non-activity launch path (next PR). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

When the app starts without launching an activity (service, broadcast receiver, content provider), create a standalone app start transaction with the end time determined by priority: 1. onApplicationPostCreate (Gradle plugin bytecode instrumentation) 2. ApplicationStartInfo timestamps (API 35+) 3. firstIdle - main thread idle handler (pre-API 35 fallback) The non-activity app start transaction stores its trace ID so that if an activity is later launched, the activity transaction reuses the same trace ID to keep both in the same trace. Adds OnNoActivityStartedListener callback from AppStartMetrics to ActivityLifecycleIntegration, triggered by checkCreateTimeOnMain() when no activity was created after Application.onCreate(). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

…entation When an app is launched via broadcast receiver, service, or content provider (no activity), detect this via Handler.post() and create a standalone app start transaction. Resolves app start end time with priority: Gradle plugin > ApplicationStartInfo (API 35+) > process init time. Also attaches child spans (process init, content providers, Application.onCreate) to standalone transactions. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Extract the "try appStartSpan, fall back to sdkInitTimeSpan" logic used for standalone (non-activity) app start transactions into a new AppStartMetrics.getAppStartTimeSpanDirect() helper, removing the duplicated inline fallback in ActivityLifecycleIntegration and the private helper in PerformanceAndroidEventProcessor. Also cache the API 35+ ApplicationStartInfo on registerLifecycleCallbacks so onAppStartSpansSent no longer re-queries ActivityManager, and simplify the non-activity detection path to always use the main-thread IdleHandler. Regenerates the sentry-android-core API to include method additions missed in prior commits on this branch (standalone-app-start options, trace id accessors, OnNoActivityStartedListener). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Wires up the TestBroadcastReceiver added earlier so the sample app can trigger a non-activity cold start via `adb shell am broadcast`. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

…tart-tracing # Conflicts: # sentry-android-core/src/main/java/io/sentry/android/core/performance/AppStartMetrics.java

…icate emission Two pre-merge fixes for the standalone app-start tracing path introduced on this branch (issue #5046): - AppStartMetrics.checkCreateTimeOnMain() now defaults appStartType to COLD when UNKNOWN with no active activities. On API < 35 (where ApplicationStartInfo is unavailable) non-activity cold starts were stuck at UNKNOWN, which both misclassified the standalone transaction as App Start Warm and caused PerformanceAndroidEventProcessor.attachAppStartSpans to early-return (dropping process.load / application.load / contentprovider.load phase spans). - ActivityLifecycleIntegration.onActivityPreCreated() now skips emitting a second standalone App Start transaction when the non-activity path has already reported the process's app start (detected via the stashed appStartTraceId). Previously a broadcast followed by an activity launch produced two standalone transactions (a spurious App Start Warm in addition to the broadcast's App Start Cold), violating one-per-process semantics. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

github-actions · 2026-04-28T15:05:04Z

	Messages
📖	Do not forget to update Sentry-docs with your feature once the pull request gets approved.

Generated by 🚫 dangerJS against 87ff0d6

sentry · 2026-04-28T15:07:46Z

📲 Install Builds

Android

🔗 App Name	App ID	Version	Configuration
SDK Size	io.sentry.tests.size	8.41.0 (1)	release

⚙️ sentry-android Build Distribution Settings

github-actions · 2026-04-28T15:11:35Z

Performance metrics 🚀

	Plain	With Sentry	Diff
Startup time	285.07 ms	363.18 ms	78.11 ms
Size	0 B	0 B	0 B

Baseline results on branch: main

Startup times

Revision	Plain	With Sentry	Diff
`0220a5c`	332.62 ms	390.85 ms	58.24 ms
`2195398`	344.65 ms	403.96 ms	59.30 ms
`ab8a72d`	316.24 ms	356.38 ms	40.14 ms
`d364ace`	384.53 ms	453.51 ms	68.98 ms
`85d7417`	347.21 ms	394.35 ms	47.15 ms
`6727e14`	337.22 ms	373.94 ms	36.71 ms
`d15471f`	310.66 ms	368.19 ms	57.53 ms
`fc5ccaf`	276.52 ms	370.46 ms	93.93 ms
`b8bd880`	314.56 ms	336.50 ms	21.94 ms
`ce0a49e`	532.00 ms	609.96 ms	77.96 ms

App size

Revision	Plain	With Sentry	Diff
`0220a5c`	0 B	0 B	0 B
`2195398`	0 B	0 B	0 B
`ab8a72d`	1.58 MiB	2.12 MiB	551.55 KiB
`d364ace`	1.58 MiB	2.11 MiB	539.75 KiB
`85d7417`	1.58 MiB	2.10 MiB	533.44 KiB
`6727e14`	1.58 MiB	2.28 MiB	718.64 KiB
`d15471f`	1.58 MiB	2.13 MiB	559.54 KiB
`fc5ccaf`	1.58 MiB	2.13 MiB	557.54 KiB
`b8bd880`	1.58 MiB	2.29 MiB	722.92 KiB
`ce0a49e`	1.58 MiB	2.10 MiB	532.94 KiB

Previous results on branch: feat/standalone-app-start-tracing

Startup times

Revision	Plain	With Sentry	Diff
`5f2075f`	329.13 ms	392.38 ms	63.25 ms
`8147749`	302.52 ms	352.71 ms	50.19 ms

App size

Revision	Plain	With Sentry	Diff
`5f2075f`	0 B	0 B	0 B
`8147749`	0 B	0 B	0 B

Rename the standalone app-start transaction to a single App Start name so cold and warm starts group consistently while preserving the app.start op. Co-authored-by: Cursor <cursoragent@cursor.com>

Co-authored-by: Cursor <cursoragent@cursor.com>

github-actions · 2026-05-07T13:40:46Z

🚨 Detected changes in high risk code 🚨

High-risk code has higher potential to break the SDK and may be hard to test. To prevent severe bugs, apply the rollout process for releasing such changes and be extra careful when changing and reviewing these files:

sentry-android-core/src/main/java/io/sentry/android/core/InternalSentrySdk.java

buenaflor · 2026-05-07T13:44:42Z

@cursor review
@sentry review

Co-authored-by: Cursor <cursoragent@cursor.com>

buenaflor · 2026-05-07T14:55:14Z

@cursor review
@sentry review

github-actions · 2026-05-07T14:55:43Z

🚨 Detected changes in high risk code 🚨

High-risk code has higher potential to break the SDK and may be hard to test. To prevent severe bugs, apply the rollout process for releasing such changes and be extra careful when changing and reviewing these files:

sentry-android-core/src/main/java/io/sentry/android/core/InternalSentrySdk.java

cursor

Cursor Bugbot has reviewed your changes and found 2 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 87ff0d6. Configure here.}

cursor · 2026-05-07T15:05:40Z

+            timestamps.get(ApplicationStartInfo.START_TIMESTAMP_APPLICATION_ONCREATE);
+        if (onCreateNanos != null && onCreateNanos > 0) {
+          final long onCreateUptimeMs = TimeUnit.NANOSECONDS.toMillis(onCreateNanos);
+          stopNonActivityAppStartAt(onCreateUptimeMs);


ApplicationStartInfo timestamps may use wrong clock base

Medium Severity

ApplicationStartInfo.getStartupTimestamps() returns nanoseconds based on SystemClock.elapsedRealtimeNanos(), but the converted value is passed to setStoppedAt() which expects SystemClock.uptimeMillis(). These two clocks diverge by the total accumulated deep sleep time since boot. On a device awake for hours with prior deep sleep, the mismatch can produce wildly inflated app start durations (off by hours). The variable name onCreateUptimeMs masks this, and the test uses mock values so it cannot catch the discrepancy.

Additional Locations (1)

sentry-android-core/src/main/java/io/sentry/android/core/performance/AppStartMetrics.java#L541-L547

^{Reviewed by Cursor Bugbot for commit 87ff0d6. Configure here.}

buenaflor and others added 10 commits April 2, 2026 14:43

chore(samples): Register TestBroadcastReceiver in manifest

5efab1d

Wires up the TestBroadcastReceiver added earlier so the sample app can trigger a non-activity cold start via `adb shell am broadcast`. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Merge remote-tracking branch 'origin/main' into feat/standalone-app-s…

f6c070d

…tart-tracing # Conflicts: # sentry-android-core/src/main/java/io/sentry/android/core/performance/AppStartMetrics.java

fix(android): refine standalone app start tracing

50a2f41

chore: Update generated files

26a83cc

style(core): Apply spotless formatting

a60d966

buenaflor mentioned this pull request Apr 28, 2026

feat: Send standalone app start transactions #5046

Open

changelog

09bac52

buenaflor commented Apr 28, 2026

View reviewed changes

Comment thread sentry-android-core/src/main/java/io/sentry/android/core/performance/AppStartMetrics.java

Merge branch 'main' into feat/standalone-app-start-tracing

5387e76

buenaflor and others added 2 commits May 4, 2026 10:15

fix(android): Use stable app start transaction name

f7c9c62

Rename the standalone app-start transaction to a single App Start name so cold and warm starts group consistently while preserving the app.start op. Co-authored-by: Cursor <cursoragent@cursor.com>

feat(android): Add standalone app start tracing

9adfa01

Co-authored-by: Cursor <cursoragent@cursor.com>

sentry Bot reviewed May 7, 2026

View reviewed changes

Comment thread sentry-android-core/src/main/java/io/sentry/android/core/ActivityLifecycleIntegration.java

Comment thread sentry-android-core/src/main/java/io/sentry/android/core/performance/AppStartMetrics.java

cursor Bot reviewed May 7, 2026

View reviewed changes

Comment thread sentry-android-core/src/main/java/io/sentry/android/core/ActivityLifecycleIntegration.java Outdated

fix(android): Handle non-activity app starts below API 24

87ff0d6

Co-authored-by: Cursor <cursoragent@cursor.com>

cursor Bot reviewed May 7, 2026

View reviewed changes

Uh oh!

Conversation

buenaflor commented Apr 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📜 Description

💡 Motivation and Context

App-start creation paths

💚 How did you test it?

End-to-end Sentry verification

📝 Checklist

🔮 Next steps

Uh oh!

Uh oh!

github-actions Bot commented Apr 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

sentry Bot commented Apr 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📲 Install Builds

Android

Uh oh!

github-actions Bot commented Apr 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Performance metrics 🚀

Baseline results on branch: main

Startup times

App size

Previous results on branch: feat/standalone-app-start-tracing

Startup times

App size

Uh oh!

github-actions Bot commented May 7, 2026

🚨 Detected changes in high risk code 🚨

Uh oh!

buenaflor commented May 7, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

buenaflor commented May 7, 2026

Uh oh!

github-actions Bot commented May 7, 2026

🚨 Detected changes in high risk code 🚨

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

cursor Bot May 7, 2026

Choose a reason for hiding this comment

ApplicationStartInfo timestamps may use wrong clock base

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

buenaflor commented Apr 28, 2026 •

edited

Loading

github-actions Bot commented Apr 28, 2026 •

edited

Loading

sentry Bot commented Apr 28, 2026 •

edited

Loading

github-actions Bot commented Apr 28, 2026 •

edited

Loading