docs(dart): Add New Spans page and stream mode migration guide - #18554
Merged
buenaflor merged 14 commits intoJul 20, 2026
Merged
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
1 Skipped Deployment
|
This was referenced Jul 1, 2026
buenaflor
changed the title
inventarSarah
force-pushed
the
buenaflor/docs/dart-span-streaming-new-spans
branch
from
July 9, 2026 11:17
47f4b17 to
e3ee6bc
Compare
inventarSarah
marked this pull request as ready for review
July 9, 2026 11:33
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>
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>
buenaflor
force-pushed
the
buenaflor/docs/dart-span-streaming-new-spans
branch
from
July 14, 2026 11:37
e3ee6bc to
522b994
Compare
Contributor
There was a problem hiding this comment.
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 Spansdocumentation with explanations, examples, and verification guidance (SDK>= 9.23.0). - Adds a
Migrate to Stream Modeguide 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. |
Distinguish local parents from remote parents across service boundaries. Clean up the scope-tag wording and remove the leading blank line from the parentSpan example. Co-Authored-By: Claude <noreply@anthropic.com>
inventarSarah
approved these changes
Jul 16, 2026
buenaflor
changed the base branch from
master
to
buenaflor/feat-dart-flutter-span-streaming
July 20, 2026 08:40
## 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. 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.): <!-- ENTER DATE HERE --> - [ ] Other deadline: <!-- ENTER DATE HERE --> - [x] 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](https://github.com/orgs/getsentry/teams/docs) --------- Co-authored-by: Claude <noreply@anthropic.com> Co-authored-by: inventarSarah <sarah@codingwriter.com>
## DESCRIBE YOUR PR Documents **stream mode** across the Dart/Flutter integration guides. - Adds a reusable stream-mode callout to every integration page (transactions become service spans; auto-instrumentation switches automatically) - Adds inline `// or, in stream mode: Sentry.startSpan(...)` hints next to the transaction/span creation in the integration code snippets (http, dio, file, graphql, sqflite, drift, hive, isar, asset bundle, user interaction), mirroring the Python integrations approach Stacked on #18554 — review/merge that first. 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.): <!-- ENTER DATE HERE --> - [ ] Other deadline: <!-- ENTER DATE HERE --> - [x] 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](https://github.com/orgs/getsentry/teams/docs) --------- Co-authored-by: Claude <noreply@anthropic.com> Co-authored-by: inventarSarah <sarah@codingwriter.com>
## DESCRIBE YOUR PR Documents **stream mode** across the Dart/Flutter configuration pages. - `options.mdx`: new `traceLifecycle`, `beforeSendSpan`, and `ignoreSpans` options (both Dart and Flutter) - `filtering.mdx`: a "Filtering Spans in Stream Mode" section (`ignoreSpans` + `beforeSendSpan`) - `sampling.mdx`: notes that a custom `tracesSampler` receives a span sampling context in stream mode, and that custom sampling context / forcing a decision don't apply - Stream-mode notes in sensitive-data and profiling Stacked on #18554 — review/merge that first. 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.): <!-- ENTER DATE HERE --> - [ ] Other deadline: <!-- ENTER DATE HERE --> - [x] 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](https://github.com/orgs/getsentry/teams/docs) --------- Co-authored-by: Claude <noreply@anthropic.com> Co-authored-by: inventarSarah <sarah@codingwriter.com>
buenaflor
merged commit Jul 20, 2026
8b14a95
into
buenaflor/feat-dart-flutter-span-streaming
5 of 9 checks passed
buenaflor
added a commit
that referenced
this pull request
Jul 21, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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.
traceLifecycle: SentryTraceLifecycle.stream), manual instrumentation (startSpan/startSpanSync/startInactiveSpan), typedSentryAttributeattributes (including array factories), span status,beforeSendSpan/ignoreSpans, sampling, and verification9.23.0This 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.
SLA
Thanks in advance for your help!
PRE-MERGE CHECKLIST
Make sure you've checked the following before merging your changes: