Skip to content

fix(flutter): Parent HTTP spans to the new route - #4155

Merged
buenaflor merged 14 commits into
mainfrom
fix/navigation-http-span-parenting
Nov 17, 2026
Merged

buenaflor merged 14 commits into
mainfrom
fix/navigation-http-span-parenting

Conversation

@buenaflor

@buenaflor buenaflor commented Nov 11, 2026 •

Copy link
Copy Markdown
Contributor

πŸ“œ Description

Hand the scope over from the app-start root / transaction when the next route display starts, so HTTP spans from later screens parent to the new route instead of the app start.

  • Starting a route display (a push or current-route replacement of a named, non-root route) unbinds the app-start root from the scope and ends its pending TTID/TTFD spans as deadline_exceeded, instead of leaving them to the 30s TTFD timeout. Streaming already follows this rule through trackRoute, and it is how sentry-java and sentry-cocoa end the previous screen's display.
  • This also applies with enableAutoTransactions disabled: navigating to a named, non-root route ends the previous display (the app start included) in both lifecycles, and the flag only decides whether a new route transaction or span starts. Before, the app start stayed bound to the scope (static) or active (streaming), so spans from later screens, including manual Sentry.getSpan()?.startChild(...) children, attached to it until its TTFD timed out. A reportFullyDisplayed() for the initial screen after leaving it is no longer recorded, the same as with auto transactions enabled.
  • Routes that start no display of their own (unnamed routes, dialogs, bottom sheets) leave the app start running, as they do for any other route transaction. TTFD on the initial screen stays reportable while a dialog is open.
  • pushReplacement/replace of the current route now starts a ui.load transaction (static) or route span (streaming), like push. Replacing with / starts none, matching push.
  • Replacing the route that named the app start before first-frame timing (e.g. a splash screen) renames the reserved app-start display instead of starting a second transaction. Replacements in other navigators are ordinary navigation.
  • Replacement transactions record route arguments as route_settings_arguments, like didPush.
  • A route transaction that finishes after the next one has started no longer clears the observer's reference to the newer one. Without this, HTTP spans stopped following the current route after consecutive pushes.

πŸ’‘ Motivation and Context

The app-start transaction held the scope until its TTFD span timed out, so HTTP spans from later screens attached to root /, which could last close to 30s.

Fixes #4154

Known limitation (pre-existing, unchanged here): an unnamed route, such as a MaterialPageRoute without settings, doesn't end the previous display in either lifecycle, whether that is the app start or another route. Its spans keep parenting to the previous screen while that transaction or span is still open. The same goes for a later navigation to / (e.g. a splash screen replaced by home after the first frame): no new display starts, so its spans stay on the app start.

πŸ’š How did you test it?

Widget tests cover static and streaming HTTP parenting on push and replacement (including past the TTFD deadline and across consecutive pushes), ending the app-start TTFD span on navigation, a dialog over the initial screen (TTFD stays reportable and HTTP spans stay on the app start), early replacement with delayed first-frame timing, nested-navigator replacements, replacing with /, replacement arguments being recorded, and ending the app start on push with enableAutoTransactions disabled (static scope released and TTFD deadline_exceeded; streaming app-start span ended and no longer active). Unit tests cover TimeToDisplayTracker.releaseInitialDisplay.

Also run manually on an iOS simulator with native app start, static lifecycle and TTFD enabled, following the issue's steps (never report fully displayed on the initial screen, push /next, make two HTTP requests). Before this change root / kept the scope, received both HTTP spans and was only sent after its TTFD timeout, while /next had none. With it, root / is sent on navigation without HTTP spans and /next carries both.

πŸ“ Checklist

  • I added tests to verify changes
  • No breaking changes

