feat(span-first): Add `startSpan` and `startSpanSync` by buenaflor · Pull Request #3574 · getsentry/sentry-dart

buenaflor · 2026-03-18T15:36:49Z

📜 Description

Updates from a single FutureOr<T> startSpan to two distinct ones.

💡 Motivation and Context

FutureOr gets dropped because it pushes ambiguity onto every caller.

It's ergonomically also not well to work with and we want to maximize dev experience as much as possible

💚 How did you test it?

Manually, existing tests and update hub_span_test

📝 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
No breaking changes

🔮 Next steps

#skip-changelog

…nd include startTimestamp parameter Modified the startSpan method across Hub, NoOpHub, and Sentry classes to return type T instead of FutureOr<T>, enhancing type safety. Added an optional startTimestamp parameter to support backdated spans. Updated example usage in the Flutter demo to demonstrate synchronous span creation.

Added a new startSpanSync method to the Hub, NoOpHub, and Sentry classes, allowing for synchronous span creation with a callback. Updated the startSpan method to return Future<T> for asynchronous operations. Enhanced documentation to clarify usage and added tests to ensure correct behavior of the new synchronous method.

Add tests covering the NoOpSentrySpanV2 code path in both startSpan and startSpanSync for two scenarios: hub is closed and traceLifecycle is static. These paths skip zone forking and call the callback directly, which was previously untested. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

github-actions · 2026-03-18T15:37:09Z

🚨 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/integrations/native_app_start_integration.dart

github-actions · 2026-03-18T15:38:28Z

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

Generated by 🚫 dangerJS against 346681c

The Hub.startSpan return type changed from FutureOr<T> to Future<T>, causing MockHub.startSpan to be out of sync. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

…n creation Replaced the call to Sentry.startSpan with Sentry.startSpanSync in the Flutter example to demonstrate the synchronous span creation functionality. This aligns with recent changes to the span API and enhances the example's clarity.

Removed the _endActiveSpan method and integrated its functionality directly into the error handling of startSpan. Now, spans are ended and their status is set to error in the catch block, improving code clarity and reducing redundancy.

Removed unnecessary variable assignments in the runZoned calls within the Hub class, enhancing code readability and reducing redundancy. The changes simplify the asynchronous handling of spans while maintaining functionality.

Copilot

Pull request overview

This PR splits the Span V2 callback API into two explicit variants—startSpan for async work and startSpanSync for synchronous work—removing the previous FutureOr<T> ambiguity and updating call sites, mocks, and tests accordingly.

Changes:

Change startSpan to require an async callback (Future<T>) and return Future<T>.
Add startSpanSync for synchronous callbacks returning T.
Propagate startTimestamp through the new APIs and update tests/examples/mocks.

Reviewed changes

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

Show a summary per file

File	Description
packages/dart/lib/src/hub.dart	Implements async `startSpan` and new `startSpanSync`, sharing zone-based active-span scoping.
packages/dart/lib/src/sentry.dart	Updates public Sentry API to `Future<T> startSpan` + adds `startSpanSync`, plus doc tweaks.
packages/dart/lib/src/noop_hub.dart	Updates NoOpHub to match the new Hub interface (async + sync variants, `startTimestamp`).
packages/dart/lib/src/hub_adapter.dart	Forwards new `startSpan`/`startSpanSync` signatures and `startTimestamp` to `Sentry.currentHub`.
packages/dart/test/hub_span_test.dart	Updates existing tests and adds coverage for the new sync/async split and `startTimestamp`.
packages/flutter/test/user_interaction/sentry_user_interaction_widget_test.dart	Migrates a test call site from async `startSpan` to `startSpanSync`.
packages/flutter/test/mocks.mocks.dart	Regenerates Mockito mocks to reflect the new Hub API (`startSpanSync`, `startTimestamp`, async-only `startSpan`).
packages/flutter/example/lib/main.dart	Demonstrates new `Sentry.startSpanSync` usage in the example app.

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

packages/dart/lib/src/sentry.dart

packages/flutter/test/user_interaction/sentry_user_interaction_widget_test.dart

packages/dart/test/hub_span_test.dart

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

…feat/span/change-futureor

Removed outdated comments regarding active spans in zone-forked scopes.

Updated comments in the Hub class to clarify the behavior of the _zoneScope and getActiveSpan methods. The changes improve the understanding of how zone-forked scopes and active spans are managed, including the resolution order for active spans.

Updated the startSpan method to be asynchronous, improving the handling of span creation and execution within the Hub class. This change enhances the overall flow of asynchronous operations while maintaining existing functionality.

packages/dart/lib/src/hub.dart

packages/dart/test/hub_span_test.dart

