docs(dart): Document stream mode in integration guides by buenaflor · Pull Request #18610 · getsentry/sentry-docs

buenaflor · 2026-07-01T09:15:30Z

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.

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:15:37Z

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:37pm

1 Skipped Deployment

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

Copilot

Pull request overview

Adds a shared “stream mode” callout to Dart/Flutter tracing integration docs so readers understand how transaction references map in stream mode and where to learn more (New Spans).

Changes:

Added a reusable MDX include (includes/dart-stream-mode-general-callout.mdx) containing an <Alert> with stream mode guidance.
Inserted that include at the top of 14 Dart/Flutter integration include pages (plus the integrations index) that cover tracing-related behavior.

Reviewed changes

Copilot reviewed 15 out of 15 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
includes/dart-stream-mode-general-callout.mdx	New reusable alert explaining stream mode differences and linking to “New Spans”.
includes/dart-integrations/index.mdx	Adds the shared stream mode callout to the integrations index include.
includes/dart-integrations/app-start-instrumentation.mdx	Adds the shared stream mode callout near the top of the page.
includes/dart-integrations/asset-bundle-instrumentation.mdx	Adds the shared stream mode callout near the top of the page.
includes/dart-integrations/dio.mdx	Adds the shared stream mode callout near the top of the page.
includes/dart-integrations/drift-instrumentation.mdx	Adds the shared stream mode callout near the top of the page.
includes/dart-integrations/file.mdx	Adds the shared stream mode callout near the top of the page.
includes/dart-integrations/graphql.mdx	Adds the shared stream mode callout near the top of the page.
includes/dart-integrations/hive-instrumentation.mdx	Adds the shared stream mode callout near the top of the page.
includes/dart-integrations/http-integration.mdx	Adds the shared stream mode callout near the top of the page.
includes/dart-integrations/isar-instrumentation.mdx	Adds the shared stream mode callout near the top of the page.
includes/dart-integrations/routing-instrumentation.mdx	Adds the shared stream mode callout near the top of the page.
includes/dart-integrations/slow-and-frozen-frames-instrumentation.mdx	Adds the shared stream mode callout near the top of the page.
includes/dart-integrations/sqflite-instrumentation.mdx	Adds the shared stream mode callout near the top of the page.
includes/dart-integrations/user-interaction-instrumentation.mdx	Adds the shared stream mode callout near the top of the page.

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 a reusable stream mode callout and include it on the Dart and Flutter integration pages that document tracing. The callout clarifies that transaction references map to service spans in stream mode, that auto-instrumentation switches automatically, and that manual instrumentation uses Sentry.startSpan. Because the integration pages share these includes, one change covers both Dart and Flutter. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Mirror the Python integrations approach: keep the transaction-mode snippet and add an inline 'or, in stream mode: Sentry.startSpan(...)' comment next to each transaction/span creation. Co-Authored-By: Claude <noreply@anthropic.com>

Replace the one-line inline stream-mode hints with full dual-mode snippets on the auto-instrumentation includes. Each Verify example now shows a Transaction Mode (Default) tab alongside a Stream Mode tab that wraps the work in `Sentry.startSpan`, so auto-created spans attach to the active span. Behaviour notes now describe both modes. Asset bundle instrumentation still uses the legacy span API and produces no spans in stream mode, so its page keeps a transaction-only snippet with an explicit limitation note instead of a stream tab. Co-Authored-By: Claude <noreply@anthropic.com>

Address Copilot review nit: method names in prose should include parentheses for consistency with other SDK docs. Co-Authored-By: Claude <noreply@anthropic.com>

sentry · 2026-07-09T12:24:51Z

+```dart {tabTitle:Stream Mode}
+Map<String, dynamic>? sentryResponseDecoder(
+  http.Response response, {
+  Hub? hub,
+}) {
+  return Sentry.startSpanSync(
+    'serialize.http.client',
+    (span) => _defaultHttpResponseDecoder(response),
+  );


Bug: The sentryResponseDecoder Stream Mode example accepts a hub parameter but ignores it, using the global Sentry object instead.
_{Severity: LOW}

Suggested Fix

Modify the sentryResponseDecoder Stream Mode example to use the hub parameter when it's provided, similar to the Transaction Mode example. Specifically, replace Sentry.startSpanSync(...) with a call that utilizes the hub object, such as (hub ?? HubAdapter()).startSpanSync(...).

Prompt for AI Agent

Review the code at the location below. A potential bug has been identified by an AI agent. Verify if this is a real issue. If it is, propose a fix; if not, explain why it's not valid. Location: includes/dart-integrations/graphql.mdx#L418-L426 Potential issue: The code snippet for `sentryResponseDecoder` in Stream Mode defines a `Hub? hub` parameter, but its implementation uses `Sentry.startSpanSync(...)` instead of the provided hub. This means any custom hub passed to the function will be silently ignored. This is inconsistent with the Transaction Mode example, which correctly uses the `hub` parameter. Developers following this example and providing a custom hub, for instance during testing, will find their custom hub is not used.

_{Did we get this right? 👍 / 👎 to inform future reviews.}

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

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

Copilot AI reviewed Jul 1, 2026

View reviewed changes

Comment thread includes/dart-stream-mode-general-callout.mdx Outdated

Comment thread includes/dart-stream-mode-general-callout.mdx Outdated

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

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

buenaflor force-pushed the buenaflor/docs/dart-span-streaming-integrations branch from 3536199 to c69b7c1 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

buenaflor force-pushed the buenaflor/docs/dart-span-streaming-integrations branch from 64e79c2 to 8ec14ee Compare July 6, 2026 12:36

vercel Bot deployed to Preview – sentry-docs July 6, 2026 12:47 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 changed the title ~~docs(dart): Add stream mode callout to integration pages~~ docs(dart): Document stream mode in integration guides Jul 6, 2026

buenaflor force-pushed the buenaflor/docs/dart-span-streaming-integrations branch from 8ec14ee to 8e11d88 Compare July 6, 2026 13:43

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

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

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

vercel Bot deployed to Preview – sentry-docs July 8, 2026 08:25 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 11 commits July 9, 2026 13:33

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

4de3378

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

docs(dart): Correct SentrySpanStatusV2 possible values

544dec8

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

01e519e

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

2af0ee3

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>

docs(dart): Reference startSpan()/startSpanSync() with parens in prose

ce6b01b

Address Copilot review nit: method names in prose should include parentheses for consistency with other SDK docs. Co-Authored-By: Claude <noreply@anthropic.com>

update span page link; minor wording updates

6052a61

inventarSarah force-pushed the buenaflor/docs/dart-span-streaming-integrations branch from 7b53369 to 6052a61 Compare July 9, 2026 11:33

codeowner-assignment Bot requested a review from a team July 9, 2026 11:34

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

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

inventarSarah assigned inventarSarah and buenaflor Jul 9, 2026

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

delete unused folder

4b427cc

sentry Bot reviewed Jul 9, 2026

View reviewed changes

vercel Bot deployed to Preview – sentry-docs July 9, 2026 12:37 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 integration guides#18610

docs(dart): Document stream mode in integration guides#18610
buenaflor wants to merge 13 commits into
buenaflor/docs/dart-span-streaming-new-spansfrom
buenaflor/docs/dart-span-streaming-integrations

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!

Uh oh!

sentry Bot Jul 9, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

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!

sentry Bot Jul 9, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

buenaflor commented Jul 1, 2026 •

edited

Loading

vercel Bot commented Jul 1, 2026 •

edited

Loading