feat(flutter): Extend standalone app start

[buenaflor]

📜 Description

Experimental SentryFlutter API for extending the standalone App Start past the first frame, so startup work that finishes later is part of the reported duration.

appRunner: () async {
  SentryFlutter.extendAppStart();
  runApp(const MyApp());

  try {
    await completeStartupWork();
  } finally {
    await SentryFlutter.finishExtendedAppStart();
  }
},

extendAppStart() opens one app.start.extended child of the App Start root and holds the root open. finishExtendedAppStart() closes it and releases the app start to report, measuring to the extension end when it outlasts the first frame. While an extension is still open the duration is withheld, rather than reporting a window that ends mid-extension.

To nest work under the extension, take the span itself: getExtendedAppStartSpan() for the V1 ISentrySpan on the static lifecycle, getExtendedAppStartSpanV2() for the V2 SentrySpanV2 on the streaming one — two getters because the protocols don't merge into anything worth exposing publicly. Each returns null on the other lifecycle and once the extension has ended. Finishing the span completes the extension on its own.

Requires enableStandaloneAppStartTracing on iOS or Android. All entry points are guarded at the boundary so an SDK bug can't throw into appRunner, and refusals are logged rather than returned. Operation and method names are verbatim from sentry-java and sentry-cocoa.

Note

Stacked on #3896 — that is the base branch and should be read first.

💡 Motivation and Context

Standalone App Start measures process start to first frame, so work finishing after it — remote config, auth restore, flag hydration — falls outside the window and understates startup. This lets the app say where startup really ends.

Closes #3767

💚 How did you test it?

Unit coverage on both lifecycles: hierarchy and status, nested descendants, the deadline interaction, finishing the span directly instead of via the API, refused extensions and refused finishes, vitals endpoint resolution, and unpublish-on-complete. The example app is wired up end to end.

📝 Checklist

• I reviewed submitted code
• I added tests to verify changes
• No new PII added or SDK only sends newly added PII if sendDefaultPii is enabled
• I updated the docs if needed
• All tests passing
• Public API changes reviewed by another Mobile SDK team member or implemented according to the develop docs spec
• No breaking changes

🔮 Next steps

• Attach E2E trace links for both lifecycles, matching feat(flutter): Add standalone app start tracing #3896
• Merge feat(flutter): Add standalone app start tracing #3896 first — this targets that branch
• docs-site follow-up: add the Flutter section alongside the existing Java / Cocoa / React Native ones

Made with Cursor

[github-actions]

Semver Impact of This PR

🟡 Minor (new features)

📋 Changelog Preview

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

---

Features

Flutter

• Extend standalone app start by buenaflor in #3918

• Add standalone app start tracing by buenaflor in #3896

Dependencies

• chore(deps): update Android SDK to v8.50.1 by github-actions in #3921

Internal Changes

• (deps) Pin Flutter development dependencies by buenaflor in #3913
• (grpc) Move MockHub to _sentry_testing package by lucas-zimerman in #3908

---

_{🤖 This preview updates automatically when you update the PR.}

[codecov]

Codecov Report

❌ Patch coverage is 90.18692% with 21 lines in your changes missing coverage. Please review.
✅ Project coverage is 87.92%. Comparing base (784dceb) to head (e775410).
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
...pp_start/standalone/streaming_app_start_trace.dart	86.41%	11 Missing ⚠️
...c/app_start/standalone/static_app_start_trace.dart	93.18%	6 Missing ⚠️
packages/flutter/lib/src/sentry_flutter.dart	83.33%	4 Missing ⚠️

Additional details and impacted files

@@                        Coverage Diff                        @@
##           feat/standalone-app-start-new    #3918      +/-   ##
=================================================================
+ Coverage                          87.78%   87.92%   +0.14%     
=================================================================
  Files                                346      346              
  Lines                              12655    12854     +199     
=================================================================
+ Hits                               11109    11302     +193     
- Misses                              1546     1552       +6     

