docs(flutter): Add standalone app start tracing docs - #18903
Merged
Conversation
App start data is attached to the first ui.load transaction by default, which mixes startup timing with screen-display timing. Document the experimental enableStandaloneAppStartTracing option that reports the app start as its own app.start transaction, along with extendAppStart and finishExtendedAppStart for covering startup work that runs past the first frame. Shipped in sentry-dart 9.26.0. Refs getsentry/sentry-dart#3896 Refs getsentry/sentry-dart#3918 Co-authored-by: Cursor <cursoragent@cursor.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
The only requirement for extendAppStart is that it runs before the first frame renders, so the root widget's initState works as well as appRunner. Show both as tabs and note that the call has to come before the first await, since awaiting first lets the frame render and the extension is refused. Co-authored-by: Cursor <cursoragent@cursor.com>
![sentry[bot]](https://avatars.githubusercontent.com/in/12637?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Pull request overview
Documents the Flutter SDK’s experimental standalone app start tracing (enableStandaloneAppStartTracing) and the related “extend app start” APIs, aligning Flutter’s docs with existing Android/Apple coverage while keeping the detailed explanation on the integration page.
Changes:
- Added a new “Standalone App Start Tracing” section (plus “Extending the App Start”) to the Flutter app start instrumentation integration docs.
- Added a short experimental standalone app start tracing section to the Flutter tracing landing page, linking to the integration docs for details.
- Added
enableStandaloneAppStartTracingto the Flutter configuration options reference under Tracing Options.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.
| File | Description |
|---|---|
| includes/dart-integrations/app-start-instrumentation.mdx | Adds standalone app start tracing docs, sampling guidance, and extended app start API usage. |
| docs/platforms/dart/guides/flutter/tracing/index.mdx | Adds a brief experimental standalone app start tracing section and links to the detailed integration page. |
| docs/platforms/dart/guides/flutter/configuration/options.mdx | Documents the new enableStandaloneAppStartTracing tracing option. |
The sampler reads the operation differently per trace lifecycle: transaction mode exposes it on the transaction context, while stream mode carries it as the span's sentry.op attribute. Accessing transactionContext in stream mode logs an error, so show both variants as tabs. Co-authored-by: Cursor <cursoragent@cursor.com>
Show how to break the extension down with getExtendedAppStartSpan and getExtendedAppStartSpanV2, one tab per trace lifecycle. Note that the extension span is not the active span, so children need an explicit parentSpan, and that passing a null parentSpan in stream mode starts a root span rather than a child. Co-authored-by: Cursor <cursoragent@cursor.com>
denrase
approved these changes
Aug 3, 2026
denrase
left a comment
denrase
left a comment
Collaborator
There was a problem hiding this comment.
Not sure where the line is drawn between documenting or not documenting stream mode, please re-check if we want to include it. Also worth looking at the bot comments.
The import pointed at src/integrations/native_app_start_integration.dart, which the SDK moved to src/app_start/ui_load_attached/. Removing that integration alone also no longer disables app start, since standalone tracing runs through StandaloneAppStartIntegration, so remove both. Replace the firstWhere lookup with a loop as well. App start integrations are only registered on the platforms that support them, and firstWhere throws when they are absent. Co-authored-by: Cursor <cursoragent@cursor.com>
runApp sat between extendAppStart and the try, so a synchronous throw would leave the extension open until the deadline — the opposite of the guidance right above the snippet. Move it inside the try. Apply the same to the child span examples: startChild was outside the try, and the stream getter now inlines as parentSpan, so nothing that can throw sits between extending and finishing. Co-authored-by: Cursor <cursoragent@cursor.com>
The in-flight span streaming pages write these as {tabTitle:Stream Mode} without
a space after the colon. Drop the space so both land consistently.
Co-authored-by: Cursor <cursoragent@cursor.com>
The span streaming docs landed on master in #18764, so the page these snippets refer to now exists. Link it on first mention, matching how the rest of the Dart docs reference stream mode. Co-authored-by: Cursor <cursoragent@cursor.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
DESCRIBE YOUR PR
Documents standalone app start tracing for the Flutter SDK, shipped in 9.26.0 via getsentry/sentry-dart#3896 and getsentry/sentry-dart#3918.
By default the SDK attaches app start data to the first
ui.loadtransaction, which mixes startup timing with screen-display timing. The new experimentalenableStandaloneAppStartTracingoption reports the app start as its ownapp.starttransaction instead, so it no longer depends on a screen transaction being started and can be sampled independently.Follows how Android (#18667) and Apple (#17852, #17920) documented the same feature, adjusted for the fact that Flutter keeps app start on its own integration page rather than in
automatic-instrumentation.mdx.Changes:
includes/dart-integrations/app-start-instrumentation.mdx— new Standalone App Start Tracing section covering the option, the Android/iOS-only limitation, and usingtracesSamplerto give app starts a dedicated sample rate. Plus an Extending the App Start subsection forSentryFlutter.extendAppStart()/finishExtendedAppStart(), including thetry/finallypattern and the 30-second deadline caveat.docs/platforms/dart/guides/flutter/tracing/index.mdx— short experimental-flagged section linking to the detail page, mirroring #17891.docs/platforms/dart/guides/flutter/configuration/options.mdx—enableStandaloneAppStartTracingentry under Tracing Options.IS YOUR CHANGE URGENT?
PRE-MERGE CHECKLIST
EXTRA RESOURCES
Made with Cursor