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.

Ref: getsentry/sentry-dart#3886

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 14, 2026 2:04pm

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
develop-docs	Ignored	Preview	Jul 14, 2026 2:04pm

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

[Copilot]

Pull request overview

Adds initial Dart/Flutter documentation for stream mode (span streaming), including a new “Streamed Spans” landing page, a migration guide from transaction APIs to span APIs, and reusable include snippets for enabling traceLifecycle: SentryTraceLifecycle.stream.

Changes:

• Introduces Streamed Spans documentation with explanations, examples, and verification guidance (SDK >= 9.23.0).
• Adds a Migrate to Stream Mode guide mapping transaction-mode APIs to the new span APIs and configuration hooks (beforeSendSpan, ignoreSpans, updated sampling context).
• Adds reusable platform-include snippets (full and diff-style) for enabling stream mode in Dart and Flutter SDK initialization.

Reviewed changes

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

Show a summary per file

File	Description
platform-includes/performance/span-streaming-enable/dart.mdx	New include snippet showing how to enable stream mode in Dart via traceLifecycle.
platform-includes/performance/span-streaming-enable/dart.flutter.mdx	New include snippet showing how to enable stream mode in Flutter via traceLifecycle.
platform-includes/performance/span-streaming-enable-diff/dart.mdx	New diff-style include highlighting the single config change for Dart.
platform-includes/performance/span-streaming-enable-diff/dart.flutter.mdx	New diff-style include highlighting the single config change for Flutter.
docs/platforms/dart/common/tracing/streamed-spans/migration-guide.mdx	New migration guide from transaction APIs/options to stream-mode span APIs/options.
docs/platforms/dart/common/tracing/streamed-spans/index.mdx	New Streamed Spans landing page explaining concepts, usage, configuration, and verification.