docs(dart): Document stream mode in integration guides

includes/dart-integrations/app-start-instrumentation.mdx

@@ -10,6 +10,8 @@ platforms:
   - flutter
 ---
 
+<Include name="dart-stream-mode-general-callout.mdx" />
+
 Sentry's app start instrumentation provides insight into how long your application takes to launch.
 
 <Alert>

includes/dart-integrations/asset-bundle-instrumentation.mdx

@@ -10,6 +10,12 @@ platforms:
   - flutter
 ---
 
+<Alert level="warning" title="Not available in stream mode">
+
+Asset bundle instrumentation isn't supported in <PlatformLink to="/tracing/streamed-spans/">stream mode</PlatformLink> yet — it creates spans only in the default transaction mode.
+
+</Alert>
+
 [AssetBundle](https://api.flutter.dev/flutter/services/AssetBundle-class.html) instrumentation provides insight into how long your app takes to load its assets, such as files.
 
 ## Instrumentation Behaviour

includes/dart-integrations/dio.mdx

@@ -7,6 +7,8 @@ platforms:
 sidebar_order: 4
 ---
 
+<Include name="dart-stream-mode-general-callout.mdx" />
+
 The `sentry_dio` library provides [Dio](https://pub.dev/packages/dio) support for Sentry using the [HttpClientAdapter](https://pub.dev/documentation/dio/latest/dio/HttpClientAdapter-class.html). It is able to collect breadcrumbs, run tracing for HTTP requests, and capture events for failed requests.
 
 ## Install
@@ -121,7 +123,7 @@ The Dio integration also provides insight into tracing for your HTTP requests do
 
 ### Instrumentation Behaviour
 
-- The created spans will be attached to the transaction on the scope - if no transaction is on the scope the span will not be sent to Sentry.
+- The created spans attach to the active span. In transaction mode, that's the transaction bound to the scope; in stream mode, it's the span started with `Sentry.startSpan()`. If no span is active, the span won't be sent to Sentry.
 - The SDK sets the span operation to `http.client` and the description to request `$METHOD $url`. For example, `GET https://sentry.io`.
 - The span finishes once the request has been executed.
 - The span status depends on either the HTTP response code or `SpanStatus.internalError()` if the code does not match any of Sentry's SpanStatus options.
@@ -150,7 +152,7 @@ dio.addSentry();
 
 #### 1. Execute the Code
 
-```dart
+```dart {tabTitle:Transaction Mode (Default)} {mdExpandTabs}
 import 'package:sentry_dio/sentry_dio.dart';
 
 Future<void> makeWebRequestWithDio() async {
@@ -181,6 +183,24 @@ Future<void> makeWebRequestWithDio() async {
 }
 ```
 
+```dart {tabTitle:Stream Mode}
+import 'package:sentry_dio/sentry_dio.dart';
+
+Future<void> makeWebRequestWithDio() async {
+  final dio = Dio();
+  dio.addSentry();
+
+  // Start a root span — the Dio integration attaches a span for the request
+  await Sentry.startSpan('dio-web-request', (span) async {
+    try {
+      final response = await dio.get<String>(exampleUrl);
+    } catch (exception, stackTrace) {
+      await Sentry.captureException(exception, stackTrace: stackTrace);
+    }
+  }, parentSpan: null);
+}
+```
+
 #### 2. View the Transaction on Sentry.io
 
 To view the recorded transaction, log into [sentry.io](https://sentry.io) and open your project.

includes/dart-integrations/drift-instrumentation.mdx

@@ -10,12 +10,14 @@ platforms:
   - flutter
 ---
 
+<Include name="dart-stream-mode-general-callout.mdx" />
+
 Drift is a library for easily managing SQLite databases within Flutter applications.
 The [sentry_drift](https://pub.dev/packages/sentry_drift) package provides `Drift` support for database performance instrumentation and allows you to track the performance of your queries.
 
 ## Instrumentation Behaviour
 
-The created spans will be attached to the transaction on the scope - if no transaction is on the scope the Drift span will not be sent to Sentry.
+The created spans attach to the active span. In transaction mode, that's the transaction bound to the scope; in stream mode, it's the span started with `Sentry.startSpan()`. If no span is active, the Drift span won't be sent to Sentry.
 
 ## Prerequisites
 
@@ -60,7 +62,7 @@ await database.runWithInterceptor(interceptor: interceptor, () async {
 
 ### 1. Execute the Code
 
-```dart
+```dart {tabTitle:Transaction Mode (Default)} {mdExpandTabs}
 import 'package:drift/drift.dart';
 import 'package:drift/native.dart';
 import 'package:sentry/sentry.dart';
@@ -93,6 +95,34 @@ Future<void> driftTest() async {
 }
 ```
 
+```dart {tabTitle:Stream Mode}
+import 'package:drift/drift.dart';
+import 'package:drift/native.dart';
+import 'package:sentry/sentry.dart';
+import 'package:sentry_drift/sentry_drift.dart';
+
+import 'your_database.dart';
+
+Future<void> driftTest() async {
+  await Sentry.startSpan('driftTest', (span) async {
+    final interceptor = SentryQueryInterceptor(databaseName: 'my_database_name');
+    final executor = inMemoryExecutor().interceptWith(interceptor);
+    final db = AppDatabase(executor);
+
+    await db.into(db.todoItems).insert(
+          TodoItemsCompanion.insert(
+            title: 'This is a test title',
+            content: 'test',
+          ),
+        );
+
+    final items = await db.select(db.todoItems).get();
+
+    await db.close();
+  }, parentSpan: null);
+}
+```
+
 ### 2. View the Transaction on Sentry.io
 
 To view the recorded transaction, log into [sentry.io](https://sentry.io) and open your project.

includes/dart-integrations/file.mdx

@@ -7,12 +7,14 @@ platforms:
   - flutter
 ---
 
+<Include name="dart-stream-mode-general-callout.mdx" />
+
 File I/O operations are fundamental for reading from and writing to files within an application.
 The `sentry_file` integration provides [File](https://api.dart.dev/stable/2.18.5/dart-io/File-class.html) support for Sentry thus providing insight into tracing of file operations.
 
 ## Behavior
 
-- The created spans will be attached to the transaction on the scope - if no transaction is on the scope the File I/O span will not be sent to Sentry.
+- The created spans attach to the active span. In transaction mode, that's the transaction bound to the scope; in stream mode, it's the span started with `Sentry.startSpan()`. If no span is active, the File I/O span won't be sent to Sentry.
 - The File I/O integration is only available for the `dart:io:File` class, not for the `dart:html:File` class.
 - The SDK sets the span `operation` to `file.copy`, `file.write`, `file.delete`, `file.open`, `file.read` or `file.rename`, and `description` to `filename` (for example, `file.txt`).
 - The span finishes once the operation has been executed. The span `status` is then set to `SpanStatus.ok` if successful, or `SpanStatus.internalError` if there was an error.
@@ -45,7 +47,7 @@ final sentryFile = file.sentryTrace();
 
 ### 1. Execute the Code
 
-```dart
+```dart {tabTitle:Transaction Mode (Default)} {mdExpandTabs}
 import 'package:sentry/sentry.dart';
 import 'package:sentry_file/sentry_file.dart';
 import 'dart:io';
@@ -92,6 +94,48 @@ Future<void> runApp() async {
 }
 ```
 
+```dart {tabTitle:Stream Mode}
+import 'package:sentry/sentry.dart';
+import 'package:sentry_file/sentry_file.dart';
+import 'dart:io';
+
+Future<void> main() async {
+  await Sentry.init(
+    (options) {
+      options.dsn = 'https://example@sentry.io/example';
+      // To set a uniform sample rate
+      options.tracesSampleRate = 1.0;
+      // Enables stream mode
+      options.traceLifecycle = SentryTraceLifecycle.stream;
+    },
+    appRunner: runApp, // Init your App.
+  );
+}
+
+Future<void> runApp() async {
+  final file = File('my_file.txt');
+  // Call the Sentry extension method to wrap up the File
+  final sentryFile = file.sentryTrace();
+
+  // Start a root span — file I/O spans attach to the active span
+  await Sentry.startSpan('MyFileExample', (span) async {
+    // create the File
+    await sentryFile.create();
+    // Write some content
+    await sentryFile.writeAsString('Hello World');
+    // Read the content
+    final text = await sentryFile.readAsString();
+
+    print(text);
+
+    // Delete the file
+    await sentryFile.delete();
+  }, parentSpan: null);
+
+  await Sentry.close();
+}
+```
+
 ### 2. View the Recorded Transaction on Sentry.io
 
 To view the recorded transaction, log into [sentry.io](https://sentry.io) and open your project.

includes/dart-integrations/graphql.mdx

@@ -7,6 +7,8 @@ platforms:
   - flutter
 ---
 
+<Include name="dart-stream-mode-general-callout.mdx" />
+
 The `sentry_link` integration adds Sentry instrumentation to GraphQL clients built on the [gql](https://pub.dev/packages/gql) ecosystem.
 
 It helps you capture:
@@ -78,15 +80,15 @@ For better error context and grouping, add the recommended init options from [Ad
 
 ## `SentryGql.link()` Options
 
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| `shouldStartTransaction` | `bool` | _required_ | Set to `true` to start a transaction per GraphQL operation when no active span/transaction exists. |
-| `graphQlErrorsMarkTransactionAsFailed` | `bool` | _required_ | Set to `true` to mark GraphQL spans/transactions as `unknownError` when `response.errors` exists. |
-| `enableBreadcrumbs` | `bool` | `true` | Records breadcrumbs for successful GraphQL operations. |
-| `reportExceptions` | `bool` | `true` | Captures `LinkException` failures as Sentry events. |
-| `reportExceptionsAsBreadcrumbs` | `bool` | `false` | Records `LinkException` failures as breadcrumbs instead of events. |
-| `reportGraphQlErrors` | `bool` | `true` | Captures GraphQL response errors as Sentry events. |
-| `reportGraphQlErrorsAsBreadcrumbs` | `bool` | `false` | Records GraphQL response errors as breadcrumbs instead of events. |
+| Parameter                              | Type   | Default    | Description                                                                                        |
+| -------------------------------------- | ------ | ---------- | -------------------------------------------------------------------------------------------------- |
+| `shouldStartTransaction`               | `bool` | _required_ | Set to `true` to start a transaction per GraphQL operation when no active span/transaction exists. |
+| `graphQlErrorsMarkTransactionAsFailed` | `bool` | _required_ | Set to `true` to mark GraphQL spans/transactions as `unknownError` when `response.errors` exists.  |
+| `enableBreadcrumbs`                    | `bool` | `true`     | Records breadcrumbs for successful GraphQL operations.                                             |
+| `reportExceptions`                     | `bool` | `true`     | Captures `LinkException` failures as Sentry events.                                                |
+| `reportExceptionsAsBreadcrumbs`        | `bool` | `false`    | Records `LinkException` failures as breadcrumbs instead of events.                                 |
+| `reportGraphQlErrors`                  | `bool` | `true`     | Captures GraphQL response errors as Sentry events.                                                 |
+| `reportGraphQlErrorsAsBreadcrumbs`     | `bool` | `false`    | Records GraphQL response errors as breadcrumbs instead of events.                                  |
 
 ## Error Reporting Layers
 
@@ -381,6 +383,14 @@ final link = Link.from([
   ),
 ]);
 
+Map<String, dynamic>? _defaultHttpResponseDecoder(http.Response response) {
+  return json.decode(utf8.decode(response.bodyBytes)) as Map<String, dynamic>?;
+}
+```
+
+The decoder itself creates the span. In transaction mode, it starts a child off the currently active transaction. In stream mode, `Sentry.startSpanSync()` is used instead, which attaches the new span to the currently active span automatically and sets its status based on whether the callback throws:
+
+```dart {tabTitle:Transaction Mode (Default)} {mdExpandTabs}
 Map<String, dynamic>? sentryResponseDecoder(
   http.Response response, {
   Hub? hub,
@@ -403,9 +413,17 @@ Map<String, dynamic>? sentryResponseDecoder(
   }
   return result;
 }
+```
 
-Map<String, dynamic>? _defaultHttpResponseDecoder(http.Response response) {
-  return json.decode(utf8.decode(response.bodyBytes)) as Map<String, dynamic>?;
+```dart {tabTitle:Stream Mode}
+Map<String, dynamic>? sentryResponseDecoder(
+  http.Response response, {
+  Hub? hub,
+}) {
+  return Sentry.startSpanSync(
+    'serialize.http.client',
+    (span) => _defaultHttpResponseDecoder(response),
+  );
 }
 ```
 

includes/dart-integrations/hive-instrumentation.mdx

@@ -10,6 +10,8 @@ platforms:
   - flutter
 ---
 
+<Include name="dart-stream-mode-general-callout.mdx" />
+
 <Include name="feature-stage-beta.mdx" />
 
 _(New in version 7.13.1)_
@@ -19,7 +21,7 @@ The [sentry_hive](https://pub.dev/packages/sentry_hive) package provides `Hive`
 
 ## Instrumentation Behaviour
 
-The created spans will be attached to the transaction on the scope - if no transaction is on the scope the Hive span will not be sent to Sentry.
+The created spans attach to the active span. In transaction mode, that's the transaction bound to the scope; in stream mode, it's the span started with `Sentry.startSpan()`. If no span is active, the Hive span won't be sent to Sentry.
 
 ## Prerequisites
 
@@ -55,7 +57,7 @@ SentryHive.init(appDir.path);
 
 ### 1. Execute the Code
 
-```dart
+```dart {tabTitle:Transaction Mode (Default)} {mdExpandTabs}
 import 'package:sentry_hive/sentry_hive.dart';
 
 Future<void> hiveTest() async {
@@ -80,6 +82,25 @@ Future<void> hiveTest() async {
 }
 ```
 
+```dart {tabTitle:Stream Mode}
+import 'package:sentry_hive/sentry_hive.dart';
+
+Future<void> hiveTest() async {
+  await Sentry.startSpan('hiveTest', (span) async {
+    final appDir = await getApplicationDocumentsDirectory();
+    SentryHive.init(appDir.path);
+
+    final catsBox = await SentryHive.openBox<Map>('cats');
+    await catsBox.put('fluffy', {'name': 'Fluffy', 'age': 4});
+    await catsBox.put('loki', {'name': 'Loki', 'age': 2});
+    await catsBox.clear();
+    await catsBox.close();
+
+    SentryHive.close();
+  }, parentSpan: null);
+}
+```
+
 ### 2. View the Transaction on Sentry.io
 
 To view the recorded transaction, log into [sentry.io](https://sentry.io) and open your project.

includes/dart-integrations/http-integration.mdx

@@ -7,6 +7,8 @@ platforms:
   - flutter
 ---
 
+<Include name="dart-stream-mode-general-callout.mdx" />
+
 ## Using the `SentryHttpClient` function
 
 You can use the `SentryHttpClient` and call its methods directly, or you can use it with the [`runWithClient`](https://pub.dev/documentation/http/latest/http/runWithClient.html) function. If you need to use a fresh instance of the `client` (so that other instances are not affected) or to run in a separate [`Zone`](https://api.dart.dev/stable/3.5.0/dart-async/Zone-class.html), which allows you to override the functionality of the existing [`Zone`](https://api.dart.dev/stable/3.5.0/dart-async/Zone-class.html), then use the `runWithClient` function (see the `runWithClient` tab). Otherwise, just use `SentryHttpClient` directly and call its methods (see the `default` tab).
@@ -184,9 +186,9 @@ Capturing transactions requires that you first <PlatformLink to="/tracing/">set
 
 </Alert>
 
-The `SentryHttpClient` starts a span out of the active span bound to the scope for each HTTP Request.
+The `SentryHttpClient` starts a span off the active span for each HTTP request. In transaction mode, that's the transaction bound to the scope; in stream mode, it's the span started with `Sentry.startSpan()`.
 
-```dart
+```dart {tabTitle:Transaction Mode (Default)} {mdExpandTabs}
 import 'package:sentry/sentry.dart';
 
 final transaction = Sentry.startTransaction(
@@ -206,3 +208,19 @@ try {
 
 await transaction.finish(status: SpanStatus.ok());
 ```
+
+```dart {tabTitle:Stream Mode}
+import 'package:sentry/sentry.dart';
+
+// Start a root span — a span is attached for each HTTP request
+await Sentry.startSpan('webrequest', (span) async {
+  var client = SentryHttpClient();
+  try {
+    var uriResponse = await client.post('https://example.com/whatsit/create',
+      body: {'name': 'doodle', 'color': 'blue'});
+    print(await client.get(uriResponse.bodyFields['uri']));
+  } finally {
+    client.close();
+  }
+}, parentSpan: null);
+```

includes/dart-integrations/index.mdx

@@ -1,3 +1,5 @@
+<Include name="dart-stream-mode-general-callout.mdx" />
+
 
 | **Integration**                                       | **Auto <br /> Enabled** | **Errors** | **Tracing** | **Additional <br /> Context** |
 | ----------------------------------------------------- | :--------------: | :--------: | :---------: | :--------------------: |