feat(android): [Session based Traces for Mobile 1B] Add session trace lifecycle by adinauer · Pull Request #5398 · getsentry/sentry-java

adinauer · 2026-05-11T07:38:52Z

PR Stack (Session based Traces for Mobile)

📜 Description

Adds opt-in Android session trace lifecycle support and simplifies the trace model by keeping session lifecycle behavior at the option/transaction level instead of storing lifecycle state on PropagationContext.

This PR:

adds enableSessionTraceLifecycle configuration and Android wiring
starts a new propagation context when Android starts a new session
remaps eligible root transactions onto the current session trace
preserves non-trace span/transaction context state while replacing only the trace id and clearing the parent span id
keeps continued traces with a parent span out of session trace remapping
removes the temporary propagation context lifecycle mode and forceNewTrace transaction flag

💡 Motivation and Context

Session-based traces on mobile need independently started root transactions to join the ambient app-session trace. Keeping this behavior behind an SDK option and deriving the opt-out from parentSpanId avoids per-context lifecycle state while preserving bounded/continued distributed traces.

This is the new first PR in the Session based Traces for Mobile stack: 1B.

💚 How did you test it?

./gradlew :sentry:compileJava :sentry:compileTestKotlin :sentry-opentelemetry:sentry-opentelemetry-core:compileJava
./gradlew :sentry:test --tests 'io.sentry.ScopesTest' --tests 'io.sentry.ScopeTest' --tests 'io.sentry.util.TracingUtilsTest' :sentry-opentelemetry:sentry-opentelemetry-core:test
./gradlew :sentry:test --tests 'io.sentry.ScopesTest.when session trace lifecycle is enabled, root transaction uses current propagation context' --tests 'io.sentry.ScopesTest.forceNewTrace does not override continued trace with parent span' spotlessApply apiDump
./gradlew :sentry:compileJava :sentry:compileTestKotlin
./gradlew :sentry:test --tests 'io.sentry.TransactionContextTest'
./gradlew :sentry:compileJava :sentry:compileTestKotlin :sentry:test --tests 'io.sentry.ScopesTest.continued trace with parent span is not remapped to session trace' --tests 'io.sentry.TransactionContextTest'
./gradlew spotlessApply apiDump

📝 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

Continue the Session based Traces for Mobile stack.

⚠️ Merge this PR using a merge commit (not squash). Only the collection branch is squash-merged into main.

Reuse the active session propagation context for eligible mobile root transactions while preserving explicit continuations and force-new trace escapes. Add Android integration guards, configuration, and tests for the opt-in lifecycle behavior. Co-Authored-By: Claude <noreply@anthropic.com>

Treat session trace lifecycle as an option-level behavior instead of storing lifecycle state on each propagation context. This keeps the current propagation context as the ambient trace source whenever session trace lifecycle is enabled. Co-Authored-By: Claude <noreply@anthropic.com>

Reuse SpanContext copy logic when remapping root transactions onto the session propagation context. Preserve transaction identity while replacing the trace id and clearing the parent span id. Co-Authored-By: Claude <noreply@anthropic.com>

Use parent span presence as the session trace lifecycle opt-out instead of a separate TransactionContext flag. Co-Authored-By: Claude <noreply@anthropic.com>

github-actions · 2026-05-11T07:39:23Z

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

Generated by 🚫 dangerJS against 341ba6b

sentry · 2026-05-11T07:41:36Z

📲 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-05-11T07:47:40Z

Performance metrics 🚀

	Plain	With Sentry	Diff
Startup time	316.96 ms	354.37 ms	37.41 ms
Size	0 B	0 B	0 B

Previous results on branch: ref/remove-propagation-context-mode

Startup times

Revision	Plain	With Sentry	Diff
`f15a0c5`	321.71 ms	365.46 ms	43.75 ms
`c183fb7`	368.02 ms	436.96 ms	68.94 ms

App size

Revision	Plain	With Sentry	Diff
`f15a0c5`	0 B	0 B	0 B
`c183fb7`	0 B	0 B	0 B

Co-Authored-By: Claude <noreply@anthropic.com>

buenaflor · 2026-05-13T08:28:52Z

  /** Whether to enable or disable automatic session tracking. */
  private boolean enableAutoSessionTracking = true;

+  /** Whether root transactions should reuse the current session trace lifecycle. */


imo this should be more generic since trace re-use is not only specific to spans/transactions, wdyt?

Suggested change

/** Whether root transactions should reuse the current session trace lifecycle. */

/** Whether telemetry should reuse the current session trace lifecycle. */

It does only affect head of trace transactions (no parentSpanID) so the current version sounds more correct to me.

which traceId do errors, metrics, logs inherit then?

Those should take traceId from the active transaction if there is any on scope. But since that should be identical to the scopes traceId the distinction would only matter for non head of trace transactions where the new behaviour doesn't kick in.

Probably simplest to change the wording to what you suggested rather than explain SDK internals here.

ah okay, btw should we scope this option to the android sdk? (not sure about the protocol here when we add new options)

Since this is used in core SDK, we can't move it to AndroidOptions. We can add a comment to the JavaDoc to explain this is only intended for Android. In docs we can simply not mention it for JVM.

In the future (new major) we'll likely make this default enabled in AndroidOptionsInitializer.

makes sense 👍

adinauer and others added 4 commits May 11, 2026 07:01

ref(core): Remove force new trace transaction flag

004741c

Use parent span presence as the session trace lifecycle opt-out instead of a separate TransactionContext flag. Co-Authored-By: Claude <noreply@anthropic.com>

adinauer mentioned this pull request May 11, 2026

feat(core): Session based Traces for Mobile #5383

Draft

adinauer and others added 2 commits May 11, 2026 10:54

changelog

f68c874

Co-Authored-By: Claude <noreply@anthropic.com>

docs(core): Update session trace lifecycle javadocs

341ba6b

Co-Authored-By: Claude <noreply@anthropic.com>

This was referenced May 11, 2026

fix(core): [Session based Traces for Mobile 2] Keep transaction baggage mutable #5402

Draft

fix(core): [Session based Traces for Mobile 3] Require active session for lifecycle #5417

Draft

buenaflor reviewed May 13, 2026

View reviewed changes

Comment thread sentry-android-core/src/test/java/io/sentry/android/core/ActivityLifecycleIntegrationTest.kt

This was referenced May 13, 2026

fix(core): [Session based Traces for Mobile 4] No longer unfreeze Baggage #5429

Draft

ref(core): [Session based Traces for Mobile 5] Rename option to enableSessionTraces #5430

Draft

	/** Whether root transactions should reuse the current session trace lifecycle. */
	/** Whether telemetry should reuse the current session trace lifecycle. */

Uh oh!

Conversation

adinauer commented May 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Stack (Session based Traces for Mobile)

📜 Description

💡 Motivation and Context

💚 How did you test it?

📝 Checklist

🔮 Next steps

Uh oh!

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

Uh oh!

Uh oh!

sentry Bot commented May 11, 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 May 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Performance metrics 🚀

Previous results on branch: ref/remove-propagation-context-mode

Startup times

App size

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

adinauer commented May 11, 2026 •

edited

Loading

github-actions Bot commented May 11, 2026 •

edited

Loading

sentry Bot commented May 11, 2026 •

edited

Loading

github-actions Bot commented May 11, 2026 •

edited

Loading