feat(tracing): add ContextScope for span context lifetime control (#138)

## Description

Add `ContextScope` parameter to `startSpan()` that controls how long a
span remains active in zone context for automatic parent assignment.

- **`ContextScope.callback` (default)**: Span is deactivated when
callback completes. Timer/stream callbacks firing after the callback
ends will start fresh, independent traces.
- **`ContextScope.zone`**: Span stays active for the entire zone
lifetime, allowing timer callbacks to inherit the parent span.

This provides explicit control over timer callback behavior, fixing the
issue where spans that had ended remained active in zone context causing
unexpected parent-child relationships.

## Related Issue(s)

Fixes #105

## Type of Change

- [ ] 🛠️ Bug fix (non-breaking change which fixes an issue)
- [x] 🚀 New feature (non-breaking change which adds functionality)
- [ ] 💥 Breaking change (fix or feature that would cause existing
functionality to not work as expected)
- [ ] 📝 Documentation
- [ ] 📈 Performance improvement
- [ ] 🏗️ Code refactoring
- [ ] 🧹 Chore / Housekeeping

## Checklist

- [x] I have made corresponding changes to the documentation
- [x] I have added tests that prove my fix is effective or that my
feature works
- [x] I have updated the CHANGELOG.md under the "Unreleased" section

## Additional Notes

### Implementation Details
- `SpanContextHolder` wrapper class tracks span + context scope + active
state
- `ContextScope` enum defined in `span.dart` with `callback` and `zone`
values
- `FaroZoneSpanManager.executeWithSpan()` conditionally deactivates the
holder based on scope
- Public API updated in `Faro.startSpan()` and `FaroTracer.startSpan()`

### Example App
Added "Context Scope" demo button in the tracing feature to test and
demonstrate both `ContextScope` values with timer callbacks.

### Documentation
Consolidated timer/async callback documentation in `doc/Features.md`
under "Timer & Async Callback Behavior" section.

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Medium Risk**
> Changes zone-based span context propagation semantics and adds a new
public parameter to `startSpan()`, which could alter parent/child
relationships for async callbacks (timers/streams) in existing
integrations.
> 
> **Overview**
> Adds a new `contextScope` parameter to
`Faro().startSpan()`/`FaroTracer.startSpan()` to control how long a span
remains the active parent in zone context (`callback` default vs `zone`
for long-lived async work).
> 
> Refactors zone propagation to store a `SpanContextHolder` in zone
values and conditionally deactivate it after the callback, so
timer/stream callbacks firing later don’t accidentally inherit an ended
span unless explicitly requested.
> 
> Updates docs/CHANGELOG and the example tracing UI to demonstrate the
new behavior, and expands unit/integration tests around context scoping
and real timer behavior.
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
4453420. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: robert-northmind

CHANGELOG.md

@@ -9,7 +9,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
-- **Span.noParent sentinel**: New `Span.noParent` static constant allows explicitly starting a span with no parent, ignoring the active span in zone context. Useful for timer callbacks or event-driven scenarios where the original parent span may have ended but remains in zone context. (Resolves #105)
+- **ContextScope for span context lifetime control**: New `contextScope` parameter on `startSpan()` controls how long a span remains active in zone context for auto-assignment. `ContextScope.callback` (default) deactivates the span when the callback completes, preventing timer/stream callbacks from inheriting it. `ContextScope.zone` keeps the span active for the entire zone lifetime, useful when you want timer callbacks to be children of the parent span. (Resolves #105)
+
+- **Span.noParent sentinel**: New `Span.noParent` static constant allows explicitly starting a span with no parent, ignoring the active span in zone context. Useful for timer callbacks or event-driven scenarios where you want to start a fresh, independent trace. (Resolves #105)
 
 ### Fixed
 
@@ -34,18 +36,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 
 - **User management with FaroUser model**: New `FaroUser` class for comprehensive user identification
+
   - Replaces the legacy `User` model with a more feature-rich implementation
   - Supports `id`, `username`, `email`, and custom `attributes` fields
   - Custom attributes align with [Faro Web SDK MetaUser](https://grafana.com/docs/grafana-cloud/monitor-applications/frontend-observability/architecture/metas/#how-to-use-the-user-meta) for cross-platform consistency
   - Includes `FaroUser.cleared()` constructor to explicitly clear user data
 
 - **User persistence**: New `persistUser` option in `FaroConfig` (default: `true`)
+
   - Automatically saves user identity to device storage
   - Restores user on subsequent app launches for consistent session tracking
   - Early events like `appStart` include user data when persistence is enabled
   - Fires `user_set` event on restore and `user_updated` event on changes
 
 - **Initial user configuration**: New `initialUser` option in `FaroConfig`
+
   - Set a user immediately on SDK initialization
   - Use `FaroUser.cleared()` to explicitly clear any persisted user on start
   - Useful for apps that know the user at startup or need to force logout state
@@ -117,6 +122,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Fixed
 
 - **SDK name consistency across telemetry types**: Updated SDK identification to use consistent naming
+
   - Changed hardcoded 'rum-flutter' SDK name to use `FaroConstants.sdkName` for consistency with OpenTelemetry traces
   - Maintains backend-compatible version '1.3.5' for proper web SDK version validation
   - Added actual Faro Flutter SDK version to session attributes as 'faro_sdk_version' for tracking real SDK version
@@ -133,7 +139,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Changed
 
 - **BREAKING: Package structure refactoring to follow Flutter plugin conventions**: Reorganized the package to align with Flutter/Dart ecosystem standards and best practices
+
   - **Breaking Change**: Main entry point changed from `faro_sdk.dart` to `faro.dart`
+
     - The package now follows the standard `lib/<package_name>.dart` convention
     - Removed `lib/faro_sdk.dart` file entirely
     - `lib/faro.dart` is now the single main entry point with selective barrel exports
@@ -149,13 +157,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
     ```
 
   - **Architecture Improvements**:
+
     - Moved core `Faro` class implementation from `lib/faro.dart` to `lib/src/faro.dart`
     - `lib/faro.dart` now serves as a clean barrel export file exposing only public APIs
     - All implementation details properly organized under `lib/src/` directory
     - Clear separation between public API surface and private implementation
     - Follows established Flutter ecosystem conventions used by popular packages like Provider, BLoC, and Dio
 
   - **Benefits**:
+
     - **Cleaner API boundaries**: Clear distinction between public and private APIs
     - **Better maintainability**: Implementation details can evolve without affecting public interface
     - **Consistent developer experience**: Matches patterns developers expect from other Flutter packages
@@ -167,11 +177,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 
 - **Type-Safe Log Level API**: New `LogLevel` enum for improved logging reliability and developer experience
+
   - Introduced `LogLevel` enum with values: `trace`, `debug`, `info`, `log`, `warn`, `error`
   - Aligns with Grafana Faro Web SDK for cross-platform consistency
   - Includes `fromString()` method for backward compatibility, supporting both `'warn'` and `'warning'` variants
 
 - **Enhanced Tracing and Span API**: Major improvements to distributed tracing capabilities
+
   - New `startSpan<T>()` method for automatic span lifecycle management with callback-based execution
   - New `startSpanManual()` method for manual span lifecycle management when precise control is needed
   - New `getActiveSpan()` method to access the currently active span from anywhere in the execution context
@@ -183,15 +195,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - Comprehensive documentation with detailed examples for common tracing patterns
 
 - **Centralized Session Management**: New `SessionIdProvider` for consistent session handling across the SDK
+
   - Dedicated session ID generation and management
   - Better integration with tracing system for session context propagation
   - Factory pattern for testable session management
 
 - **SDK Constants Management**: New centralized constants system
+
   - Added `FaroConstants` class for SDK version and name management
   - Better version tracking and consistency across the codebase
 
 - **BREAKING: Synchronous API for telemetry methods**: Refactored telemetry methods to remove unnecessary async patterns for improved performance and developer experience
+
   - **Breaking Change**: The following methods changed from `Future<void>?` to `void`:
     - `pushEvent()` - Send custom events
     - `pushLog()` - Send custom logs
@@ -217,13 +232,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - **Internal Architecture**: Introduced `BatchTransportFactory` singleton pattern for better dependency management and testing
 
 - **BREAKING: pushLog API requires LogLevel enum**: Enhanced logging API for better type safety and consistency
+
   - **Breaking Change**: `pushLog()` now requires a `LogLevel` parameter instead of optional `String?`
   - **Migration**: Replace `level: "warn"` with `level: LogLevel.warn` in your pushLog calls
   - **Benefit**: Eliminates typos in log levels and provides better IDE support
   - **Compatibility**: Existing string-based log levels in internal code updated to use LogLevel enum
   - **Documentation**: All examples and documentation updated to reflect the new API
 
 - **Tracing Architecture Refactoring**: Complete redesign of the internal tracing system
+
   - Replaced legacy `tracer.dart` and `tracer_provider.dart` with new `FaroTracer` implementation
   - New `FaroZoneSpanManager` for robust zone-based span context management
   - Improved `Span` class with cleaner API and better OpenTelemetry integration

doc/Features.md

@@ -286,30 +286,69 @@ await Faro().startSpan('main_operation', (span) async {
 });
 ```
 
-### 🔓 Starting Independent Traces
+### 🕐 Timer & Async Callback Behavior
 
-In some scenarios (like timer callbacks or event-driven architectures), you may want to start a new trace without inheriting from the active span in the zone context. Use `Span.noParent` for this:
+When using `startSpan()`, you have control over how timer and stream callbacks relate to the parent span. The `contextScope` parameter determines this behavior.
+
+#### Default: Timer Callbacks Start New Traces
+
+By default (`ContextScope.callback`), spans are deactivated from context when the callback completes. Timer or stream callbacks that fire _after_ the callback has completed will start their own independent traces:
 
 ```dart
-// Inside a callback where the original parent span may have ended
 await Faro().startSpan('parent-operation', (parentSpan) async {
-  // Set up a periodic timer
+  // This timer fires after the callback completes (30s > doMainWork duration)
   Timer.periodic(Duration(seconds: 30), (_) {
-    // Without Span.noParent, this would inherit the (possibly ended) parent span
-    // Use Span.noParent to start a fresh, independent trace
-    Faro().startSpan('periodic-check', parentSpan: Span.noParent, (span) async {
+    // Starts a NEW trace because parent was deactivated when callback ended
+    Faro().startSpan('periodic-check', (span) async {
       await performHealthCheck();
     });
   });
 
-  await doMainWork();
-});
+  await doMainWork(); // Takes less than 30 seconds
+}); // Parent span deactivated here
 ```
 
-The `parentSpan` parameter supports three states:
-- **Not provided / null**: Uses the active span from zone context (default behavior)
-- **`Span.noParent`**: Explicitly starts a new root trace with no parent
-- **Specific `Span` instance**: Uses that span as the parent
+#### Keeping Span Active for Timer Callbacks
+
+If you want timer callbacks to inherit the parent span (same trace), use `ContextScope.zone`:
+
+```dart
+await Faro().startSpan('long-running-operation', (parentSpan) async {
+  // Timer callbacks WILL be children of this span
+  Timer.periodic(Duration(seconds: 5), (_) {
+    Faro().startSpan('progress-update', (span) async {
+      await reportProgress(); // Same traceId as parent
+    });
+  });
+
+  await doWork();
+}, contextScope: ContextScope.zone); // Span stays active for zone lifetime
+```
+
+#### Explicit New Trace with Span.noParent
+
+For explicit control, use `Span.noParent` to start a fresh trace regardless of context:
+
+```dart
+// Useful inside zone-scoped spans or manual spans
+Faro().startSpan('independent-operation', (span) async {
+  await doSomething();
+}, parentSpan: Span.noParent); // Always starts new trace
+```
+
+#### Summary
+
+| Scenario                          | Result                            |
+| --------------------------------- | --------------------------------- |
+| Default (`ContextScope.callback`) | Timer callbacks → new trace       |
+| `ContextScope.zone`               | Timer callbacks → child of parent |
+| `parentSpan: Span.noParent`       | Always new trace (explicit)       |
+
+The `parentSpan` parameter supports three values:
+
+- **Not provided / null**: Uses active span from zone context
+- **`Span.noParent`**: Explicitly starts a new root trace
+- **Specific `Span` instance**: Uses that span as parent
 
 ### 🔄 Span Features
 

example/lib/features/tracing/domain/tracing_service.dart

@@ -1,3 +1,4 @@
+import 'dart:async';
 import 'dart:math';
 
 import 'package:faro/faro.dart';
@@ -272,6 +273,106 @@ class TracingService {
       log('Error: $error', isError: true);
     }
   }
+
+  /// Demonstrates ContextScope for controlling span context lifetime.
+  ///
+  /// Shows the difference between ContextScope.callback (default) and
+  /// ContextScope.zone for timer/async operations.
+  Future<void> runContextScopeDemo(LogCallback log) async {
+    log('Starting ContextScope demo...');
+    log('');
+    log('ContextScope controls whether timer callbacks inherit the parent span.');
+    log('');
+
+    try {
+      // Demo 1: Default behavior (ContextScope.callback)
+      log('--- Demo 1: ContextScope.callback (default) ---');
+      log('Timer callbacks will NOT inherit the parent span.');
+
+      String? parentTraceId1;
+      String? timerSpanTraceId1;
+      final completer1 = Completer<void>();
+
+      await Faro().startSpan<void>(
+        'parent-callback-scope',
+        (parentSpan) async {
+          parentTraceId1 = parentSpan.traceId;
+          log('Parent span started (traceId: ${parentSpan.traceId.substring(0, 8)}...)');
+
+          // Schedule a timer that fires after parent callback ends
+          Timer(const Duration(milliseconds: 100), () async {
+            await Faro().startSpan<void>(
+              'timer-child-callback',
+              (timerSpan) async {
+                timerSpanTraceId1 = timerSpan.traceId;
+                log('  Timer span (traceId: ${timerSpan.traceId.substring(0, 8)}...)');
+              },
+            );
+            completer1.complete();
+          });
+
+          await Future.delayed(const Duration(milliseconds: 50));
+          log('Parent callback ending...');
+        },
+        // contextScope: ContextScope.callback, // This is the default
+      );
+
+      await completer1.future;
+      if (timerSpanTraceId1 != parentTraceId1) {
+        log('Result: Timer span has DIFFERENT traceId = new trace');
+      } else {
+        log('Result: Timer span has SAME traceId (unexpected)');
+      }
+      log('');
+
+      // Demo 2: Zone scope (ContextScope.zone)
+      log('--- Demo 2: ContextScope.zone ---');
+      log('Timer callbacks WILL inherit the parent span.');
+
+      String? parentTraceId;
+      String? timerSpanTraceId2;
+      final completer2 = Completer<void>();
+
+      await Faro().startSpan<void>(
+        'parent-zone-scope',
+        (parentSpan) async {
+          parentTraceId = parentSpan.traceId;
+          log('Parent span started (traceId: ${parentSpan.traceId.substring(0, 8)}...)');
+
+          // Schedule a timer that fires after parent callback ends
+          Timer(const Duration(milliseconds: 100), () async {
+            await Faro().startSpan<void>(
+              'timer-child-zone',
+              (timerSpan) async {
+                timerSpanTraceId2 = timerSpan.traceId;
+                log('  Timer span (traceId: ${timerSpan.traceId.substring(0, 8)}...)');
+              },
+            );
+            completer2.complete();
+          });
+
+          await Future.delayed(const Duration(milliseconds: 50));
+          log('Parent callback ending...');
+        },
+        contextScope: ContextScope.zone, // Keep span active for timer
+      );
+
+      await completer2.future;
+
+      if (timerSpanTraceId2 == parentTraceId) {
+        log('Result: Timer span has SAME traceId = child of parent!');
+      } else {
+        log('Result: Timer span traceId differs (unexpected)');
+      }
+
+      log('');
+      log('ContextScope demo completed!');
+      log('Use ContextScope.zone when you want timer/stream callbacks');
+      log('to be children of the parent span.');
+    } catch (error) {
+      log('Error: $error', isError: true);
+    }
+  }
 }
 
 // =============================================================================

example/lib/features/tracing/presentation/tracing_page.dart

@@ -117,6 +117,12 @@ class _ButtonsSection extends StatelessWidget {
                 onPressed: actions.runSpanWithNoParent,
                 isRunning: uiState.isRunning,
               ),
+              _SpanButton(
+                label: 'Context Scope',
+                icon: Icons.timer,
+                onPressed: actions.runContextScopeDemo,
+                isRunning: uiState.isRunning,
+              ),
             ],
           ),
         ],

example/lib/features/tracing/presentation/tracing_page_view_model.dart

@@ -70,6 +70,9 @@ abstract interface class TracingPageActions {
 
   /// Demonstrates Span.noParent for independent traces.
   Future<void> runSpanWithNoParent();
+
+  /// Demonstrates ContextScope for controlling span context lifetime.
+  Future<void> runContextScopeDemo();
 }
 
 // =============================================================================
@@ -183,6 +186,11 @@ class _TracingPageViewModel extends Notifier<TracingPageUiState>
   Future<void> runSpanWithNoParent() async {
     await _runSpanOperation(_tracingService.runSpanWithNoParent);
   }
+
+  @override
+  Future<void> runContextScopeDemo() async {
+    await _runSpanOperation(_tracingService.runContextScopeDemo);
+  }
 }
 
 // =============================================================================