Propagate Sampling Seed (#3951)

Author: jamescrosswell

CHANGELOG.md

@@ -2,7 +2,12 @@
 
 ## Unreleased
 
+### Features
+
+- The sample seed used for sampling decisions is now propagated, for use in downstream custom trace samplers ([#3951](https://github.com/getsentry/sentry-dotnet/pull/3951))
+
 ### Fixes
+
 - Add Azure Function UseSentry overloads for easier wire ups  ([#3971](https://github.com/getsentry/sentry-dotnet/pull/3971))
 
 ### Dependencies

src/Sentry/BaggageHeader.cs

@@ -26,7 +26,7 @@ private BaggageHeader(IEnumerable<KeyValuePair<string, string>> members) =>
 
     // We can safely return a dictionary of Sentry members, as we are in control over the keys added.
     // Just to be safe though, we'll group by key and only take the first of each one.
-    internal IReadOnlyDictionary<string, string> GetSentryMembers() =>
+    internal Dictionary<string, string> GetSentryMembers() =>
         Members
             .Where(kvp => kvp.Key.StartsWith(SentryKeyPrefix))
             .GroupBy(kvp => kvp.Key, kvp => kvp.Value)

src/Sentry/DynamicSamplingContext.cs

@@ -1,3 +1,4 @@
+using Sentry.Internal;
 using Sentry.Internal.Extensions;
 
 namespace Sentry;
@@ -24,27 +25,33 @@ private DynamicSamplingContext(
         string publicKey,
         bool? sampled,
         double? sampleRate = null,
+        double? sampleRand = null,
         string? release = null,
         string? environment = null,
         string? transactionName = null)
     {
         // Validate and set required values
         if (traceId == SentryId.Empty)
         {
-            throw new ArgumentOutOfRangeException(nameof(traceId));
+            throw new ArgumentOutOfRangeException(nameof(traceId), "cannot be empty");
         }
 
         if (string.IsNullOrWhiteSpace(publicKey))
         {
-            throw new ArgumentException(default, nameof(publicKey));
+            throw new ArgumentException("cannot be empty", nameof(publicKey));
         }
 
         if (sampleRate is < 0.0 or > 1.0)
         {
-            throw new ArgumentOutOfRangeException(nameof(sampleRate));
+            throw new ArgumentOutOfRangeException(nameof(sampleRate), "Arg invalid if < 0.0 or > 1.0");
         }
 
-        var items = new Dictionary<string, string>(capacity: 7)
+        if (sampleRand is < 0.0 or >= 1.0)
+        {
+            throw new ArgumentOutOfRangeException(nameof(sampleRand), "Arg invalid if < 0.0 or >= 1.0");
+        }
+
+        var items = new Dictionary<string, string>(capacity: 8)
         {
             ["trace_id"] = traceId.ToString(),
             ["public_key"] = publicKey,
@@ -61,6 +68,11 @@ private DynamicSamplingContext(
             items.Add("sample_rate", sampleRate.Value.ToString(CultureInfo.InvariantCulture));
         }
 
+        if (sampleRand is not null)
+        {
+            items.Add("sample_rand", sampleRand.Value.ToString("N4", CultureInfo.InvariantCulture));
+        }
+
         if (!string.IsNullOrWhiteSpace(release))
         {
             items.Add("release", release);
@@ -99,7 +111,7 @@ private DynamicSamplingContext(
             return null;
         }
 
-        if (items.TryGetValue("sampled", out var sampledString) && !bool.TryParse(sampledString, out _))
+        if (items.TryGetValue("sampled", out var sampledString) && !bool.TryParse(sampledString, out var sampled))
         {
             return null;
         }
@@ -111,6 +123,27 @@ private DynamicSamplingContext(
             return null;
         }
 
+        // See https://develop.sentry.dev/sdk/telemetry/traces/#propagated-random-value
+        if (items.TryGetValue("sample_rand", out var sampleRand))
+        {
+            if (!double.TryParse(sampleRand, NumberStyles.Float, CultureInfo.InvariantCulture, out var rand) ||
+                 rand is < 0.0 or >= 1.0)
+            {
+                return null;
+            }
+        }
+        else
+        {
+            var rand = SampleRandHelper.GenerateSampleRand(traceId);
+            if (!string.IsNullOrEmpty(sampledString))
+            {
+                // Ensure sample_rand is consistent with the sampling decision that has already been made
+                rand = bool.Parse(sampledString)
+                    ? rand * rate // 0 <= sampleRand < rate
+                    : rate + (1 - rate) * rand; // rate < sampleRand < 1
+            }
+            items.Add("sample_rand", rand.ToString("N4", CultureInfo.InvariantCulture));
+        }
         return new DynamicSamplingContext(items);
     }
 
@@ -121,6 +154,7 @@ public static DynamicSamplingContext CreateFromTransaction(TransactionTracer tra
         var traceId = transaction.TraceId;
         var sampled = transaction.IsSampled;
         var sampleRate = transaction.SampleRate!.Value;
+        var sampleRand = transaction.SampleRand;
         var transactionName = transaction.NameSource.IsHighQuality() ? transaction.Name : null;
 
         // These two may not have been set yet on the transaction, but we can get them directly.
@@ -132,6 +166,7 @@ public static DynamicSamplingContext CreateFromTransaction(TransactionTracer tra
             publicKey,
             sampled,
             sampleRate,
+            sampleRand,
             release,
             environment,
             transactionName);

src/Sentry/Internal/FnvHash.cs

@@ -0,0 +1,43 @@
+namespace Sentry.Internal;
+
+/// <summary>
+/// FNV is a non-cryptographic hash.
+///
+/// See https://en.wikipedia.org/wiki/Fowler%E2%80%93Noll%E2%80%93Vo_hash_function#FNV_hash_parameters
+/// </summary>
+/// <remarks>
+/// We use a struct to avoid heap allocations.
+/// </remarks>
+internal struct FnvHash
+{
+    public FnvHash()
+    {
+    }
+
+    private const int Offset = unchecked((int)2166136261);
+    private const int Prime = 16777619;
+
+    private int HashCode { get; set; } = Offset;
+
+    private void Combine(byte data)
+    {
+        unchecked
+        {
+            HashCode ^= data;
+            HashCode *= Prime;
+        }
+    }
+
+    private static int ComputeHash(byte[] data)
+    {
+        var result = new FnvHash();
+        foreach (var b in data)
+        {
+            result.Combine(b);
+        }
+
+        return result.HashCode;
+    }
+
+    public static int ComputeHash(string data) => ComputeHash(Encoding.UTF8.GetBytes(data));
+}

src/Sentry/Internal/Hub.cs

@@ -127,7 +127,12 @@ internal ITransactionTracer StartTransaction(
         IReadOnlyDictionary<string, object?> customSamplingContext,
         DynamicSamplingContext? dynamicSamplingContext)
     {
-        var transaction = new TransactionTracer(this, context);
+        var transaction = new TransactionTracer(this, context)
+        {
+            SampleRand = dynamicSamplingContext?.Items.TryGetValue("sample_rand", out var sampleRand) ?? false
+                ? double.Parse(sampleRand, NumberStyles.Float, CultureInfo.InvariantCulture)
+                : SampleRandHelper.GenerateSampleRand(context.TraceId.ToString())
+        };
 
         // If the hub is disabled, we will always sample out.  In other words, starting a transaction
         // after disposing the hub will result in that transaction not being sent to Sentry.
@@ -151,7 +156,7 @@ internal ITransactionTracer StartTransaction(
 
                 if (tracesSampler(samplingContext) is { } sampleRate)
                 {
-                    transaction.IsSampled = _randomValuesFactory.NextBool(sampleRate);
+                    transaction.IsSampled = SampleRandHelper.IsSampled(transaction.SampleRand.Value, sampleRate);
                     transaction.SampleRate = sampleRate;
                 }
             }
@@ -160,7 +165,7 @@ internal ITransactionTracer StartTransaction(
             if (transaction.IsSampled == null)
             {
                 var sampleRate = _options.TracesSampleRate ?? 0.0;
-                transaction.IsSampled = _randomValuesFactory.NextBool(sampleRate);
+                transaction.IsSampled = SampleRandHelper.IsSampled(transaction.SampleRand.Value, sampleRate);
                 transaction.SampleRate = sampleRate;
             }
 

src/Sentry/Internal/SampleRandHelper.cs

@@ -0,0 +1,15 @@
+namespace Sentry.Internal;
+
+internal static class SampleRandHelper
+{
+    internal static double GenerateSampleRand(string traceId)
+        => new Random(FnvHash.ComputeHash(traceId)).NextDouble();
+
+    internal static bool IsSampled(double sampleRand, double rate) => rate switch
+    {
+        >= 1 => true,
+        <= 0 => false,
+        _ => sampleRand < rate
+    };
+
+}

src/Sentry/TransactionTracer.cs

@@ -100,6 +100,8 @@ internal set
     /// </summary>
     public double? SampleRate { get; internal set; }
 
+    internal double? SampleRand { get; set; }
+
     /// <inheritdoc />
     public SentryLevel? Level { get; set; }
 

test/Sentry.AspNetCore.Tests/SentryTracingMiddlewareTests.cs

@@ -1,4 +1,3 @@
-#if NETCOREAPP3_1_OR_GREATER
 using Microsoft.AspNetCore.Builder;
 using Microsoft.AspNetCore.Hosting;
 using Microsoft.AspNetCore.Http;
@@ -285,6 +284,7 @@ public async Task Baggage_header_propagates_to_outbound_requests(bool shouldProp
         const string incomingBaggage =
             "sentry-trace_id=75302ac48a024bde9a3b3734a82e36c8, " +
             "sentry-public_key=d4d82fc1c2c4032a83f3a29aa3a3aff, " +
+            "sentry-sample_rand=0.1234, " +
             "sentry-sample_rate=0.5, " +
             "foo-bar=abc123";
 
@@ -299,6 +299,7 @@ public async Task Baggage_header_propagates_to_outbound_requests(bool shouldProp
                 "other-value=abc123, " +
                 "sentry-trace_id=75302ac48a024bde9a3b3734a82e36c8, " +
                 "sentry-public_key=d4d82fc1c2c4032a83f3a29aa3a3aff, " +
+                "sentry-sample_rand=0.1234, " +
                 "sentry-sample_rate=0.5";
         }
         else
@@ -382,6 +383,7 @@ public async Task Baggage_header_sets_dynamic_sampling_context()
         const string baggage =
             "sentry-trace_id=75302ac48a024bde9a3b3734a82e36c8, " +
             "sentry-public_key=d4d82fc1c2c4032a83f3a29aa3a3aff, " +
+            "sentry-sample_rand=0.1234, " +
             "sentry-sample_rate=0.5";
 
         // Arrange
@@ -677,5 +679,3 @@ public async Task Transaction_TransactionNameProviderSetUnset_TransactionNameSet
         transaction.NameSource.Should().Be(TransactionNameSource.Url);
     }
 }
-
-#endif

test/Sentry.Testing/VerifyExtensions.cs

@@ -11,6 +11,7 @@ public static SettingsTask IgnoreStandardSentryMembers(this SettingsTask setting
         return settings
             .ScrubMachineName()
             .ScrubUserName()
+            .ScrubMember("sample_rand")
             .AddExtraSettings(_ =>
             {
                 _.Converters.Add(new SpansConverter());