feat(sampling): add head-based session sampling support (#139)

## Description

Add head-based session sampling support to control what percentage of
sessions send telemetry data. The sampling decision is made once at SDK
initialization and remains consistent for the entire session. When a
session is not sampled, all telemetry is silently dropped with zero
processing overhead using the Null Object Pattern.

This aligns with Faro Web SDK sampling behavior.

## Related Issue(s)

Fixes #89

## 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)
- [x] 📝 Documentation
- [ ] 📈 Performance improvement
- [x] 🏗️ 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

## Screenshots (if applicable)

N/A

## Additional Notes

**Key changes:**
- **FaroConfig**: Added `samplingRate` parameter (0.0 to 1.0, default
1.0)
- **SessionSamplingProvider**: Handles one-time sampling decision at
init
- **RandomValueProvider**: Injectable randomness for testable sampling
logic
- **NoOpBatchTransport**: Null object pattern for unsampled sessions
(zero overhead)
- **BatchTransport**: Refactored with private fields, fixed timer
cancellation bug

**Testing:**
- Unit tests for SessionSamplingProvider, RandomValueProvider,
FaroConfig
- Unit tests for BatchTransport and NoOpBatchTransport
- Integration tests verifying end-to-end sampling behavior
- Manual testing with example app at different samplingRate values

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Medium Risk**
> Changes core telemetry initialization and transport selection, so
mis-sampling or factory singleton behavior could unintentionally drop
data across a session. Coverage is strong, but the new no-op path and
init-time decision affect all telemetry types.
> 
> **Overview**
> Adds head-based **session sampling** via new `FaroConfig.samplingRate`
(0.0–1.0, default 1.0), making a one-time sampling decision at SDK init
and routing all telemetry through a `NoOpBatchTransport` when unsampled
(plus a debug log explaining dropped telemetry).
> 
> Refactors `BatchTransport` internals (private fields/timer handling)
and updates `BatchTransportFactory` to select real vs no-op transport
based on `isSampled`, backed by new `SessionSamplingProvider` and
injectable `RandomValueProvider` for deterministic testing; updates
docs/CHANGELOG and adds unit + integration test coverage for sampling
and transport behavior.
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
9e1f88a. 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,6 +9,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- **Session sampling support**: New `samplingRate` configuration option allows controlling what percentage of sessions send telemetry data. This enables cost management and traffic reduction for high-volume applications. (Resolves #89)
+
+  - `samplingRate` accepts a value from `0.0` (no sessions sampled) to `1.0` (all sessions sampled, default)
+  - Sampling decision is made once per session at initialization and applies to all telemetry types (events, logs, exceptions, measurements, traces)
+  - A debug log is emitted when a session is not sampled (visible in debug builds only)
+  - Aligns with [Faro Web SDK sampling behavior](https://grafana.com/docs/grafana-cloud/monitor-applications/frontend-observability/instrument/sampling/)
+
 - **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)

doc/Configurations.md

@@ -499,6 +499,42 @@ Faro().runApp(
   - **Faro session** (`meta.session.attributes`): Values are stringified per Faro protocol requirements
   - **Span resources** (`resource.attributes`): Types are preserved (int, double, bool, String), enabling numeric queries and filtering in trace backends
 
+### Session Sampling
+
+Control what percentage of sessions send telemetry data. This is useful for managing costs and reducing traffic for high-volume applications.
+
+```dart
+Faro().runApp(
+  optionsConfiguration: FaroConfig(
+    // ...
+    samplingRate: 0.5, // Sample 50% of sessions (default: 1.0 = 100%)
+    // ...
+  ),
+  appRunner: () => runApp(const MyApp()),
+);
+```
+
+**How it works:**
+
+- The `samplingRate` value ranges from `0.0` (no sessions sampled) to `1.0` (all sessions sampled)
+- The sampling decision is made once per session at initialization time
+- When a session is not sampled, all telemetry (events, logs, exceptions, measurements, traces) is silently dropped
+- A debug log is emitted when a session is not sampled, for transparency during development
+
+**Example values:**
+
+| samplingRate | Behavior                                       |
+| ------------ | ---------------------------------------------- |
+| `1.0`        | All sessions sampled (default - send all data) |
+| `0.5`        | 50% of sessions sampled                        |
+| `0.1`        | 10% of sessions sampled                        |
+| `0.0`        | No sessions sampled (no data sent)             |
+
+**Notes:**
+
+- Sampling is head-based: the decision is made at SDK initialization and remains consistent for the entire session
+- This aligns with [Faro Web SDK sampling behavior](https://grafana.com/docs/grafana-cloud/monitor-applications/frontend-observability/instrument/sampling/)
+
 ### Data Collection Control
 
 Faro provides the ability to enable or disable data collection at runtime. This setting is automatically persisted across app restarts, so you don't need to set it every time your app starts.

example/lib/main.dart

@@ -41,6 +41,7 @@ void main() async {
       appEnv: 'Test',
       apiKey: faroApiKey,
       namespace: 'flutter_app',
+      samplingRate: 1.0,
       anrTracking: true,
       cpuUsageVitals: true,
       collectorUrl: faroCollectorUrl,

lib/src/configurations/faro_config.dart

@@ -25,10 +25,15 @@ class FaroConfig {
     this.sessionAttributes,
     this.initialUser,
     this.persistUser = true,
+    this.samplingRate = 1.0,
   })  : assert(appName.isNotEmpty, 'appName cannot be empty'),
         assert(appEnv.isNotEmpty, 'appEnv cannot be empty'),
         assert(apiKey.isNotEmpty, 'apiKey cannot be empty'),
         assert(maxBufferLimit > 0, 'maxBufferLimit must be greater than 0'),
+        assert(
+          samplingRate >= 0.0 && samplingRate <= 1.0,
+          'samplingRate must be between 0.0 and 1.0',
+        ),
         batchConfig = batchConfig ?? BatchConfig();
   final String appName;
   final String appEnv;
@@ -76,4 +81,18 @@ class FaroConfig {
   ///
   /// Set to `false` to disable user persistence.
   final bool persistUser;
+
+  /// Session sampling rate (0.0 to 1.0, default: 1.0 = 100%).
+  ///
+  /// Controls the probability that a session will be sampled. When a session
+  /// is not sampled, no telemetry (events, logs, exceptions, measurements,
+  /// traces) is sent for that session.
+  ///
+  /// Examples:
+  /// - `1.0` (default): 100% of sessions are sampled (all telemetry sent)
+  /// - `0.5`: 50% of sessions are sampled
+  /// - `0.0`: 0% of sessions are sampled (no telemetry sent)
+  ///
+  /// The sampling decision is made once per session at initialization time.
+  final double samplingRate;
 }

lib/src/faro.dart

@@ -16,6 +16,7 @@ import 'package:faro/src/integrations/on_error_integration.dart';
 import 'package:faro/src/models/models.dart';
 import 'package:faro/src/native_platform_interaction/faro_native_methods.dart';
 import 'package:faro/src/session/session_id_provider.dart';
+import 'package:faro/src/session/session_sampling_provider.dart';
 import 'package:faro/src/tracing/faro_tracer.dart';
 import 'package:faro/src/tracing/span.dart';
 import 'package:faro/src/transport/batch_transport.dart';
@@ -129,10 +130,23 @@ class Faro {
       persistUser: optionsConfiguration.persistUser,
     );
 
+    // Make sampling decision (once per session)
+    final isSampled = SessionSamplingProviderFactory()
+        .create(samplingRate: optionsConfiguration.samplingRate)
+        .isSampled;
+
+    if (!isSampled) {
+      log(
+        'Faro: Session not sampled (samplingRate: '
+        '${optionsConfiguration.samplingRate}). Telemetry will be dropped.',
+      );
+    }
+
     _batchTransport = BatchTransportFactory().create(
       initialPayload: Payload(meta),
       batchConfig: config?.batchConfig ?? BatchConfig(),
       transports: _transports,
+      isSampled: isSampled,
     );
 
     if (config?.transports == null) {

lib/src/session/session_sampling_provider.dart

@@ -0,0 +1,57 @@
+import 'package:faro/src/util/random_value_provider.dart';
+import 'package:flutter/foundation.dart';
+
+/// Determines if a session should be sampled.
+///
+/// The sampling decision is made once at construction time and is immutable.
+/// This ensures consistent behavior throughout the session lifecycle.
+class SessionSamplingProvider {
+  /// Creates a sampling provider with the given [samplingRate].
+  ///
+  /// The [samplingRate] is clamped to the valid range [0.0, 1.0] to ensure
+  /// safe behavior even if an invalid value is provided in production builds
+  /// (where assert statements are not checked).
+  SessionSamplingProvider({
+    required double samplingRate,
+    required RandomValueProvider randomValueProvider,
+  }) : isSampled =
+            randomValueProvider.nextDouble() < samplingRate.clamp(0.0, 1.0);
+
+  /// Whether this session is sampled.
+  ///
+  /// When `true`, telemetry data will be sent for this session.
+  /// When `false`, telemetry data will be dropped.
+  final bool isSampled;
+}
+
+/// Factory for creating [SessionSamplingProvider] instances.
+///
+/// Uses singleton pattern to ensure the sampling decision is made only once
+/// per session and remains consistent.
+class SessionSamplingProviderFactory {
+  static SessionSamplingProvider? _instance;
+
+  /// Creates or returns the singleton [SessionSamplingProvider] instance.
+  ///
+  /// The [samplingRate] is only used when creating the first instance.
+  /// Subsequent calls return the cached instance regardless of the provided
+  /// [samplingRate].
+  ///
+  /// If [randomValueProvider] is not provided, uses the default from
+  /// [RandomValueProviderFactory].
+  SessionSamplingProvider create({
+    required double samplingRate,
+    RandomValueProvider? randomValueProvider,
+  }) {
+    _instance ??= SessionSamplingProvider(
+      samplingRate: samplingRate,
+      randomValueProvider:
+          randomValueProvider ?? RandomValueProviderFactory().create(),
+    );
+    return _instance!;
+  }
+
+  /// Resets the singleton instance. Primarily for testing purposes.
+  @visibleForTesting
+  void reset() => _instance = null;
+}

lib/src/transport/batch_transport.dart

@@ -6,58 +6,63 @@ import 'package:faro/src/configurations/batch_config.dart';
 import 'package:faro/src/models/models.dart';
 import 'package:faro/src/models/span_record.dart';
 import 'package:faro/src/transport/faro_base_transport.dart';
+import 'package:faro/src/transport/no_op_batch_transport.dart';
 import 'package:faro/src/util/payload_extension.dart';
 import 'package:flutter/foundation.dart';
 
+/// Transport that batches telemetry data and sends it periodically.
 class BatchTransport {
-  BatchTransport(
-      {required this.payload,
-      required this.batchConfig,
-      required this.transports}) {
-    if (batchConfig.enabled) {
-      Timer.periodic(batchConfig.sendTimeout, (t) {
-        flushTimer = t;
-        flush(payload);
+  BatchTransport({
+    required Payload payload,
+    required BatchConfig batchConfig,
+    required List<BaseTransport> transports,
+  })  : _payload = payload,
+        _batchConfig = batchConfig,
+        _transports = transports {
+    if (_batchConfig.enabled) {
+      _flushTimer = Timer.periodic(_batchConfig.sendTimeout, (_) {
+        flush(_payload);
         resetPayload();
       });
     } else {
-      batchConfig.payloadItemLimit = 1;
+      _batchConfig.payloadItemLimit = 1;
     }
   }
-  Payload payload;
-  BatchConfig batchConfig;
-  List<BaseTransport> transports;
-  Timer? flushTimer;
+
+  final Payload _payload;
+  final BatchConfig _batchConfig;
+  final List<BaseTransport> _transports;
+  Timer? _flushTimer;
 
   void addEvent(Event event) {
-    payload.events.add(event);
+    _payload.events.add(event);
     checkPayloadItemLimit();
   }
 
   void addMeasurement(Measurement measurement) {
-    payload.measurements.add(measurement);
+    _payload.measurements.add(measurement);
     checkPayloadItemLimit();
   }
 
   void addLog(FaroLog faroLog) {
-    payload.logs.add(faroLog);
+    _payload.logs.add(faroLog);
     checkPayloadItemLimit();
   }
 
   void addSpan(SpanRecord spanRecord) {
-    payload.traces.addSpan(spanRecord);
+    _payload.traces.addSpan(spanRecord);
     checkPayloadItemLimit();
   }
 
   void addExceptions(FaroException exception) {
-    payload.exceptions.add(exception);
+    _payload.exceptions.add(exception);
     checkPayloadItemLimit();
   }
 
   void updatePayloadMeta(Meta meta) {
-    flush(payload);
+    flush(_payload);
     resetPayload();
-    payload.meta = meta;
+    _payload.meta = meta;
   }
 
   Future<void> flush(Payload payload) async {
@@ -69,43 +74,43 @@ class BatchTransport {
       return;
     }
 
-    if (transports.isNotEmpty) {
-      final currentTransports = transports;
+    if (_transports.isNotEmpty) {
+      final currentTransports = _transports;
       for (final transport in currentTransports) {
         await transport.send(payloadJson);
       }
     }
   }
 
   void checkPayloadItemLimit() {
-    if (payloadSize() >= batchConfig.payloadItemLimit) {
-      flush(payload);
+    if (payloadSize() >= _batchConfig.payloadItemLimit) {
+      flush(_payload);
       resetPayload();
     }
   }
 
   void dispose() {
-    flushTimer?.cancel();
+    _flushTimer?.cancel();
   }
 
   bool isPayloadEmpty() {
-    return payload.isEmpty();
+    return _payload.isEmpty();
   }
 
   int payloadSize() {
-    return payload.logs.length +
-        payload.measurements.length +
-        payload.events.length +
-        payload.exceptions.length +
-        payload.traces.numberSpans();
+    return _payload.logs.length +
+        _payload.measurements.length +
+        _payload.events.length +
+        _payload.exceptions.length +
+        _payload.traces.numberSpans();
   }
 
   void resetPayload() {
-    payload.events = [];
-    payload.measurements = [];
-    payload.logs = [];
-    payload.exceptions = [];
-    payload.traces.resetSpans();
+    _payload.events = [];
+    _payload.measurements = [];
+    _payload.logs = [];
+    _payload.exceptions = [];
+    _payload.traces.resetSpans();
   }
 }
 
@@ -118,15 +123,22 @@ class BatchTransportFactory {
     required Payload initialPayload,
     required BatchConfig batchConfig,
     required List<BaseTransport> transports,
+    required bool isSampled,
   }) {
     if (_instance != null) {
       return _instance!;
     }
 
-    final instance = BatchTransport(
+    final BatchTransport instance;
+    if (isSampled) {
+      instance = BatchTransport(
         payload: initialPayload,
         batchConfig: batchConfig,
-        transports: transports);
+        transports: transports,
+      );
+    } else {
+      instance = NoOpBatchTransport();
+    }
 
     _instance = instance;
     return instance;