docs(dart): Add New Spans page and stream mode migration guide

[buenaflor]

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

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
sentry-docs	Ready	Preview, Comment	Jul 9, 2026 11:27am

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
develop-docs	Ignored	Preview	Jul 9, 2026 11:27am

[inventarSarah]

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>

[buenaflor]

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]

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

[buenaflor]

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();
}