[sdk-traces] Add support for OTEL_TRACES_SAMPLER and OTEL_TRACES_SAMPLER_ARG

src/OpenTelemetry/CHANGELOG.md

@@ -77,6 +77,16 @@
   Specification](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/configuration/sdk-environment-variables.md#exemplar).
   ([#5412](https://github.com/open-telemetry/opentelemetry-dotnet/pull/5412))
 
+* `TracerProvider`s can now have a sampler configured via the
+  `OTEL_TRACES_SAMPLER` environment variable. The supported values are:
+  `always_off`, `always_on`, `traceidratio`, `parentbased_always_on`,
+  `parentbased_always_off`, and `parentbased_traceidratio`. The options
+  `traceidratio` and `parentbased_traceidratio` may have the sampler probability
+  configured via the `OTEL_TRACES_SAMPLER_ARG` environment variable.
+  For details see: [OpenTelemetry Environment Variable
+  Specification](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/configuration/sdk-environment-variables.md#general-sdk-configuration).
+  ([#5448](https://github.com/open-telemetry/opentelemetry-dotnet/pull/5448))
+
 ## 1.7.0
 
 Released 2023-Dec-08

src/OpenTelemetry/Trace/TracerProviderSdk.cs

@@ -5,6 +5,7 @@
 using System.Runtime.CompilerServices;
 using System.Text;
 using System.Text.RegularExpressions;
+using Microsoft.Extensions.Configuration;
 using Microsoft.Extensions.DependencyInjection;
 using OpenTelemetry.Internal;
 using OpenTelemetry.Resources;
@@ -13,6 +14,9 @@ namespace OpenTelemetry.Trace;
 
 internal sealed class TracerProviderSdk : TracerProvider
 {
+    internal const string TracesSamplerConfigKey = "OTEL_TRACES_SAMPLER";
+    internal const string TracesSamplerArgConfigKey = "OTEL_TRACES_SAMPLER_ARG";
+
     internal readonly IServiceProvider ServiceProvider;
     internal readonly IDisposable? OwnedServiceProvider;
     internal int ShutdownCount;
@@ -57,7 +61,7 @@ internal TracerProviderSdk(
         resourceBuilder.ServiceProvider = serviceProvider;
         this.Resource = resourceBuilder.Build();
 
-        this.sampler = state.Sampler ?? new ParentBasedSampler(new AlwaysOnSampler());
+        this.sampler = GetSampler(serviceProvider!.GetRequiredService<IConfiguration>(), state.Sampler);
         OpenTelemetrySdkEventSource.Log.TracerProviderSdkEvent($"Sampler added = \"{this.sampler.GetType()}\".");
 
         this.supportLegacyActivity = state.LegacyActivityOperationNames.Count > 0;
@@ -401,6 +405,79 @@ protected override void Dispose(bool disposing)
         base.Dispose(disposing);
     }
 
+    private static Sampler GetSampler(IConfiguration configuration, Sampler? stateSampler)
+    {
+        Sampler? sampler = null;
+
+        if (stateSampler != null)
+        {
+            sampler = stateSampler;
+        }
+
+        if (configuration.TryGetStringValue(TracesSamplerConfigKey, out var configValue))
+        {
+            if (sampler != null)
+            {
+                OpenTelemetrySdkEventSource.Log.TracerProviderSdkEvent(
+                    $"Trace sampler configuration value '{configValue}' has been ignored because a value '{sampler.GetType().FullName}' was set previously.");
+                return sampler;
+            }
+
+            if (string.Equals(configValue, "always_on", StringComparison.OrdinalIgnoreCase))
+            {
+                sampler = new AlwaysOnSampler();
+            }
+            else if (string.Equals(configValue, "always_off", StringComparison.OrdinalIgnoreCase))
+            {
+                sampler = new AlwaysOffSampler();
+            }
+            else if (string.Equals(configValue, "traceidratio", StringComparison.OrdinalIgnoreCase))
+            {
+                var traceIdRatio = ReadTraceIdRatio(configuration);
+                sampler = new TraceIdRatioBasedSampler(traceIdRatio);
+            }
+            else if (string.Equals(configValue, "parentbased_always_on", StringComparison.OrdinalIgnoreCase))
+            {
+                sampler = new ParentBasedSampler(new AlwaysOnSampler());
+            }
+            else if (string.Equals(configValue, "parentbased_always_off", StringComparison.OrdinalIgnoreCase))
+            {
+                sampler = new ParentBasedSampler(new AlwaysOffSampler());
+            }
+            else if (string.Equals(configValue, "parentbased_traceidratio", StringComparison.OrdinalIgnoreCase))
+            {
+                var traceIdRatio = ReadTraceIdRatio(configuration);
+                sampler = new ParentBasedSampler(new TraceIdRatioBasedSampler(traceIdRatio));
+            }
+            else
+            {
+                OpenTelemetrySdkEventSource.Log.TracerProviderSdkEvent($"OTEL_TRACES_SAMPLER configuration was found but the value '{configValue}' is invalid and will be ignored.");
+            }
+
+            if (sampler != null)
+            {
+                OpenTelemetrySdkEventSource.Log.TracerProviderSdkEvent($"Trace sampler set to '{sampler.GetType().FullName}' from configuration.");
+            }
+        }
+
+        return sampler ?? new ParentBasedSampler(new AlwaysOnSampler());
+    }
+
+    private static double ReadTraceIdRatio(IConfiguration configuration)
+    {
+        if (configuration.TryGetStringValue(TracesSamplerArgConfigKey, out var configValue) &&
+                double.TryParse(configValue, out var traceIdRatio))
+        {
+            return traceIdRatio;
+        }
+        else
+        {
+            OpenTelemetrySdkEventSource.Log.TracerProviderSdkEvent($"Trace sampler argument configuration was found but the value '{configValue}' is invalid and will be ignored, default of value of '1.0' will be used.");
+        }
+
+        return 1.0;
+    }
+
     private static ActivitySamplingResult ComputeActivitySamplingResult(
         ref ActivityCreationOptions<ActivityContext> options,
         Sampler sampler)

test/OpenTelemetry.Tests/Trace/TracerProviderSdkTest.cs

@@ -2,6 +2,8 @@
 // SPDX-License-Identifier: Apache-2.0
 
 using System.Diagnostics;
+using Microsoft.Extensions.Configuration;
+using Microsoft.Extensions.DependencyInjection;
 using OpenTelemetry.Instrumentation;
 using OpenTelemetry.Resources;
 using OpenTelemetry.Resources.Tests;
@@ -1039,6 +1041,68 @@ public void SdkPopulatesSamplingParamsCorrectlyForLegacyActivityWithInProcParent
         activity.Stop();
     }
 
+    [Theory]
+    [InlineData(null, null, "ParentBased{AlwaysOnSampler}")]
+    [InlineData("always_on", null, "AlwaysOnSampler")]
+    [InlineData("always_off", null, "AlwaysOffSampler")]
+    [InlineData("always_OFF", null, "AlwaysOffSampler")]
+    [InlineData("traceidratio", "0.5", "TraceIdRatioBasedSampler{0.500000}")]
+    [InlineData("traceidratio", "not_a_double", "TraceIdRatioBasedSampler{1.000000}")]
+    [InlineData("parentbased_always_on", null, "ParentBased{AlwaysOnSampler}")]
+    [InlineData("parentbased_always_off", null, "ParentBased{AlwaysOffSampler}")]
+    [InlineData("parentbased_traceidratio", "0.111", "ParentBased{TraceIdRatioBasedSampler{0.111000}}")]
+    [InlineData("ParentBased_TraceIdRatio", "0.000001", "ParentBased{TraceIdRatioBasedSampler{0.000001}}")]
+    public void TestSamplerSetFromConfiguration(string configValue, string argValue, string samplerDescription)
+    {
+        var configBuilder = new ConfigurationBuilder();
+
+        if (!string.IsNullOrEmpty(configValue))
+        {
+            configBuilder.AddInMemoryCollection(new Dictionary<string, string>
+            {
+                [TracerProviderSdk.TracesSamplerConfigKey] = configValue,
+            });
+        }
+
+        if (!string.IsNullOrEmpty(argValue))
+        {
+            configBuilder.AddInMemoryCollection(new Dictionary<string, string>
+            {
+                [TracerProviderSdk.TracesSamplerArgConfigKey] = argValue,
+            });
+        }
+
+        var builder = Sdk.CreateTracerProviderBuilder();
+        builder.ConfigureServices(s => s.AddSingleton<IConfiguration>(configBuilder.Build()));
+        using var tracerProvider = builder.Build();
+        var tracerProviderSdk = tracerProvider as TracerProviderSdk;
+
+        Assert.NotNull(tracerProviderSdk);
+        Assert.NotNull(tracerProviderSdk.Sampler);
+        Assert.Equal(samplerDescription, tracerProviderSdk.Sampler.Description);
+    }
+
+    [Fact]
+    public void TestSamplerConfigurationIgnoredWhenSetProgrammatically()
+    {
+        var configBuilder = new ConfigurationBuilder();
+        configBuilder.AddInMemoryCollection(new Dictionary<string, string>
+        {
+            [TracerProviderSdk.TracesSamplerConfigKey] = "always_off",
+        });
+
+        var builder = Sdk.CreateTracerProviderBuilder();
+        builder.ConfigureServices(s => s.AddSingleton<IConfiguration>(configBuilder.Build()));
+        builder.SetSampler(new AlwaysOnSampler());
+
+        using var tracerProvider = builder.Build();
+        var tracerProviderSdk = tracerProvider as TracerProviderSdk;
+
+        Assert.NotNull(tracerProviderSdk);
+        Assert.NotNull(tracerProviderSdk.Sampler);
+        Assert.Equal("AlwaysOnSampler", tracerProviderSdk.Sampler.Description);
+    }
+
     [Fact]
     public void TracerProvideSdkCreatesAndDiposesInstrumentation()
     {