Support Dynamic Sampling

CHANGELOG.md

@@ -12,6 +12,7 @@
 - Add `User.Segment` property ([#1920](https://github.com/getsentry/sentry-dotnet/pull/1920))
 - Add support for custom `JsonConverter`s ([#1934](https://github.com/getsentry/sentry-dotnet/pull/1934))
 - Support more types for message template tags in SentryLogger ([#1945](https://github.com/getsentry/sentry-dotnet/pull/1945))
+- Support Dynamic Sampling ([#1953](https://github.com/getsentry/sentry-dotnet/pull/1953))
 
 ## Fixes
 

src/Sentry.AspNet/HttpContextExtensions.cs

@@ -1,6 +1,6 @@
-using System.Collections.Specialized;
 using System.ComponentModel;
 using System.Web;
+using Sentry.Extensibility;
 
 namespace Sentry.AspNet;
 
@@ -12,20 +12,47 @@ public static class HttpContextExtensions
 {
     private const string HttpContextTransactionItemName = "__SentryTransaction";
 
-    private static SentryTraceHeader? TryGetTraceHeader(NameValueCollection headers)
+    private static SentryTraceHeader? TryGetSentryTraceHeader(HttpContext context, SentryOptions? options)
     {
-        var traceHeader = headers.Get(SentryTraceHeader.HttpHeaderName);
-        if (traceHeader == null)
+        var value = context.Request.Headers.Get(SentryTraceHeader.HttpHeaderName);
+        if (string.IsNullOrWhiteSpace(value))
         {
             return null;
         }
 
+        options?.LogDebug("Received Sentry trace header '{0}'.", value);
+
+        try
+        {
+            return SentryTraceHeader.Parse(value);
+        }
+        catch (Exception ex)
+        {
+            options?.LogError("Invalid Sentry trace header '{0}'.", ex, value);
+            return null;
+        }
+    }
+
+    private static BaggageHeader? TryGetBaggageHeader(HttpContext context, SentryOptions? options)
+    {
+        var value = context.Request.Headers.Get(SentryTraceHeader.HttpHeaderName);
+        if (string.IsNullOrWhiteSpace(value))
+        {
+            return null;
+        }
+
+        // Note: If there are multiple baggage headers, they will be joined with comma delimiters,
+        // and can thus be treated as a single baggage header.
+
+        options?.LogDebug("Received baggage header '{0}'.", value);
+
         try
         {
-            return SentryTraceHeader.Parse(traceHeader);
+            return BaggageHeader.TryParse(value, onlySentry: true);
         }
-        catch
+        catch (Exception ex)
         {
+            options?.LogError("Invalid baggage header '{0}'.", ex, value);
             return null;
         }
     }
@@ -37,8 +64,9 @@ public static ITransaction StartSentryTransaction(this HttpContext httpContext)
     {
         var method = httpContext.Request.HttpMethod;
         var path = httpContext.Request.Path;
+        var options = SentrySdk.CurrentOptions;
 
-        var traceHeader = TryGetTraceHeader(httpContext.Request.Headers);
+        var traceHeader = TryGetSentryTraceHeader(httpContext, options);
 
         var transactionName = $"{method} {path}";
         const string transactionOperation = "http.server";
@@ -47,7 +75,29 @@ public static ITransaction StartSentryTransaction(this HttpContext httpContext)
             ? new TransactionContext(transactionName, transactionOperation, traceHeader, TransactionNameSource.Url)
             : new TransactionContext(transactionName, transactionOperation, TransactionNameSource.Url);
 
-        var transaction = SentrySdk.StartTransaction(transactionContext);
+        var customSamplingContext = new Dictionary<string, object?>(3, StringComparer.Ordinal)
+        {
+            ["__HttpMethod"] = method,
+            ["__HttpPath"] = path,
+            ["__HttpContext"] = httpContext,
+        };
+
+        // Set the Dynamic Sampling Context from the baggage header, if it exists.
+        var baggageHeader = TryGetBaggageHeader(httpContext, options);
+        var dynamicSamplingContext = baggageHeader?.CreateDynamicSamplingContext();
+
+        if (traceHeader is { } && baggageHeader is null)
+        {
+            // We received a sentry-trace header without a baggage header, which indicates the request
+            // originated from an older SDK that doesn't support dynamic sampling.
+            // Set DynamicSamplingContext.Empty to "freeze" the DSC on the transaction.
+            // See:
+            // https://develop.sentry.dev/sdk/performance/dynamic-sampling-context/#freezing-dynamic-sampling-context
+            // https://develop.sentry.dev/sdk/performance/dynamic-sampling-context/#unified-propagation-mechanism
+            dynamicSamplingContext = DynamicSamplingContext.Empty;
+        }
+
+        var transaction = SentrySdk.StartTransaction(transactionContext, customSamplingContext, dynamicSamplingContext);
 
         SentrySdk.ConfigureScope(scope => scope.Transaction = transaction);
         httpContext.Items[HttpContextTransactionItemName] = transaction;

src/Sentry.AspNetCore/SentryTracingMiddleware.cs

@@ -5,6 +5,7 @@
 using Microsoft.Extensions.Options;
 using Sentry.AspNetCore.Extensions;
 using Sentry.Extensibility;
+using Sentry.Internal;
 
 namespace Sentry.AspNetCore
 {
@@ -50,6 +51,30 @@ public SentryTracingMiddleware(
             }
         }
 
+        private BaggageHeader? TryGetBaggageHeader(HttpContext context)
+        {
+            var value = context.Request.Headers.GetValueOrDefault(BaggageHeader.HttpHeaderName);
+            if (string.IsNullOrWhiteSpace(value))
+            {
+                return null;
+            }
+
+            // Note: If there are multiple baggage headers, they will be joined with comma delimiters,
+            // and can thus be treated as a single baggage header.
+
+            _options.LogDebug("Received baggage header '{0}'.", value);
+
+            try
+            {
+                return BaggageHeader.TryParse(value, onlySentry: true);
+            }
+            catch (Exception ex)
+            {
+                _options.LogError("Invalid baggage header '{0}'.", ex, value);
+                return null;
+            }
+        }
+
         private ITransaction? TryStartTransaction(HttpContext context)
         {
             if (context.Request.Method == HttpMethod.Options.Method)
@@ -65,18 +90,14 @@ public SentryTracingMiddleware(
                 // Attempt to start a transaction from the trace header if it exists
                 var traceHeader = TryGetSentryTraceHeader(context);
 
-                // It's important to try and set the transaction name
-                // to some value here so that it's available for use
-                // in sampling.
-                // At a later stage, we will try to get the transaction name
-                // again, to account for the other middlewares that may have
-                // ran after ours.
-                var transactionName =
-                    context.TryGetTransactionName();
+                // It's important to try and set the transaction name to some value here so that it's available for use
+                // in sampling.  At a later stage, we will try to get the transaction name again, to account for the
+                // other middlewares that may have ran after ours.
+                var transactionName = context.TryGetTransactionName() ?? string.Empty;
 
                 var transactionContext = traceHeader is not null
-                    ? new TransactionContext(transactionName ?? string.Empty, OperationName, traceHeader, TransactionNameSource.Route)
-                    : new TransactionContext(transactionName ?? string.Empty, OperationName, TransactionNameSource.Route);
+                    ? new TransactionContext(transactionName, OperationName, traceHeader, TransactionNameSource.Route)
+                    : new TransactionContext(transactionName, OperationName, TransactionNameSource.Route);
 
                 var customSamplingContext = new Dictionary<string, object?>(4, StringComparer.Ordinal)
                 {
@@ -86,7 +107,22 @@ public SentryTracingMiddleware(
                     [SamplingExtensions.KeyForHttpContext] = context,
                 };
 
-                var transaction = hub.StartTransaction(transactionContext, customSamplingContext);
+                // Set the Dynamic Sampling Context from the baggage header, if it exists.
+                var baggageHeader = TryGetBaggageHeader(context);
+                var dynamicSamplingContext = baggageHeader?.CreateDynamicSamplingContext();
+
+                if (traceHeader is { } && baggageHeader is null)
+                {
+                    // We received a sentry-trace header without a baggage header, which indicates the request
+                    // originated from an older SDK that doesn't support dynamic sampling.
+                    // Set DynamicSamplingContext.Empty to "freeze" the DSC on the transaction.
+                    // See:
+                    // https://develop.sentry.dev/sdk/performance/dynamic-sampling-context/#freezing-dynamic-sampling-context
+                    // https://develop.sentry.dev/sdk/performance/dynamic-sampling-context/#unified-propagation-mechanism
+                    dynamicSamplingContext = DynamicSamplingContext.Empty;
+                }
+
+                var transaction = hub.StartTransaction(transactionContext, customSamplingContext, dynamicSamplingContext);
 
                 _options.LogInfo(
                     "Started transaction with span ID '{0}' and trace ID '{1}'.",

src/Sentry/BaggageHeader.cs

@@ -0,0 +1,135 @@
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using Sentry.Internal.Extensions;
+
+namespace Sentry
+{
+    /// <summary>
+    /// Baggage Header for dynamic sampling.
+    /// </summary>
+    /// <seealso href="https://develop.sentry.dev/sdk/performance/dynamic-sampling-context"/>
+    /// <seealso href="https://www.w3.org/TR/baggage"/>
+    internal class BaggageHeader
+    {
+        internal const string HttpHeaderName = "baggage";
+        internal const string SentryKeyPrefix = "sentry-";
+
+        // https://www.w3.org/TR/baggage/#baggage-string
+        // "Uniqueness of keys between multiple list-members in a baggage-string is not guaranteed."
+        // "The order of duplicate entries SHOULD be preserved when mutating the list."
+
+        public IReadOnlyList<KeyValuePair<string, string>> Members { get; }
+
+        private BaggageHeader(IEnumerable<KeyValuePair<string, string>> members) =>
+            Members = members.ToList().AsReadOnly();
+
+        // 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.
+        public IReadOnlyDictionary<string, string> GetSentryMembers() =>
+            Members
+                .Where(kvp => kvp.Key.StartsWith(SentryKeyPrefix))
+                .GroupBy(kvp => kvp.Key, kvp => kvp.Value)
+                .ToDictionary(
+#if NETCOREAPP || NETSTANDARD2_1
+                    g => g.Key[SentryKeyPrefix.Length..],
+#else
+                    g => g.Key.Substring(SentryKeyPrefix.Length),
+#endif
+                    g => g.First());
+
+        /// <summary>
+        /// Creates the baggage header string based on the members of this instance.
+        /// </summary>
+        /// <returns>The baggage header string.</returns>
+        public override string ToString()
+        {
+            // The keys do not require special encoding.  The values are percent-encoded.
+            // The results should not be sorted, as the baggage spec says original ordering should be preserved.
+            var members = Members.Select(x => $"{x.Key}={Uri.EscapeDataString(x.Value)}");
+
+            // Whitespace after delimiter is optional by the spec, but typical by convention.
+            return string.Join(", ", members);
+        }
+
+        /// <summary>
+        /// Parses a baggage header string.
+        /// </summary>
+        /// <param name="baggage">The string to parse.</param>
+        /// <param name="onlySentry">
+        /// When <c>false</c>, the resulting object includes all list members present in the baggage header string.
+        /// When <c>true</c>, the resulting object includes only members prefixed with <c>"sentry-"</c>.
+        /// </param>
+        /// <returns>
+        /// An object representing the members baggage header, or <c>null</c> if there are no members parsed.
+        /// </returns>
+        public static BaggageHeader? TryParse(string baggage, bool onlySentry = false)
+        {
+            // Example from W3C baggage spec:
+            // "key1=value1;property1;property2, key2 = value2, key3=value3; propertyKey=propertyValue"
+
+            var items = baggage.Split(',', StringSplitOptions.RemoveEmptyEntries);
+            var members = new List<KeyValuePair<string, string>>(items.Length);
+
+            foreach (var item in items)
+            {
+                // Per baggage spec, the value may contain = characters, so limit the split to 2 parts.
+                var parts = item.Split('=', 2);
+                if (parts.Length != 2)
+                {
+                    // malformed, missing separator, key, or value
+                    continue;
+                }
+
+                var key = parts[0].Trim();
+                var value = parts[1].Trim();
+                if (key.Length == 0 || value.Length == 0)
+                {
+                    // malformed, key or value found empty
+                    continue;
+                }
+
+                if (!onlySentry || key.StartsWith(SentryKeyPrefix))
+                {
+                    // Values are percent-encoded.  Decode them before storing.
+                    members.Add(key, Uri.UnescapeDataString(value));
+                }
+            }
+
+            return members.Count == 0 ? null : new BaggageHeader(members);
+        }
+
+        public static BaggageHeader Create(
+            IEnumerable<KeyValuePair<string, string>> items,
+            bool useSentryPrefix = false)
+        {
+            var members = items.Where(member => IsValidKey(member.Key));
+
+            if (useSentryPrefix)
+            {
+                members = members.Select(kvp => new KeyValuePair<string, string>(SentryKeyPrefix + kvp.Key, kvp.Value));
+            }
+
+            return new BaggageHeader(members);
+        }
+
+        public static BaggageHeader Merge(IEnumerable<BaggageHeader> baggageHeaders) =>
+            new(baggageHeaders.SelectMany(x => x.Members));
+
+        private static bool IsValidKey(string key)
+        {
+            if (key.Length == 0)
+            {
+                return false;
+            }
+
+            // The rules are the same as for HTTP headers.
+            // TODO: Is this public somewhere in .NET we can just call?
+            // https://www.w3.org/TR/baggage/#key
+            // https://www.rfc-editor.org/rfc/rfc7230#section-3.2.6
+            // https://source.dot.net/#System.Net.Http/System/Net/Http/HttpRuleParser.cs,21
+            const string delimiters = @"""(),/:;<=>?@[\]{}";
+            return key.All(c => c >= 33 && c != 127 && !delimiters.Contains(c));
+        }
+    }
+}