docs(dart): Cover stream mode across tracing pages by buenaflor · Pull Request #18611 · getsentry/sentry-docs

buenaflor · 2026-07-01T09:19:12Z

DESCRIBE YOUR PR

Documents stream mode across the Dart/Flutter tracing pages. Following the Python precedent, code snippets gain a Stream Mode tab next to Transaction Mode (Default) (nothing is removed), and prose is genericized to cover both modes.

Custom instrumentation (page + 5 code includes) → dual Transaction/Stream tabs, startSpan-only
Automatic instrumentation & performance metrics → mode-neutral wording; setMeasurement → span attributes
Tracing setup + Verify → New Spans pointer and mode-aware wording
Distributed-trace custom instrumentation → notes that trace continuation isn't supported in stream mode yet
Transaction-name and features → mode notes

Stacked on #18554 — review/merge that first.

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 · 2026-07-01T09:19:18Z

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

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

1 Skipped Deployment

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

Copilot

Pull request overview

Updates the Dart and Flutter tracing documentation to clarify how stream mode (span streaming) affects manual/automatic instrumentation and distributed trace continuation, aligning the tracing pages with the newer span APIs.

Changes:

Adds stream mode callouts to manual instrumentation pages, directing readers to Sentry.startSpan APIs (since transaction APIs are no-ops in stream mode).
Adds stream mode callouts to automatic instrumentation pages noting that auto-instrumentation switches to streaming span APIs automatically.
Adds stream mode callouts to trace propagation pages noting that continuing an incoming distributed trace isn’t supported yet in stream mode.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
docs/platforms/dart/guides/flutter/tracing/trace-propagation/index.mdx	Adds a stream mode limitation callout for continuing incoming distributed traces.
docs/platforms/dart/guides/flutter/tracing/instrumentation/custom-instrumentation.mdx	Adds a stream mode callout pointing manual instrumentation to `Sentry.startSpan` and New Spans.
docs/platforms/dart/guides/flutter/tracing/instrumentation/automatic-instrumentation.mdx	Adds a stream mode callout stating auto-instrumentation switches APIs automatically and links to New Spans.
docs/platforms/dart/common/tracing/trace-propagation/index.mdx	Adds a stream mode limitation callout for continuing incoming distributed traces.
docs/platforms/dart/common/tracing/trace-propagation/custom-instrumentation/index.mdx	Adds a stream mode limitation callout and links to New Spans.
docs/platforms/dart/common/tracing/instrumentation/custom-instrumentation.mdx	Adds a stream mode callout pointing manual instrumentation to `Sentry.startSpan` and New Spans.
docs/platforms/dart/common/tracing/instrumentation/automatic-instrumentation.mdx	Adds a stream mode callout stating auto-instrumentation switches APIs automatically and links to New Spans.

Point custom instrumentation to the new Sentry.startSpan APIs for stream mode, note that automatic instrumentation switches to the streaming span API automatically, and flag that continuing an incoming distributed trace isn't supported yet in stream mode. Covers both Dart and Flutter. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Convert the custom-instrumentation code snippets to dual Transaction Mode (Default) / Stream Mode tabs, mirroring the Python docs approach. Reword prose to cover both modes. Co-Authored-By: Claude <noreply@anthropic.com>

Use Sentry.startSpan (async) in all stream mode snippets instead of mixing in startSpanSync; startSpanSync is documented once in New Spans as the synchronous-signature variant. Co-Authored-By: Claude <noreply@anthropic.com>

Genericize automatic-instrumentation and performance-metrics prose to cover both modes, and add a Stream Mode tab to custom performance metrics (setMeasurement -> span attributes). Co-Authored-By: Claude <noreply@anthropic.com>

Add a New Spans pointer and mode-aware wording to the tracing setup and Verify sections, note that distributed-trace continuation and transaction naming differ in stream mode, and genericize the features overview. Co-Authored-By: Claude <noreply@anthropic.com>

Use SentryAttribute.stringArray/intArray/boolArray for the array cases, matching the transaction-mode setData arrays. Co-Authored-By: Claude <noreply@anthropic.com>

inventarSarah · 2026-07-07T09:07:43Z


+<Alert>
+
+In stream mode, continuing an incoming distributed trace isn't supported yet. See <PlatformLink to="/tracing/new-spans/">New Spans</PlatformLink>.


I would also add a note about this to the main page if that sounds alright to you

Hmm, I am thinking that since Flutter is a mobile SDK and therefore always head of the trace, there is no use case for incoming traces and we don't support any backend use cases for Dart

Not sure how much we need to point out incoming distributed tracing since for the almost all of users in Dart/Flutter this won't be relevant

