Ensure consistent sampleRand per trace (#3079)

* Implement sampleRand propagation for consistent trace sampling

Co-authored-by: giancarlo.buenaflor <[email protected]>

* Update

* Update CHANGELOG

* UpdatE

* Update hub.dart

* Update propagation_context.dart

* Update hub.dart

* Update

* Add test for resetting sampleRand in new trace

* Update

---------

Co-authored-by: Cursor Agent <[email protected]>

Author: buenaflor

CHANGELOG.md

@@ -9,6 +9,10 @@
   - This works on Flutter builds that include [this PR](https://github.com/flutter/flutter/pull/171545)
 - Add `LoggingIntegration` support for `SentryLog` ([#3050](https://github.com/getsentry/sentry-dart/pull/3050))
 
+### Fixes
+
+- Ensure consistent sampling per trace ([#3079](https://github.com/getsentry/sentry-dart/pull/3079))
+
 ### Dependencies
 
 - Bump Native SDK from v0.9.0 to v0.9.1 ([#3018](https://github.com/getsentry/sentry-dart/pull/3018))

dart/lib/src/hub.dart

@@ -1,5 +1,6 @@
 import 'dart:async';
 import 'dart:collection';
+import 'dart:math';
 
 import 'package:meta/meta.dart';
 
@@ -490,17 +491,29 @@ class Hub {
     } else if (_options.isTracingEnabled()) {
       final item = _peek();
 
-      // if transactionContext has no sampled decision, run the traces sampler
+      // if transactionContext has no sampling decision yet, run the traces sampler
       var samplingDecision = transactionContext.samplingDecision;
+      final propagationContext = scope.propagationContext;
+      // Store the generated/used sampleRand on the propagation context so
+      // that subsequent transactions in the same trace reuse it.
+      propagationContext.sampleRand ??= Random().nextDouble();
+
       if (samplingDecision == null) {
         final samplingContext = SentrySamplingContext(
             transactionContext, customSamplingContext ?? {});
-        samplingDecision = _tracesSampler.sample(samplingContext);
+
+        samplingDecision = _tracesSampler.sample(
+          samplingContext,
+          // sampleRand is guaranteed not to be null here
+          propagationContext.sampleRand!,
+        );
+
+        // Persist the sampling decision within the transaction context
         transactionContext.samplingDecision = samplingDecision;
       }
 
       transactionContext.origin ??= SentryTraceOrigins.manual;
-      transactionContext.traceId = scope.propagationContext.traceId;
+      transactionContext.traceId = propagationContext.traceId;
 
       SentryProfiler? profiler;
       if (_profilerFactory != null &&
@@ -529,8 +542,10 @@ class Hub {
   }
 
   @internal
-  void generateNewTraceId() {
+  void generateNewTrace() {
     scope.propagationContext.traceId = SentryId.newId();
+    // Reset sampleRand so that a new one is generated for the new trace when a new transaction is started
+    scope.propagationContext.sampleRand = null;
   }
 
   /// Gets the current active transaction or span.

dart/lib/src/hub_adapter.dart

@@ -162,7 +162,7 @@ class HubAdapter implements Hub {
       );
 
   @override
-  void generateNewTraceId() => Sentry.currentHub.generateNewTraceId();
+  void generateNewTrace() => Sentry.currentHub.generateNewTrace();
 
   @override
   void setSpanContext(

dart/lib/src/noop_hub.dart

@@ -126,7 +126,7 @@ class NoOpHub implements Hub {
       NoOpSentrySpan();
 
   @override
-  void generateNewTraceId() {}
+  void generateNewTrace() {}
 
   @override
   ISentrySpan? getSpan() => null;

dart/lib/src/propagation_context.dart

@@ -10,6 +10,13 @@ class PropagationContext {
   /// The dynamic sampling context.
   SentryBaggage? baggage;
 
+  /// Random number generated for sampling decisions.
+  ///
+  /// This value must be generated **once per trace** and reused across all
+  /// child spans and transactions that belong to the same trace. It is reset
+  /// whenever a new trace is started.
+  double? sampleRand;
+
   /// Baggage header to attach to http headers.
   SentryBaggageHeader? toBaggageHeader() =>
       baggage != null ? SentryBaggageHeader.fromBaggage(baggage!) : null;

dart/lib/src/sentry_traces_sampler.dart

@@ -19,7 +19,10 @@ class SentryTracesSampler {
     }
   }
 
-  SentryTracesSamplingDecision sample(SentrySamplingContext samplingContext) {
+  SentryTracesSamplingDecision sample(
+    SentrySamplingContext samplingContext,
+    double sampleRand,
+  ) {
     final samplingDecision =
         samplingContext.transactionContext.samplingDecision;
     if (samplingDecision != null) {
@@ -31,7 +34,7 @@ class SentryTracesSampler {
       try {
         final sampleRate = tracesSampler(samplingContext);
         if (sampleRate != null) {
-          return _makeSampleDecision(sampleRate);
+          return _makeSampleDecision(sampleRate, sampleRand);
         }
       } catch (exception, stackTrace) {
         _options.log(
@@ -54,7 +57,7 @@ class SentryTracesSampler {
 
     double? optionsRate = _options.tracesSampleRate;
     if (optionsRate != null) {
-      return _makeSampleDecision(optionsRate);
+      return _makeSampleDecision(optionsRate, sampleRand);
     }
 
     return SentryTracesSamplingDecision(false);
@@ -68,8 +71,10 @@ class SentryTracesSampler {
     return _isSampled(optionsRate);
   }
 
-  SentryTracesSamplingDecision _makeSampleDecision(double sampleRate) {
-    final sampleRand = _random.nextDouble();
+  SentryTracesSamplingDecision _makeSampleDecision(
+    double sampleRate,
+    double sampleRand,
+  ) {
     final sampled = _isSampled(sampleRate, sampleRand: sampleRand);
     return SentryTracesSamplingDecision(sampled,
         sampleRate: sampleRate, sampleRand: sampleRand);

dart/test/hub_test.dart

@@ -581,14 +581,23 @@ void main() {
       });
     });
 
-    test('generateNewTraceId creates new trace id in propagation context', () {
+    test('generateNewTrace creates new trace id in propagation context', () {
       final oldTraceId = hub.scope.propagationContext.traceId;
 
-      hub.generateNewTraceId();
+      hub.generateNewTrace();
 
       final newTraceId = hub.scope.propagationContext.traceId;
       expect(oldTraceId, isNot(newTraceId));
     });
+
+    test('generateNewTrace resets sampleRand in propagation context', () {
+      hub.scope.propagationContext.sampleRand = 1.0;
+
+      hub.generateNewTrace();
+
+      final newSampleRand = hub.scope.propagationContext.sampleRand;
+      expect(newSampleRand, isNull);
+    });
   });
 
   group('Hub scope callback', () {

dart/test/sample_rand_propagation_test.dart

@@ -0,0 +1,43 @@
+import 'package:sentry/sentry.dart';
+import 'package:sentry/src/sentry_tracer.dart';
+import 'package:test/test.dart';
+
+import 'test_utils.dart';
+
+void main() {
+  group('sampleRand', () {
+    test('is reused for transactions within the same trace', () {
+      final options = defaultTestOptions()..tracesSampleRate = 1.0;
+      final hub = Hub(options);
+
+      final tx1 = hub.startTransaction('tx1', 'op') as SentryTracer;
+      final rand1 = tx1.samplingDecision?.sampleRand;
+
+      // Sanity check
+      expect(rand1, isNotNull);
+
+      final tx2 = hub.startTransaction('tx2', 'op') as SentryTracer;
+      final rand2 = tx2.samplingDecision?.sampleRand;
+
+      expect(rand2, equals(rand1));
+    });
+
+    test('is generated within a transaction in a new trace', () {
+      final options = defaultTestOptions()..tracesSampleRate = 1.0;
+      final hub = Hub(options);
+
+      final tx1 = hub.startTransaction('tx1', 'op') as SentryTracer;
+      final rand1 = tx1.samplingDecision?.sampleRand;
+      expect(rand1, isNotNull);
+
+      // Start a new trace
+      hub.generateNewTrace();
+
+      final tx2 = hub.startTransaction('tx2', 'op') as SentryTracer;
+      final rand2 = tx2.samplingDecision?.sampleRand;
+
+      expect(rand2, isNotNull);
+      expect(rand2, isNot(equals(rand1)));
+    });
+  });
+}

dart/test/sentry_traces_sampler_test.dart

@@ -6,6 +6,7 @@ import 'test_utils.dart';
 
 void main() {
   late Fixture fixture;
+  const _sampleRand = 1.0;
 
   setUp(() {
     fixture = Fixture();
@@ -21,7 +22,7 @@ void main() {
     );
     final context = SentrySamplingContext(trContext, {});
 
-    expect(sut.sample(context).sampled, true);
+    expect(sut.sample(context, _sampleRand).sampled, true);
   });
 
   test('options has sampler', () {
@@ -40,7 +41,7 @@ void main() {
     );
     final context = SentrySamplingContext(trContext, {});
 
-    expect(sut.sample(context).sampled, true);
+    expect(sut.sample(context, _sampleRand).sampled, true);
   });
 
   test('transactionContext has parentSampled', () {
@@ -53,7 +54,7 @@ void main() {
     );
     final context = SentrySamplingContext(trContext, {});
 
-    expect(sut.sample(context).sampled, true);
+    expect(sut.sample(context, _sampleRand).sampled, true);
   });
 
   test('options has rate 1.0', () {
@@ -65,7 +66,7 @@ void main() {
     );
     final context = SentrySamplingContext(trContext, {});
 
-    expect(sut.sample(context).sampled, true);
+    expect(sut.sample(context, _sampleRand).sampled, true);
   });
 
   test('options has rate 0.0', () {
@@ -77,7 +78,7 @@ void main() {
     );
     final context = SentrySamplingContext(trContext, {});
 
-    expect(sut.sample(context).sampled, false);
+    expect(sut.sample(context, _sampleRand).sampled, false);
   });
 
   test('does not sample if tracesSampleRate and tracesSampleRate are null', () {
@@ -88,7 +89,7 @@ void main() {
       'op',
     );
     final context = SentrySamplingContext(trContext, {});
-    final samplingDecision = sut.sample(context);
+    final samplingDecision = sut.sample(context, _sampleRand);
 
     expect(samplingDecision.sampleRate, isNull);
     expect(samplingDecision.sampleRand, isNull);
@@ -111,7 +112,7 @@ void main() {
       'op',
     );
     final context = SentrySamplingContext(trContext, {});
-    sut.sample(context);
+    sut.sample(context, _sampleRand);
 
     expect(fixture.loggedException, exception);
     expect(fixture.loggedLevel, SentryLevel.error);

drift/test/mocks/mocks.mocks.dart

@@ -429,9 +429,9 @@ class MockHub extends _i1.Mock implements _i2.Hub {
       ) as _i2.ISentrySpan);
 
   @override
-  void generateNewTraceId() => super.noSuchMethod(
+  void generateNewTrace() => super.noSuchMethod(
         Invocation.method(
-          #generateNewTraceId,
+          #generateNewTrace,
           [],
         ),
         returnValueForMissingStub: null,