Flag	Coverage Δ
sentry	87.62% <ø> (ø)
sentry_dio	97.73% <ø> (ø)
sentry_drift	93.57% <ø> (ø)
sentry_file	65.29% <ø> (ø)
sentry_firebase_remote_config	100.00% <ø> (ø)
sentry_flutter	92.17% <90.18%> (+0.24%)	⬆️
sentry_grpc	99.09% <ø> (ø)
sentry_hive	77.48% <ø> (ø)
sentry_isar	74.37% <ø> (ø)
sentry_link	21.50% <ø> (ø)
sentry_logging	97.01% <ø> (ø)
sentry_sqflite	88.81% <ø> (ø)
sentry_supabase	97.27% <ø> (ø)

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]

@cursor review

[Copilot]

Pull request overview

Adds a public SentryFlutter API surface to extend standalone App Start and attach child spans, with support for both static (V1 span) and streaming (V2 span) trace lifecycles. This builds on the standalone app-start tracing subsystem by allowing an explicit “extended” region and exposing its span handle(s) for downstream instrumentation.

Changes:

• Adds SentryFlutter.extendAppStart(), finishExtendedAppStart(), and lifecycle-specific getters for the extended span (V1/V2).
• Implements extended-span lifecycle, measurement endpoint selection, and close/deadline behaviors for both static and streaming standalone app-start traces.
• Adds comprehensive tests + docs + example usage for the new extended app start flow.

Reviewed changes

Copilot reviewed 16 out of 16 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
packages/flutter/lib/src/sentry_flutter.dart	Adds the new public APIs and span getters for extended standalone app start.
packages/flutter/lib/src/sentry_flutter_options.dart	Publishes an internal standaloneAppStartTrace reference for the public APIs to access.
packages/flutter/lib/src/app_start/standalone/app_start_trace.dart	Extends the internal trace contract with extend/finish/getter APIs and standaloneExtendedAppStartName.
packages/flutter/lib/src/app_start/standalone/static_app_start_trace.dart	Implements extended-span creation/finish and measurement endpoint selection for static lifecycle.
packages/flutter/lib/src/app_start/standalone/streaming_app_start_trace.dart	Implements extended-span creation/finish, V2 lifecycle hooks, and measurement endpoint selection for streaming lifecycle.
packages/flutter/lib/src/app_start/standalone/standalone_app_start_lifecycle.dart	Publishes/clears the active standalone trace on options so SentryFlutter APIs can access it.
packages/flutter/test/sentry_flutter_test.dart	Tests the new public APIs (timestamps forwarded, getters, no-op behavior).
packages/flutter/test/app_start_trace_test_support.dart	Adds a lightweight AppStartTrace test double for API-level tests.
packages/flutter/test/app_start/standalone/static_app_start_trace_test.dart	Adds extensive static-lifecycle coverage for extension span behavior, measurement endpoint, and deadlines.
packages/flutter/test/app_start/standalone/streaming_app_start_trace_test.dart	Adds extensive streaming-lifecycle coverage for extension span behavior, measurement endpoint, and deadlines/close.
packages/flutter/test/app_start/standalone/standalone_app_start_lifecycle_test.dart	Verifies lifecycle publishing/cleanup and parity between static vs streaming extension outputs.
packages/flutter/example/lib/main.dart	Demonstrates using the extended span in both static and streaming lifecycles.
packages/dart/lib/src/sdk_lifecycle_hooks.dart	Adds prepend: option to lifecycle callback registration to control callback ordering.
packages/dart/test/sdk_lifecycle_hooks_test.dart	Tests prepended callback execution order.
packages/dart/lib/src/constants.dart	Adds app.start.extended op constant and a cancelled status-message constant.
docs/standalone-app-start-spec.md	Documents the extended app start APIs and lifecycle behaviors.

Comments suppressed due to low confidence (1)

packages/flutter/lib/src/sentry_flutter.dart:414

• Same concern as extendAppStart(): this should behave as a no-op when inactive, but options.clock() / trace.finishExtended(...) can throw and bubble up to the app. Wrapping in try/catch keeps the API safe and consistent with its no-op semantics.

  static Future<void> finishExtendedAppStart() async {
    final options = Sentry.currentHub.options;
    if (options is SentryFlutterOptions) {
      final trace = options.standaloneAppStartTrace;
      if (trace != null) {
        await trace.finishExtended(options.clock());
      }
    }

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[cursor]

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

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

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