grafana
diff --git a/‎CHANGELOG.md‎
Lines changed: 5 additions & 19 deletions b/‎CHANGELOG.md‎
Lines changed: 5 additions & 19 deletions
diff --git a/‎doc/Configurations.md‎
Lines changed: 62 additions & 9 deletions b/‎doc/Configurations.md‎
Lines changed: 62 additions & 9 deletions
diff --git a/‎example/lib/features/sampling_settings/domain/sampling_settings_service.dart‎
Lines changed: 142 additions & 0 deletions b/‎example/lib/features/sampling_settings/domain/sampling_settings_service.dart‎
Lines changed: 142 additions & 0 deletions
@@ -9,11 +9,12 @@ 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)
+- **Session sampling support**: New `sampling` configuration option allows controlling what percentage of sessions send telemetry data. This enables cost management and traffic reduction for high-volume applications. (Resolves #89)
+  - Use `SamplingRate(0.5)` for fixed 50% sampling
+  - Use `SamplingFunction((context) => ...)` for dynamic sampling based on session context (user attributes, app environment, etc.)
+  - If not provided, all sessions are sampled (100%)
   - 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)
+  - Example: `sampling: SamplingFunction((context) => context.meta.user?.attributes?['role'] == 'beta' ? 1.0 : 0.1)`
   - 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)
@@ -43,21 +44,18 @@ 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
@@ -129,7 +127,6 @@ 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
@@ -146,9 +143,7 @@ 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
@@ -164,15 +159,13 @@ 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
@@ -184,13 +177,11 @@ 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
@@ -202,18 +193,15 @@ 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
@@ -239,15 +227,13 @@ 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
 