…anSync Updated the documentation for startSpan and startSpanSync methods to clarify their behavior, including nesting capabilities and handling of NoOpSentrySpanV2. Added comprehensive tests to verify the correct parent-child relationships between synchronous and asynchronous spans, ensuring accurate span management in various scenarios.

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.}

packages/dart/lib/src/noop_hub.dart

denrase

Just one comment for the non-wrapped comments.

…an method Updated the startSpan method in the NoOpHub class to ensure the startTimestamp parameter is optional, enhancing flexibility in span creation. This change aligns with the asynchronous nature of span handling introduced in previous commits.

Updated the startSpanSync method in the NoOpHub class to remove the async keyword, ensuring it operates synchronously. This change aligns with the method's intended functionality and improves clarity in its usage.

buenaflor and others added 3 commits March 18, 2026 12:23

buenaflor changed the base branch from main to feat/span-first March 18, 2026 15:37

buenaflor changed the title ~~test(span): Add missing critical tests for startSpan and startSpanSync~~ feat(span-first): Add startSpan and startSpanSync Mar 18, 2026

buenaflor and others added 5 commits March 18, 2026 16:52

build(flutter): Regenerate mocks for updated startSpan signature

967e251

The Hub.startSpan return type changed from FutureOr<T> to Future<T>, causing MockHub.startSpan to be out of sync. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

fix analyze error

10a2306

refactor(span): Streamline runZoned usage in Hub class

f7e0ce3

Removed unnecessary variable assignments in the runZoned calls within the Hub class, enhancing code readability and reducing redundancy. The changes simplify the asynchronous handling of spans while maintaining functionality.

buenaflor marked this pull request as ready for review March 18, 2026 16:34

buenaflor requested a review from denrase as a code owner March 18, 2026 16:34

Copilot AI review requested due to automatic review settings March 18, 2026 16:34

Copilot started reviewing on behalf of buenaflor March 18, 2026 16:35 View session

Copilot AI reviewed Mar 18, 2026

View reviewed changes

packages/dart/lib/src/sentry.dart Outdated Show resolved Hide resolved

packages/dart/lib/src/sentry.dart Show resolved Hide resolved

packages/flutter/test/user_interaction/sentry_user_interaction_widget_test.dart Outdated Show resolved Hide resolved

cursor bot reviewed Mar 18, 2026

View reviewed changes

packages/dart/test/hub_span_test.dart Outdated Show resolved Hide resolved

buenaflor and others added 7 commits March 18, 2026 17:41

Potential fix for pull request finding

e803278

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Potential fix for pull request finding

3eba4e6

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

update

8d7fadb

Merge remote-tracking branch 'origin/feat/span/change-futureor' into …

9301c5a

…feat/span/change-futureor

Refactor getActiveSpan documentation comments

e534df8

Removed outdated comments regarding active spans in zone-forked scopes.

denrase requested changes Mar 20, 2026

View reviewed changes

buenaflor requested a review from denrase March 20, 2026 10:17

cursor bot reviewed Mar 20, 2026

View reviewed changes

packages/dart/lib/src/noop_hub.dart Show resolved Hide resolved

denrase approved these changes Mar 20, 2026

View reviewed changes

buenaflor added 2 commits March 20, 2026 11:29

fix(hub): Remove async keyword from startSpanSync method in NoOpHub

346681c

Updated the startSpanSync method in the NoOpHub class to remove the async keyword, ensuring it operates synchronously. This change aligns with the method's intended functionality and improves clarity in its usage.

buenaflor merged commit ce21ef2 into feat/span-first Mar 23, 2026
138 of 140 checks passed

buenaflor deleted the feat/span/change-futureor branch March 23, 2026 08:47

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat(span-first): Add `startSpan` and `startSpanSync`#3574

feat(span-first): Add `startSpan` and `startSpanSync`#3574
buenaflor merged 18 commits intofeat/span-firstfrom
feat/span/change-futureor

buenaflor commented Mar 18, 2026 •

edited

Loading

Uh oh!

github-actions bot commented Mar 18, 2026

Uh oh!

github-actions bot commented Mar 18, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cursor bot left a comment

Uh oh!

Uh oh!

denrase left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

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

Uh oh!

📜 Description

💡 Motivation and Context

💚 How did you test it?

📝 Checklist

🔮 Next steps

Uh oh!

github-actions bot commented Mar 18, 2026

🚨 Detected changes in high risk code 🚨

Uh oh!

github-actions bot commented Mar 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cursor bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

denrase left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

buenaflor commented Mar 18, 2026 •

edited

Loading

github-actions bot commented Mar 18, 2026 •

edited

Loading