docs(dart): Document stream mode in configuration pages by buenaflor · Pull Request #18609 · getsentry/sentry-docs

buenaflor · 2026-07-01T09:05:17Z

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.

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:05:23Z

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 12:35pm

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
develop-docs	Ignored	Preview	Jul 9, 2026 12:35pm

Copilot

Pull request overview

Documents Dart/Flutter “stream mode” (span streaming) behavior across existing Configuration and data-management pages, aligning Dart/Flutter guidance with the corresponding Python documentation effort and the new span APIs introduced in sentry-dart 9.19.0.

Changes:

Adds Stream Mode configuration options (traceLifecycle, beforeSendSpan, ignoreSpans) to Options pages (common + Flutter override).
Adds stream-mode-specific guidance to Sampling, Filtering, and Sensitive Data pages (including samplingContext.spanContext and span scrubbing).
Notes feature limitations in stream mode (profiling unavailable) on the Flutter Profiling page.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
docs/platforms/dart/guides/flutter/profiling/index.mdx	Adds a warning that profiling is not available in stream mode.
docs/platforms/dart/guides/flutter/data-management/sensitive-data/index.mdx	Adds stream-mode span scrubbing guidance via `beforeSendSpan` and link to New Spans.
docs/platforms/dart/guides/flutter/configuration/sampling.mdx	Adds stream-mode callout about `tracesSampler` sampling context (`samplingContext.spanContext`).
docs/platforms/dart/guides/flutter/configuration/options.mdx	Documents stream-mode options (`traceLifecycle`, `beforeSendSpan`, `ignoreSpans`) and sampling-context note.
docs/platforms/dart/guides/flutter/configuration/filtering.mdx	Adds a stream-mode section describing span filtering/modification using `ignoreSpans`/`beforeSendSpan`.
docs/platforms/dart/common/data-management/sensitive-data/index.mdx	Same stream-mode sensitive data guidance for the common Dart pages.
docs/platforms/dart/common/configuration/sampling.mdx	Same stream-mode sampling-context callout for the common Dart pages.
docs/platforms/dart/common/configuration/options.mdx	Same stream-mode options and sampling-context note for the common Dart pages.
docs/platforms/dart/common/configuration/filtering.mdx	Same stream-mode filtering section for the common Dart pages.

inventarSarah · 2026-07-07T08:47:36Z


+<Alert level="warning">
+
+Profiling isn't available in stream mode. It works only with the default transaction mode (`SentryTraceLifecycle.static`).


Does it make sense to you to also add this to the main page (New Spans) and display it only for Flutter?

Actually, I think we should remove this. the profiling we have in Flutter is only Alpha and might be removed soon

Okay, then I'll remove this warning

inventarSarah · 2026-07-09T08:43:41Z

+
+You can also use <PlatformIdentifier name="before-send-transaction" /> (for transaction mode) or <PlatformIdentifier name="before-send-span" /> (for stream mode) to modify transaction/span data.

 ### Using <PlatformIdentifier name="ignore-transactions" />


above, we write about beforeSendTransaction but then we document ignoreTransactions, which I've never seen until now. And it is also not in the respective page for Flutter.

We should document beforeSendTransaction here as well (also missing for Flutter).

We should document ignoreTransactions in the migration guide (use ignoreSpans instead)

Let me know what you think :)

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>

Add the stream mode configuration options (traceLifecycle, beforeSendSpan, ignoreSpans) to the Options pages, and cover stream mode behavior in the filtering, sampling, sensitive-data, and profiling pages for both Dart and Flutter. Note that a custom tracesSampler receives a different sampling context and that profiling is unavailable in stream mode. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

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

Custom sampling context and forcing a sampling decision don't exist in stream mode; note that data should be passed as span attributes and read via samplingContext.spanContext in a tracesSampler instead. Co-Authored-By: Claude <noreply@anthropic.com>

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

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

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

Copilot AI reviewed Jul 1, 2026

View reviewed changes

Comment thread docs/platforms/dart/common/configuration/options.mdx Outdated

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

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

buenaflor force-pushed the buenaflor/docs/dart-span-streaming-config branch from 77a12de to 7328412 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 10:09 View deployment

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

buenaflor force-pushed the buenaflor/docs/dart-span-streaming-config branch from 93cbe73 to d291d3b Compare July 6, 2026 12:36

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

buenaflor mentioned this pull request Jul 6, 2026

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

Open

6 tasks

buenaflor force-pushed the buenaflor/docs/dart-span-streaming-config branch from d291d3b to ad6539b 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

Comment thread docs/platforms/dart/common/configuration/filtering.mdx Outdated

inventarSarah reviewed Jul 9, 2026

View reviewed changes

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

inventarSarah force-pushed the buenaflor/docs/dart-span-streaming-new-spans branch from 47f4b17 to e3ee6bc Compare July 9, 2026 11:17

buenaflor and others added 8 commits July 9, 2026 13:32

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

112b590

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

docs(dart): Correct SentrySpanStatusV2 possible values

f92f5bc

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

d70c65a

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

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

cac17b3

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 and others added 3 commits July 9, 2026 13:32

docs(dart): Bump span streaming option availableSince to 9.23.0

9bb982e

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

minor wording updates; changes to align with Python guides

da34ec1

inventarSarah force-pushed the buenaflor/docs/dart-span-streaming-config branch from bc30c88 to da34ec1 Compare July 9, 2026 11:32

inventarSarah marked this pull request as ready for review July 9, 2026 11:38

inventarSarah requested review from cleptric and sfanahata July 9, 2026 11:39

inventarSarah assigned inventarSarah and buenaflor Jul 9, 2026

delete unused folder

2f7ddbb

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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

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

docs(dart): Document stream mode in configuration pages#18609
buenaflor wants to merge 12 commits into
buenaflor/docs/dart-span-streaming-new-spansfrom
buenaflor/docs/dart-span-streaming-config

buenaflor commented Jul 1, 2026 •

edited

Loading

Uh oh!

vercel Bot commented Jul 1, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

inventarSarah Jul 7, 2026

Uh oh!

buenaflor Jul 7, 2026

Uh oh!

inventarSarah Jul 7, 2026

Uh oh!

Uh oh!

inventarSarah Jul 9, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants


		<Alert level="warning">

		Profiling isn't available in stream mode. It works only with the default transaction mode (`SentryTraceLifecycle.static`).


		You can also use <PlatformIdentifier name="before-send-transaction" /> (for transaction mode) or <PlatformIdentifier name="before-send-span" /> (for stream mode) to modify transaction/span data.

		### Using <PlatformIdentifier name="ignore-transactions" />

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!

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!

Uh oh!

inventarSarah Jul 9, 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