docs(dart): Add New Spans page and stream mode migration guide by buenaflor · Pull Request #18554 · getsentry/sentry-docs

buenaflor · 2026-06-25T13:36:54Z

DESCRIBE YOUR PR

Introduces the Dart/Flutter stream mode (span streaming) documentation — the base of a 4-PR stack. Mirrors the Python New Spans docs.

New New Spans page: enabling stream mode (traceLifecycle: SentryTraceLifecycle.stream), manual instrumentation (startSpan/startSpanSync/startInactiveSpan), typed SentryAttribute attributes (including array factories), span status, beforeSendSpan/ignoreSpans, sampling, and verification
New Migrate to Stream Mode guide mapping the transaction API to the new span API
Minimum SDK version documented as 9.23.0

This is the bottom of the stack — merge this first. Stacked children: #18609, #18610, #18611.

IS YOUR CHANGE URGENT?

Help us prioritize incoming PRs by letting us know when the change needs to go live.

Urgent deadline (GA date, etc.):
Other deadline:
None: Not urgent, can wait up to 1 week+

SLA

Teamwork makes the dream work, so please add a reviewer to your PRs.
Please give the docs team up to 1 week to review your PR unless you've added an urgent due date to it.
Thanks in advance for your help!

PRE-MERGE CHECKLIST

Make sure you've checked the following before merging your changes:

Checked Vercel preview for correctness, including links
PR was reviewed and approved by any necessary SMEs (subject matter experts)
PR was reviewed and approved by a member of the Sentry docs team

Document stream mode (SentryTraceLifecycle.stream) for the Dart and Flutter SDKs, where spans are sent as they finish instead of being batched into a transaction. Mirrors the Python New Spans pages. - New Spans page: enabling stream mode, manual instrumentation with startSpan/startSpanSync/startInactiveSpan, typed attributes, status, beforeSendSpan/ignoreSpans, sampling, and verification - Migration guide: mapping transaction-based APIs to the new span APIs - Platform-includes split init snippets for Flutter vs plain Dart Co-Authored-By: Claude <noreply@anthropic.com>

vercel · 2026-06-25T13:37:00Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
sentry-docs	Ready	Preview, Comment	Jul 8, 2026 1:24pm

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
develop-docs	Ignored	Preview	Jul 8, 2026 1:24pm

Fix two factual errors in the New Spans pages verified against the SDK source: a custom tracesSampler receives a different sampling context in stream mode (read name and attributes from spanContext, not the transaction context), and beforeSendSpan runs when each span ends and sees all attributes rather than only creation-time ones. Also add the service span type to the span taxonomy. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

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

Add the array SentryAttribute factories (stringArray/intArray/boolArray/ doubleArray) to the attributes table and clarify that startSpanSync is the synchronous variant of startSpan (T vs Future<T> callback). Co-Authored-By: Claude <noreply@anthropic.com>

The enum has four values (ok, error, cancelled, deadlineExceeded), not just ok/error. Fix the New Spans and migration guide wording. Co-Authored-By: Claude <noreply@anthropic.com>

Per SDK maintainer: only ok and error are valid stream-mode span statuses. Co-Authored-By: Claude <noreply@anthropic.com>

Mirror the Python migration guide: scope setTag isn't applied to streamed spans; use Sentry.setAttributes to set span-applying attributes. Co-Authored-By: Claude <noreply@anthropic.com>

inventarSarah · 2026-07-07T08:33:32Z

+- In `stream` mode, the transaction APIs (`Sentry.startTransaction`, `ISentrySpan.startChild`) do nothing and log a warning.
+- In `static` mode, the new span APIs (`Sentry.startSpan`) do nothing.
+- Auto-instrumentations switch to the correct API automatically based on this setting.
+


I'd like to add the Expandable "How does span flushing work?" we have in the other guides here too. Or is there a specific reason why it's not included on this page?

This is the content I'd add (copied from Python):

<Expandable title="How does span flushing work?"> When stream mode is enabled, the SDK maintains an internal buffer that groups spans by trace ID. Spans are flushed: - On a regular interval (every 5 seconds by default). - When a trace's buffer reaches 1,000 spans. - When the SDK shuts down. Each flush sends only the spans accumulated since the last flush, grouped into envelopes by trace ID. </Expandable>

Sounds good, I'd also add:

When the internal buffer size exceeds 1 MiB or something like that. This is specific to mobile because we have tighter memory constraints

inventarSarah · 2026-07-07T08:33:41Z

+
+By default, a span inherits the currently active span as its parent. To change this, pass `parentSpan`:
+
+- `parentSpan: null` forces a root span with no parent.


does this force a root span or a service span?
iirc, in python, it's a service span

Service span should be more accurate here 👍

inventarSarah · 2026-07-07T08:33:45Z

+By default, a span inherits the currently active span as its parent. To change this, pass `parentSpan`:
+
+- `parentSpan: null` forces a root span with no parent.
+- `parentSpan: someSpan` parents the new span under a specific `SentrySpanV2`.


we mention SentrySpanV2 twice in this document -> will this be documented somewhere we can link to (I haven't looked at the other prs yet)? If not, I propose to just write "span"

Not explictly no, it's the class name for the Span you use in Dart code. I'm also fine with just calling it span

inventarSarah · 2026-07-07T08:33:53Z

+
+Only **root spans** are sampled; child spans inherit the root span's decision. When a root span isn't sampled, its callback still executes with a no-op span, so all span operations remain safe to call.
+
+## Flutter Auto-Instrumentation


Does it make sense to only show this on the Flutter page and not the Dart page?

Ah that's my bad. yes definitely

inventarSarah · 2026-07-07T08:33:56Z

+- } finally {
+-   await transaction.finish();
+- }
+ await Sentry.startSpan('checkout', (span) async {


We should add more examples here like we did for Python:

start a span

Start what used to be a transaction (parent none)

Start a child span while a parent is active

Start a child span with a parent that's currently not active

let me know if you have any thoughts on this

Makes sense, here are some examples - feel free to adapt these as you see fit

1. Start a span

If there is no active parent, this becomes a service span. If there is an active span, it becomes a child automatically.

await Sentry.startSpan('load-user', (span) async { span.setAttribute('user.id', SentryAttribute.string(userId)); await loadUser(userId); });

2. Start what used to be a transaction

Explicitly pass parentSpan: null to force a service span.

await Sentry.startSpan( 'checkout-flow', (span) async { await runCheckout(); }, parentSpan: null, );

3. Start a child span while a parent is active

Nested startSpan calls parent automatically through zones.

await Sentry.startSpan('checkout-flow', (checkoutSpan) async { await Sentry.startSpan('charge-card', (chargeSpan) async { await paymentService.charge(); }); await Sentry.startSpan('create-order', (orderSpan) async { await orderService.create(); }); });

4. Start a child span with a parent that is not active

Keep the parent span reference and pass it explicitly.

final parent = Sentry.startInactiveSpan( 'background-sync', parentSpan: null, ); try { await someOtherAsyncBoundary(); await Sentry.startSpan( 'fetch-page', (child) async { await api.fetchPage(); }, parentSpan: parent, ); } finally { parent.end(); }

inventarSarah · 2026-07-07T08:50:33Z

+
+#### Spans That Outlive a Callback
+
+Use `Sentry.startInactiveSpan` when the work can't be wrapped in a single callback — widget lifecycles, stream subscriptions, or platform channel round-trips. You must call `end()` manually, and other spans do **not** automatically become its children:


.... and other spans do **not** automatically become its children:

How do you create child spans in that case?

Do you have to set the parent explicitly?

Yes, then the 'inactive span' needs to be set as parent specifically

… Python guides

codeowner-assignment Bot requested a review from a team June 25, 2026 13:37

vercel Bot deployed to Preview – sentry-docs June 25, 2026 13:47 View deployment

This was referenced Jul 1, 2026

docs(dart): Document stream mode in configuration pages #18609

Draft

docs(dart): Document stream mode in integration guides #18610

Draft

docs(dart): Cover stream mode across tracing pages #18611

Draft

vercel Bot deployed to Preview – sentry-docs July 1, 2026 09:30 View deployment

docs(dart): Bump span streaming min SDK version to 9.23.0

a8b6c0c

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

vercel Bot deployed to Preview – sentry-docs July 6, 2026 10:08 View deployment

buenaflor and others added 3 commits July 6, 2026 14:10

docs(dart): Correct SentrySpanStatusV2 possible values

bea3913

The enum has four values (ok, error, cancelled, deadlineExceeded), not just ok/error. Fix the New Spans and migration guide wording. Co-Authored-By: Claude <noreply@anthropic.com>

docs(dart): Revert span status to ok/error only

f7edbe7

Per SDK maintainer: only ok and error are valid stream-mode span statuses. Co-Authored-By: Claude <noreply@anthropic.com>

vercel Bot deployed to Preview – sentry-docs July 6, 2026 12:36 View deployment

buenaflor changed the title ~~docs(dart): Draft New Spans and Migration Guide pages~~ docs(dart): Add New Spans page and stream mode migration guide Jul 6, 2026

docs(dart): Note scope tags don't apply to spans in stream mode

0609993

Mirror the Python migration guide: scope setTag isn't applied to streamed spans; use Sentry.setAttributes to set span-applying attributes. Co-Authored-By: Claude <noreply@anthropic.com>

vercel Bot deployed to Preview – sentry-docs July 6, 2026 13:54 View deployment

inventarSarah reviewed Jul 7, 2026

View reviewed changes

rename new spans to streamed spans; update pages for consistency with…

6b73cb4

… Python guides

vercel Bot deployed to Preview – sentry-docs July 8, 2026 13:24 View deployment


		By default, a span inherits the currently active span as its parent. To change this, pass `parentSpan`:

		- `parentSpan: null` forces a root span with no parent.


		Only root spans are sampled; child spans inherit the root span's decision. When a root span isn't sampled, its callback still executes with a no-op span, so all span operations remain safe to call.

		## Flutter Auto-Instrumentation


		#### Spans That Outlive a Callback

		Use `Sentry.startInactiveSpan` when the work can't be wrapped in a single callback — widget lifecycles, stream subscriptions, or platform channel round-trips. You must call `end()` manually, and other spans do not automatically become its children:

Uh oh!

Uh oh!

Conversation

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

Uh oh!

DESCRIBE YOUR PR

IS YOUR CHANGE URGENT?

SLA

PRE-MERGE CHECKLIST

Uh oh!

vercel Bot commented Jun 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

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

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!

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

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!

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

Uh oh!

Choose a reason for hiding this comment

1. Start a span

2. Start what used to be a transaction

3. Start a child span while a parent is active

4. Start a child span with a parent that is not active

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

buenaflor commented Jun 25, 2026 •

edited

Loading

vercel Bot commented Jun 25, 2026 •

edited

Loading

buenaflor Jul 7, 2026 •

edited

Loading

buenaflor Jul 7, 2026 •

edited

Loading

buenaflor Jul 7, 2026 •

edited

Loading