@@ -503,38 +503,91 @@ Faro().runApp(
 
 Control what percentage of sessions send telemetry data. This is useful for managing costs and reducing traffic for high-volume applications.
 
+#### Fixed Sampling Rate
+
+Use `SamplingRate` for a constant sampling probability:
+
 ```dart
 Faro().runApp(
   optionsConfiguration: FaroConfig(
     // ...
-    samplingRate: 0.5, // Sample 50% of sessions (default: 1.0 = 100%)
+    sampling: SamplingRate(0.5), // Sample 50% of sessions (default: 100% if omitted)
     // ...
   ),
   appRunner: () => runApp(const MyApp()),
 );
 ```
 
+**Example values:**
+
+| Sampling            | Behavior                                       |
+| ------------------- | ---------------------------------------------- |
+| Not provided        | All sessions sampled (default - send all data) |
+| `SamplingRate(1.0)` | All sessions sampled (100%)                    |
+| `SamplingRate(0.5)` | 50% of sessions sampled                        |
+| `SamplingRate(0.1)` | 10% of sessions sampled                        |
+| `SamplingRate(0.0)` | No sessions sampled (no data sent)             |
+
+#### Dynamic Sampling
+
+Use `SamplingFunction` for dynamic sampling decisions based on session context such as user attributes, app environment, or session metadata:
+
+```dart
+Faro().runApp(
+  optionsConfiguration: FaroConfig(
+    appName: 'MyApp',
+    appEnv: 'production',
+    apiKey: 'xxx',
+    collectorUrl: 'https://...',
+    sampling: SamplingFunction((context) {
+      // Sample all beta users
+      if (context.meta.user?.attributes?['role'] == 'beta') {
+        return 1.0;
+      }
+      // Sample 10% of production sessions
+      if (context.meta.app?.environment == 'production') {
+        return 0.1;
+      }
+      // Sample all in development
+      return 1.0;
+    }),
+  ),
+  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
+- Invalid return values (< 0.0 or > 1.0) are clamped to the valid range
 
-**Example values:**
+**Available context:**
 
-| 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)             |
+| Property           | Access Pattern                     | Description                              |
+| ------------------ | ---------------------------------- | ---------------------------------------- |
+| Session ID         | `context.meta.session?.id`         | Unique session identifier                |
+| Session attributes | `context.meta.session?.attributes` | Custom sessionAttributes from config     |
+| User ID            | `context.meta.user?.id`            | User ID (from initialUser or persisted)  |
+| User attributes    | `context.meta.user?.attributes`    | Custom user attributes                   |
+| App name           | `context.meta.app?.name`           | App name from config                     |
+| App environment    | `context.meta.app?.environment`    | App environment from config              |
+| App version        | `context.meta.app?.version`        | App version (from config or PackageInfo) |
+| SDK version        | `context.meta.sdk?.version`        | Faro SDK version                         |
 
 **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/)
 
+**Use cases:**
+
+- Sample all beta testers while sampling only 10% of regular users
+- Different sampling rates per environment (100% in dev, 10% in production)
+- A/B testing with different sampling for different user segments
+- Sampling based on custom session attributes (team, feature flags, etc.)
+
 ### 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.
 
@@ -0,0 +1,142 @@
+import 'package:faro/faro.dart';
+import 'package:flutter_riverpod/flutter_riverpod.dart';
+import 'package:shared_preferences/shared_preferences.dart';
+
+import '../models/sampling_setting.dart';
+
+/// Service for managing sampling settings.
+///
+/// Handles loading, saving, and querying sampling configuration
+/// that is passed to FaroConfig on app startup.
+class SamplingSettingsService {
+  SamplingSettingsService({required SharedPreferences prefs}) : _prefs = prefs;
+
+  final SharedPreferences _prefs;
+
+  static const String _samplingSettingKey = 'faro_sampling_setting';
+
+  // ===========================================================================
+  // Sampling Setting
+  // ===========================================================================
+
+  /// Gets the current sampling setting.
+  SamplingSetting get samplingSetting {
+    final storedName = _prefs.getString(_samplingSettingKey);
+    if (storedName == null) {
+      return SamplingSetting.all;
+    }
+    return SamplingSetting.values.firstWhere(
+      (e) => e.name == storedName,
+      orElse: () => SamplingSetting.all,
+    );
+  }
+
+  /// Gets the [Sampling] configuration for the current setting.
+  Sampling? get sampling => samplingSetting.sampling;
+
+  /// Sets the sampling setting.
+  Future<void> setSamplingSetting(SamplingSetting setting) async {
+    if (setting == SamplingSetting.all) {
+      await _prefs.remove(_samplingSettingKey);
+    } else {
+      await _prefs.setString(_samplingSettingKey, setting.name);
+    }
+  }
+
+  // ===========================================================================
+  // Current Session Info
+  // ===========================================================================
+
+  /// Gets whether the current session is sampled.
+  bool get isSessionSampled => Faro().isSampled;
+
+  /// Gets a display string for the current sampling config.
+  String getCurrentSamplingDisplay() {
+    final config = Faro().config;
+    if (config == null) return 'Not initialized';
+
+    final sampling = config.sampling;
+    if (sampling == null) {
+      return '100% (default)';
+    }
+    if (sampling is SamplingRate) {
+      final percent = (sampling.rate * 100).toStringAsFixed(0);
+      return 'SamplingRate($percent%)';
+    }
+    if (sampling is SamplingFunction) {
+      return 'SamplingFunction';
+    }
+    return 'Unknown';
+  }
+
+  /// Gets the current session's sampling setting.
+  ///
+  /// This attempts to match the current config's sampling to a known setting.
+  SamplingSetting? get currentSessionSamplingSetting {
+    final config = Faro().config;
+    if (config == null) return null;
+
+    final currentSampling = config.sampling;
+
+    // Match against known settings
+    for (final setting in SamplingSetting.values) {
+      if (_samplingMatches(currentSampling, setting)) {
+        return setting;
+      }
+    }
+
+    return null; // Unknown/custom sampling
+  }
+
+  /// Checks if the current config sampling matches a setting.
+  bool _samplingMatches(Sampling? sampling, SamplingSetting setting) {
+    if (sampling == null && setting == SamplingSetting.all) {
+      return true;
+    }
+    if (sampling is SamplingRate) {
+      switch (setting) {
+        case SamplingSetting.none:
+          return sampling.rate == 0.0;
+        case SamplingSetting.half:
+          return sampling.rate == 0.5;
+        case SamplingSetting.tenPercent:
+          return sampling.rate == 0.1;
+        default:
+          return false;
+      }
+    }
+    // For SamplingFunction, we can't easily compare, so check by setting type
+    if (sampling is SamplingFunction) {
+      return setting.isFunction;
+    }
+    return false;
+  }
+
+  /// Returns true if the saved setting differs from current session.
+  bool get needsRestart {
+    final current = currentSessionSamplingSetting;
+    if (current == null) return true; // Unknown config, restart to apply known
+    return samplingSetting != current;
+  }
+}
+
+// =============================================================================
+// Provider
+// =============================================================================
+
+/// Provider for SharedPreferences instance.
+///
+/// Must be overridden with the actual instance at app startup.
+final sharedPreferencesProvider = Provider<SharedPreferences>((ref) {
+  throw UnimplementedError(
+    'sharedPreferencesProvider must be overridden with the actual instance',
+  );
+});
+
+/// Provider for the sampling settings service.
+final samplingSettingsServiceProvider = Provider<SamplingSettingsService>(
+  (ref) {
+    final prefs = ref.watch(sharedPreferencesProvider);
+    return SamplingSettingsService(prefs: prefs);
+  },
+);