If it's not relevant for most users, then let's keep it here as a note and not include it in the main page 👍

inventarSarah · 2026-07-07T09:21:12Z

+## Add More Spans to the Transaction/Service Span

-By default, transactions are not bound to the scope. Transaction has to be passed manually as a method parameter to enable attaching nested spans. When creating nested span, you can choose the value of `operation` and `description`.
+In transaction mode, transactions aren't bound to the scope, so the transaction has to be passed manually as a method parameter to attach nested spans. In stream mode, nested spans attach to the active span automatically — no manual passing needed. When creating a nested span, you can choose its name and `sentry.op`.


What is "sentry.op"? - I haven't seen that in our Dart docs until now

Oh, is that for startTransaction?

the operation parameter is not built into the function like in startTransaction and instead in startSpan you'd have to add it yourself. however I am not entirely sure if we wanna document this at all - does python document this?

In Python, almost all startSpan examples include sentry.op. And in the migration guide, we explicitly state: "- op is no longer a dedicated argument — set it as the sentry.op attribute instead."

Example:

with sentry_sdk.traces.start_span(name="SELECT", attributes={"sentry.op": "db"}, parent_span=parent): ...

So from your comment, I assume it is the same in Dart where you have to add op as an attribute?

yes, it's the same in Dart - then I guess we can also keep documenting it here

Copilot AI review requested due to automatic review settings July 1, 2026 09:19

codeowner-assignment Bot requested a review from a team July 1, 2026 09:19

Copilot started reviewing on behalf of buenaflor July 1, 2026 09:19 View session

buenaflor marked this pull request as draft July 1, 2026 09:21

Copilot AI reviewed Jul 1, 2026

View reviewed changes

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

buenaflor force-pushed the buenaflor/docs/dart-span-streaming-tracing branch from 45fa64b to dff9eb6 Compare July 1, 2026 10:23

buenaflor changed the base branch from master to buenaflor/docs/dart-span-streaming-new-spans July 1, 2026 10:23

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

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

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

buenaflor force-pushed the buenaflor/docs/dart-span-streaming-tracing branch from fedd806 to fbc2c56 Compare July 6, 2026 12:36

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

buenaflor mentioned this pull request Jul 6, 2026

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

Draft

6 tasks

buenaflor changed the title ~~docs(dart): Note stream mode in tracing instrumentation pages~~ docs(dart): Cover stream mode across tracing pages Jul 6, 2026

buenaflor and others added 6 commits July 6, 2026 15:43

docs(dart): Add stream mode tabs to custom instrumentation

b892277

Convert the custom-instrumentation code snippets to dual Transaction Mode (Default) / Stream Mode tabs, mirroring the Python docs approach. Reword prose to cover both modes. Co-Authored-By: Claude <noreply@anthropic.com>

docs(dart): Use startSpan consistently in stream mode examples

773fa74

Use Sentry.startSpan (async) in all stream mode snippets instead of mixing in startSpanSync; startSpanSync is documented once in New Spans as the synchronous-signature variant. Co-Authored-By: Claude <noreply@anthropic.com>

docs(dart): Show array attributes in stream mode data example

2fc3a53

Use SentryAttribute.stringArray/intArray/boolArray for the array cases, matching the transaction-mode setData arrays. Co-Authored-By: Claude <noreply@anthropic.com>

buenaflor force-pushed the buenaflor/docs/dart-span-streaming-tracing branch from fbc2c56 to 2fc3a53 Compare July 6, 2026 13:43

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

inventarSarah reviewed Jul 7, 2026

View reviewed changes


		<Alert>

		In stream mode, continuing an incoming distributed trace isn't supported yet. See <PlatformLink to="/tracing/new-spans/">New Spans</PlatformLink>.

Uh oh!

Uh oh!

Conversation

buenaflor commented Jul 1, 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 Jul 1, 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!

inventarSarah Jul 7, 2026

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!

inventarSarah Jul 7, 2026

Choose a reason for hiding this comment

Uh oh!

inventarSarah Jul 7, 2026

Choose a reason for hiding this comment

Uh oh!

inventarSarah Jul 7, 2026

Choose a reason for hiding this comment

Uh oh!

buenaflor Jul 7, 2026

Choose a reason for hiding this comment

Uh oh!

inventarSarah Jul 7, 2026

Choose a reason for hiding this comment

Uh oh!

buenaflor Jul 7, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

buenaflor commented Jul 1, 2026 •

edited

Loading

vercel Bot commented Jul 1, 2026 •

edited

Loading

buenaflor Jul 7, 2026 •

edited

Loading