Changelog Entry

  • Parent HTTP spans to the new route after navigating away from the initial route, instead of to the app-start root / transaction until its TTFD timeout (Initial root / transaction keeps scope after navigationΒ #4154)
  • pushReplacement/replace of the current route now starts a ui.load transaction (static) or route span (streaming), like push
  • With enableAutoTransactions disabled, navigating to a named route now ends the app-start display (TTID/TTFD end as deadline_exceeded in static mode), so spans from later screens no longer attach to the app start

Hand off app-start scope on navigation while TTFD is pending and
track current route replacements in both tracing modes.

Fixes #4154

Co-Authored-By: OpenAI Codex <noreply@openai.com>
@github-actions

github-actions Bot commented Nov 11, 2026 •

Copy link
Copy Markdown
Contributor

Semver Impact of This PR

🟒 Patch (bug fixes)

πŸ“‹ Changelog Preview

This is how your changes will appear in the changelog.
Entries from this PR are highlighted with a left border (blockquote style).


Fixes

Flutter

  • Parent HTTP spans to the new route after navigating away from the initial route, instead of to the app-start root / transaction until its TTFD timeout (Initial root / transaction keeps scope after navigationΒ #4154) by buenaflor, codex and 2 others in #4155
  • pushReplacement/replace of the current route now starts a ui.load transaction (static) or route span (streaming), like push by buenaflor, codex and 2 others in #4155
  • With enableAutoTransactions disabled, navigating to a named route now ends the app-start display (TTID/TTFD end as deadline_exceeded in static mode), so spans from later screens no longer attach to the app start by buenaflor, codex and 2 others in #4155
  • Use a writable native database directory on Windows when nativeDatabasePath isn't set, so native crashes from packaged (MSIX/Microsoft Store) apps are captured. by lucas-zimerman and claude in #4156

Other

  • (dart) Avoid mutating flags of captured events by buenaflor and claude in #4169

Dependencies

Deps

  • chore(deps): update JavaScript SDK to v11.13.0 by buenaflor with github-actions in #4177
  • chore(deps): update Cocoa SDK to v9.35.0 by github-actions in #4176

Internal Changes

  • (agents) Disable AI attribution in commits by buenaflor with sentry-junior in #4170
  • (android) Upgrade Flutter example toolchain by buenaflor in #4171

πŸ€– This preview updates automatically when you update the PR.

@codecov

codecov Bot commented Nov 11, 2026 •

Copy link
Copy Markdown

Codecov Report

βœ… All modified and coverable lines are covered by tests.
βœ… Project coverage is 93.15%. Comparing base (312756c) to head (21921f9).
βœ… All tests successful. No failed tests found.

Additional details and impacted files
@@            Coverage Diff             @@
##             main    #4155      +/-   ##
==========================================
+ Coverage   89.11%   93.15%   +4.03%     
==========================================
  Files         354      119     -235     
  Lines       12795     4833    -7962     
==========================================
- Hits        11402     4502    -6900     
+ Misses       1393      331    -1062     
Flag Coverage Ξ”
sentry ?
sentry_dio ?
sentry_drift ?
sentry_file ?
sentry_firebase_remote_config 100.00% <ΓΈ> (ΓΈ)
sentry_flutter 92.89% <100.00%> (+0.01%) ⬆️
sentry_grpc ?
sentry_hive ?
sentry_isar ?
sentry_link ?
sentry_logging ?
sentry_sqflite ?
sentry_supabase 97.46% <ΓΈ> (ΓΈ)

Flags with carried forward coverage won't be shown. Click here to find out more.

β˜” View full report in Codecov by Harness.
πŸ“’ Have feedback on the report? Share it here.

buenaflor and others added 2 commits November 11, 2026 13:28
Keep the prepared app-start display through early route replacements.
Omit raw replacement arguments from static transaction data.

Refs #4154

Co-Authored-By: OpenAI Codex <noreply@openai.com>
@buenaflor
buenaflor marked this pull request as ready for review November 11, 2026 13:10
@buenaflor
buenaflor requested a review from denrase as a code owner November 11, 2026 13:10
Copilot AI balanced review requested due to automatic review settings November 11, 2026 13:10

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

🟒 Approval recommended

No active review issues block the route-tracking and HTTP-span parenting changes.

No open issues πŸŽ‰

What changed in this PR

Fixes #4154 by keeping HTTP spans attached to the incoming Flutter route instead of the initial app-start transaction while full-display timing remains pending.

Changes:

  • Updates route tracking for pushes and named current-route replacements while preserving unrelated scope bindings.
  • Reuses reserved app-start display tracking for early replacements and avoids copying raw replacement arguments into static transactions.
  • Adds widget tests for static and streaming HTTP parenting, delayed timing, consecutive navigation, and background replacements.
File Description
packages/​flutter/​test/​navigation/​sentry_navigator_observer_test.dart Adds HTTP-parenting, replacement, timing, and privacy regression tests.
packages/​flutter/​test/​mocks.mocks.dart Updates the mock for prepared app-start route renaming.
packages/​flutter/​lib/​src/​navigation/​time_to_display_tracker.dart Releases the initial display’s scope binding and supports renaming reserved transactions.
packages/​flutter/​lib/​src/​navigation/​time_to_display_tracker_v2.dart Supports renaming prepared streaming app-start display spans.
packages/​flutter/​lib/​src/​navigation/​sentry_navigator_observer.dart Tracks current replacements and prevents older transaction callbacks from clearing newer state.

Review effort: Balanced

buenaflor and others added 3 commits November 16, 2026 09:51
Unbind the app-start root and end its pending display spans on every
push or current replacement, including unnamed routes, instead of
leaving its TTFD span to the 30s timeout. clear() no longer touches
the scope.

Only a replacement of the route that named the app start takes over
its reservation, so nested navigators can't rename it. Replacing with
/ starts no transaction, matching didPush. Merge the duplicate
app-start rename methods and restructure the tests.

Refs #4154

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Record route_settings_arguments on replacement transactions like
didPush does. The didReplace breadcrumb already carries them, so
omitting them only made push and replace inconsistent.

Refs #4154

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Release the app-start root only when a route display starts, instead
of on every push or replacement. Releasing on unnamed routes ended
the app-start TTFD as deadline_exceeded when a dialog opened over the
initial screen, and dropped that screen's HTTP spans because nothing
was left bound to the scope.

This matches streaming, where trackRoute ends the previous display,
and ordinary route transactions, which unnamed routes leave running.

Refs #4154

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Co-authored-by: Cursor <cursoragent@cursor.com>

@cursor cursor Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Stale Bugbot comment from a previous run.

Splitting the V2 tracker test dropped the check that prepareAppStart
marks the route name as pending. Only one observer widget test still
caught a regression there, and not by name.

Refs #4154
@lucas-zimerman

Copy link
Copy Markdown
Collaborator

After reviewing it, I found some behaviour differences compared to Sentry React Native that may result in anomalies.
TTFD shouldn't be tied to the root Scope, this has the potential to link other automatic transactions to it as a child span.
We could use Hub.startTransaction and startTransactionWithContext with bindToScope: false as a replacement startInactiveSpan from Sentry JavaScript

@lucas-zimerman

Copy link
Copy Markdown
Collaborator

I spotted an edge case here when _enableAutoTransactions is disabled. With the flag off, the app-start root keeps Scope.span after the user navigates, until it finishes on it timeout. It's the same for routes where _trackRouteDisplay is never called (null or / names).

What's affected:

  • Spans created from the active span. Sentry.getSpan()?.startChild(...) attaches to the app-start transaction, and so do automatic child spans (e.g. HTTP).
  • Not affected: manual transactions started with bindToScope: true.

With the flag off these spans previously had no parent and were dropped, so the result is misattributed spans, not lost data. I'd call it low to medium severity.

I reproduced it with a real Navigator:

  • enableAutoTransactions: false, launch, push /next. hub.getSpan() is still the app-start SentryTracer.
  • getSpan()?.startChild('custom.op') gets the app-start root's span ID as its parentSpanId.

@lucas-zimerman lucas-zimerman left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

The two comments that I wrote applies here, but they also happen on main so they are somewhat unrelated, feel free to do a follow-up PR or just open an issue to track them.

With enableAutoTransactions disabled, navigating to a named route
skipped all display handling, so the app start stayed bound to the
scope (static) or active (streaming) and spans from later screens
parented to it until its TTFD timed out.

End the previous display before checking the flag, in both trace
lifecycles. The flag now only controls whether a new route transaction
or span starts.

@cursor cursor Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Stale Bugbot comment from a previous run.

Navigating to a named route before first-frame timing arrives ends the
prepared streaming app-start span. When the timing arrived afterwards,
trackAppStart found nothing prepared, started a fresh idle span, and
spans from the current screen parented to it.

Skip recording when nothing is prepared anymore, as static already
does.
Every push or replacement cleared the app-start route, including ones
that start no display, such as dialogs. Replacing the initial route
after a dialog opened and closed before first-frame timing then dropped
the app-start reservation and started a separate route transaction.

Clear the handoff only when a new route display takes over.
@github-actions

Copy link
Copy Markdown
Contributor

🚨 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:

  • packages/flutter/lib/src/app_start/standalone/app_start_display_tracking.dart

buenaflor and others added 2 commits November 17, 2026 13:59
With auto transactions disabled in streaming mode, navigating to a named
route called cancelCurrentRoute, which ends whatever idle span the hub
holds. That cut short user-interaction spans, such as the tap that
pushed the route.

Track the app-start span and end only that one. With auto transactions
enabled, trackRoute still ends the current route span as before.

@cursor cursor Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Cursor Bugbot has reviewed your changes and found 1 potential issue.

Fix All in Cursor

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

Reviewed by Cursor Bugbot for commit fe57c4e. Configure here.

@buenaflor
buenaflor merged commit 31d8892 into main Nov 17, 2026
74 checks passed
@buenaflor
buenaflor deleted the fix/navigation-http-span-parenting branch November 17, 2026 13:37
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Initial root / transaction keeps scope after navigation

3 participants