Refactor sampler config to use SamplerOptions and IOptions

- Introduce `SamplerOptions` to encapsulate trace sampler configuration, parsing OTEL_TRACES_SAMPLER and OTEL_TRACES_SAMPLER_ARG from IConfiguration.
- Refactor `TracerProviderSdk` to resolve sampler settings via `IOptions<SamplerOptions>`, enabling standard options pipeline overrides and improved diagnostics.
- Add tests for configuration, overrides, and error handling.
- Update public API and diagnostics to reflect new options-based approach.

Author: stevejgordon

src/OpenTelemetry/.publicApi/Stable/PublicAPI.Unshipped.txt

@@ -0,0 +1,5 @@
+OpenTelemetry.Trace.SamplerOptions
+OpenTelemetry.Trace.SamplerOptions.SamplerArg.get -> double?
+OpenTelemetry.Trace.SamplerOptions.SamplerArg.set -> void
+OpenTelemetry.Trace.SamplerOptions.SamplerType.get -> string?
+OpenTelemetry.Trace.SamplerOptions.SamplerType.set -> void

src/OpenTelemetry/CHANGELOG.md

@@ -6,6 +6,10 @@ Notes](../../RELEASENOTES.md).
 
 ## Unreleased
 
+* Introduce SamplerOptions to encapsulate trace sampler configuration, parsing
+  OTEL_TRACES_SAMPLER and OTEL_TRACES_SAMPLER_ARG from IConfiguration.
+  ([#7192](https://github.com/open-telemetry/opentelemetry-dotnet/pull/7192))
+
 ## 1.15.3
 
 Released 2026-Apr-21

src/OpenTelemetry/Internal/Builder/ProviderBuilderServiceCollectionExtensions.cs

@@ -51,6 +51,7 @@ public static IServiceCollection AddOpenTelemetryTracerProviderBuilderServices(t
 #pragma warning disable CS8604 // Possible null reference argument.
         services.TryAddSingleton<TracerProviderBuilderSdk>();
         services.RegisterOptionsFactory(configuration => new BatchExportActivityProcessorOptions(configuration));
+        services.RegisterOptionsFactory(configuration => new SamplerOptions(configuration));
         services.RegisterOptionsFactory(
             (sp, configuration, name) => new ActivityExportProcessorOptions(
                 sp.GetRequiredService<IOptionsMonitor<BatchExportActivityProcessorOptions>>().Get(name)));

src/OpenTelemetry/Trace/SamplerOptions.cs

@@ -0,0 +1,76 @@
+// Copyright The OpenTelemetry Authors
+// SPDX-License-Identifier: Apache-2.0
+
+using System.Globalization;
+using Microsoft.Extensions.Configuration;
+
+namespace OpenTelemetry.Trace;
+
+/// <summary>
+/// Options for configuring the trace sampler.
+/// OTEL_TRACES_SAMPLER and OTEL_TRACES_SAMPLER_ARG environment variables
+/// are parsed during object construction.
+/// </summary>
+public sealed class SamplerOptions
+{
+    internal const string TracesSamplerConfigKey = "OTEL_TRACES_SAMPLER";
+    internal const string TracesSamplerArgConfigKey = "OTEL_TRACES_SAMPLER_ARG";
+
+    // Unlike some other options classes, we don't have a public parameterless constructor.
+    // The internal-only constructor is the right long-term design for any new options class using
+    // DelegatingOptionsFactory. Consumers never instantiate SamplerOptions directly, so there's no
+    // need for a public constructor. The public constructor on BatchExportActivityProcessorOptions
+    // pre-dates this pattern and is a historical artefact, not a template to follow for new work.
+
+    private double? samplerArg;
+
+    internal SamplerOptions(IConfiguration configuration)
+    {
+        if (configuration.TryGetStringValue(TracesSamplerConfigKey, out var samplerType))
+        {
+            this.SamplerType = samplerType;
+        }
+
+        if (configuration.TryGetStringValue(TracesSamplerArgConfigKey, out var samplerArgStr))
+        {
+            this.SamplerArgRaw = samplerArgStr;
+
+            if (double.TryParse(
+                samplerArgStr,
+                NumberStyles.Float | NumberStyles.AllowThousands,
+                CultureInfo.InvariantCulture,
+                out var parsedArg))
+            {
+                // Bypass the public setter so that SamplerArgRaw is not cleared.
+                this.samplerArg = parsedArg;
+            }
+
+            // If unparsable, samplerArg stays null; SamplerArgRaw carries the bad string
+            // for ReadTraceIdRatio to log when called for ratio-based samplers. This matches
+            // the behavior prior to introducing this options type.
+        }
+    }
+
+    /// <summary>
+    /// Gets or sets the sampler type.
+    /// </summary>
+    public string? SamplerType { get; set; }
+
+    /// <summary>
+    /// Gets or sets the sampler argument.
+    /// </summary>
+    public double? SamplerArg
+    {
+        get => this.samplerArg;
+        set
+        {
+            this.samplerArg = value;
+            this.SamplerArgRaw = null; // no original config string when set programmatically
+        }
+    }
+
+    /// <summary>
+    /// Gets the original configuration string so it can be logged.
+    /// </summary>
+    internal string? SamplerArgRaw { get; private set; }
+}

src/OpenTelemetry/Trace/TracerProviderSdk.cs

@@ -6,18 +6,15 @@
 using System.Runtime.CompilerServices;
 using System.Text;
 using System.Text.RegularExpressions;
-using Microsoft.Extensions.Configuration;
 using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.Options;
 using OpenTelemetry.Internal;
 using OpenTelemetry.Resources;
 
 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 IDisposable? OwnedServiceProvider;
     internal int ShutdownCount;
@@ -59,7 +56,9 @@ internal TracerProviderSdk(
         resourceBuilder.ServiceProvider = serviceProvider;
         this.Resource = resourceBuilder.Build();
 
-        this.Sampler = GetSampler(serviceProvider!.GetRequiredService<IConfiguration>(), state.Sampler);
+        this.Sampler = GetSampler(
+            serviceProvider!.GetRequiredService<IOptions<SamplerOptions>>().Value,
+            state.Sampler);
         OpenTelemetrySdkEventSource.Log.TracerProviderSdkEvent($"Sampler added = \"{this.Sampler.GetType()}\".");
 
         this.supportLegacyActivity = state.LegacyActivityOperationNames.Count > 0;
@@ -386,77 +385,78 @@ protected override void Dispose(bool disposing)
         base.Dispose(disposing);
     }
 
-    private static Sampler GetSampler(IConfiguration configuration, Sampler? stateSampler)
+    private static Sampler GetSampler(SamplerOptions options, Sampler? stateSampler)
     {
         var sampler = stateSampler;
 
-        if (configuration.TryGetStringValue(TracesSamplerConfigKey, out var configValue))
+        if (!string.IsNullOrWhiteSpace(options.SamplerType))
         {
             if (sampler != null)
             {
                 OpenTelemetrySdkEventSource.Log.TracerProviderSdkEvent(
-                    $"Trace sampler configuration value '{configValue}' has been ignored because a value '{sampler.GetType().FullName}' was set programmatically.");
+                    $"Trace sampler configuration value '{options.SamplerType}' has been ignored because a value '{sampler.GetType().FullName}' was set programmatically.");
                 return sampler;
             }
 
-            switch (configValue)
+            switch (options.SamplerType)
             {
-                case var _ when string.Equals(configValue, "always_on", StringComparison.OrdinalIgnoreCase):
+                case var _ when string.Equals(options.SamplerType, "always_on", StringComparison.OrdinalIgnoreCase):
                     sampler = AlwaysOnSampler.Instance;
                     break;
-                case var _ when string.Equals(configValue, "always_off", StringComparison.OrdinalIgnoreCase):
+                case var _ when string.Equals(options.SamplerType, "always_off", StringComparison.OrdinalIgnoreCase):
                     sampler = AlwaysOffSampler.Instance;
                     break;
-                case var _ when string.Equals(configValue, "traceidratio", StringComparison.OrdinalIgnoreCase):
+                case var _ when string.Equals(options.SamplerType, "traceidratio", StringComparison.OrdinalIgnoreCase):
                     {
-                        var traceIdRatio = ReadTraceIdRatio(configuration);
+                        var traceIdRatio = ReadTraceIdRatio(options);
                         sampler = new TraceIdRatioBasedSampler(traceIdRatio);
                         break;
                     }
 
-                case var _ when string.Equals(configValue, "parentbased_always_on", StringComparison.OrdinalIgnoreCase):
+                case var _ when string.Equals(options.SamplerType, "parentbased_always_on", StringComparison.OrdinalIgnoreCase):
                     sampler = new ParentBasedSampler(AlwaysOnSampler.Instance);
                     break;
-                case var _ when string.Equals(configValue, "parentbased_always_off", StringComparison.OrdinalIgnoreCase):
+                case var _ when string.Equals(options.SamplerType, "parentbased_always_off", StringComparison.OrdinalIgnoreCase):
                     sampler = new ParentBasedSampler(AlwaysOffSampler.Instance);
                     break;
-                case var _ when string.Equals(configValue, "parentbased_traceidratio", StringComparison.OrdinalIgnoreCase):
-                    {
-                        var traceIdRatio = ReadTraceIdRatio(configuration);
-                        sampler = new ParentBasedSampler(new TraceIdRatioBasedSampler(traceIdRatio));
-                        break;
-                    }
-
+                case var _ when string.Equals(options.SamplerType, "parentbased_traceidratio", StringComparison.OrdinalIgnoreCase):
+                    sampler = new ParentBasedSampler(new TraceIdRatioBasedSampler(ReadTraceIdRatio(options)));
+                    break;
                 default:
-                    OpenTelemetrySdkEventSource.Log.TracesSamplerConfigInvalid(configValue);
+                    OpenTelemetrySdkEventSource.Log.TracesSamplerConfigInvalid(options.SamplerType!);
                     break;
             }
 
             if (sampler != null)
             {
                 OpenTelemetrySdkEventSource.Log.TracerProviderSdkEvent($"Trace sampler set to '{sampler.GetType().FullName}' from configuration.");
             }
+
+            return sampler ?? new ParentBasedSampler(new AlwaysOnSampler());
         }
 
         return sampler ?? new ParentBasedSampler(AlwaysOnSampler.Instance);
     }
 
-    private static double ReadTraceIdRatio(IConfiguration configuration)
+    private static double ReadTraceIdRatio(SamplerOptions options)
     {
-        if (configuration.TryGetStringValue(TracesSamplerArgConfigKey, out var configValue) &&
-                double.TryParse(configValue, NumberStyles.Float | NumberStyles.AllowThousands, CultureInfo.InvariantCulture, out var traceIdRatio) &&
-                !double.IsNaN(traceIdRatio) &&
-                !double.IsInfinity(traceIdRatio) &&
-                traceIdRatio >= 0.0 &&
-                traceIdRatio <= 1.0)
+        var samplerArg = options.SamplerArg;
+        if (samplerArg.HasValue
+            && !double.IsNaN(samplerArg.Value)
+            && !double.IsInfinity(samplerArg.Value)
+            && samplerArg.Value >= 0.0
+            && samplerArg.Value <= 1.0)
         {
-            return traceIdRatio;
-        }
-        else
-        {
-            OpenTelemetrySdkEventSource.Log.TracesSamplerArgConfigInvalid(configValue ?? string.Empty);
+            return samplerArg.Value;
         }
 
+        // No valid ratio. Log the original config string for diagnostic fidelity and fall back to 1.0.
+        OpenTelemetrySdkEventSource.Log.TracesSamplerArgConfigInvalid(
+            options.SamplerArgRaw
+            ?? (samplerArg.HasValue
+                ? samplerArg.Value.ToString(CultureInfo.InvariantCulture)
+                : string.Empty));
+
         return 1.0;
     }
 

test/OpenTelemetry.Extensions.Hosting.Tests/OpenTelemetryServicesExtensionsTests.cs

@@ -168,6 +168,63 @@ public async Task AddOpenTelemetry_WithTracing_HostConfigurationHonoredTest()
         host.Dispose();
     }
 
+    [Fact]
+    public void AddOpenTelemetry_WithTracing_SamplerResolvedFromHostConfigurationTest()
+    {
+        using var clearSamplerEnv = EnvironmentVariableScope.Create(SamplerOptions.TracesSamplerConfigKey, null);
+        using var clearSamplerArgEnv = EnvironmentVariableScope.Create(SamplerOptions.TracesSamplerArgConfigKey, null);
+
+        var builder = new HostBuilder()
+            .ConfigureAppConfiguration(configBuilder =>
+            {
+                configBuilder.AddInMemoryCollection(new Dictionary<string, string?>
+                {
+                    [SamplerOptions.TracesSamplerConfigKey] = "traceidratio",
+                    [SamplerOptions.TracesSamplerArgConfigKey] = "0.25",
+                });
+            })
+            .ConfigureServices(services =>
+            {
+                services.AddOpenTelemetry().WithTracing();
+            });
+
+        using var host = builder.Build();
+
+        var tracerProvider = host.Services.GetRequiredService<TracerProvider>() as TracerProviderSdk;
+
+        Assert.NotNull(tracerProvider);
+        Assert.Equal("TraceIdRatioBasedSampler{0.250000}", tracerProvider.Sampler.Description);
+    }
+
+    [Fact]
+    public void AddOpenTelemetry_WithTracing_ConfigureSamplerOptionsOverridesHostConfigurationTest()
+    {
+        using var clearSamplerEnv = EnvironmentVariableScope.Create(SamplerOptions.TracesSamplerConfigKey, null);
+        using var clearSamplerArgEnv = EnvironmentVariableScope.Create(SamplerOptions.TracesSamplerArgConfigKey, null);
+
+        var builder = new HostBuilder()
+            .ConfigureAppConfiguration(configBuilder =>
+            {
+                configBuilder.AddInMemoryCollection(new Dictionary<string, string?>
+                {
+                    [SamplerOptions.TracesSamplerConfigKey] = "traceidratio",
+                    [SamplerOptions.TracesSamplerArgConfigKey] = "0.1",
+                });
+            })
+            .ConfigureServices(services =>
+            {
+                services.AddOpenTelemetry().WithTracing();
+                services.Configure<SamplerOptions>(o => o.SamplerArg = 0.9);
+            });
+
+        using var host = builder.Build();
+
+        var tracerProvider = host.Services.GetRequiredService<TracerProvider>() as TracerProviderSdk;
+
+        Assert.NotNull(tracerProvider);
+        Assert.Equal("TraceIdRatioBasedSampler{0.900000}", tracerProvider.Sampler.Description);
+    }
+
     [Fact]
     public void AddOpenTelemetry_WithTracing_NestedResolutionUsingConfigureTest()
     {