Introduce a ConfigureSampler API

[stevejgordon]

Relates to #7192

Changes

Introduces ConfigureSampler on the TracerProviderSdk.

Today the only way to influence the SDK's sampler is SetSampler, which wins outright: when a programmatic sampler is present, the user's OTEL_TRACES_SAMPLER value is logged as ignored and discarded. So any library that supplies a sampler silently throws away the user's configuration, and two such libraries silently conflict (last writer wins, no diagnostic). ConfigureSampler registers a callback that receives the sampler the SDK resolved (programmatic, environment, or the default) and returns the sampler to use, so a library can wrap, inspect, conditionally replace, or just observe it instead of overwriting it. Multiple registrations chain in registration order, so libraries compose. This completes an existing pattern rather than introducing a concept: the resource already has SetResourceBuilder, ConfigureResource and GetResource, all stable, and the signature is the existing stable SetSampler(Func<IServiceProvider, Sampler>) overload with the resolved sampler as an extra input. Resolution order is unchanged, and behaviour is identical when no callback is registered.

The callback runs once during Build() and the sampler field stays immutable. Runtime swapping already works today without any SDK change, via SetSampler with a delegating sampler holding a mutable delegate. What the SDK does not expose is the effective resolved sampler, and that is what this adds. This matters increasingly as declarative configuration moves sampler selection out of code, and it is the missing piece for dynamic control sampler configuration. A component that adjusts sampling remotely has to layer over the user's configured sampler and be able to restore it, which is impossible today. Nothing here is specific to that work, and the benefits it introduce are (I believe) useful for other library cases.

I avoided introducing GetSampler in this PR as it adds less value. A type check would be needed to access which specific Sampler implementation is set, and today most samplers do not expose public properties of their specific configuration. We could add it as a consistency follow up.

Merge requirement checklist

• CONTRIBUTING guidelines followed (license requirements, nullable enabled, static analysis, etc.)
• Unit tests added/updated
• Appropriate CHANGELOG.md files updated for non-trivial changes
• Changes in public API reviewed (if applicable)

[opentelemetry-pr-dashboard]

Pull request dashboard status

Merged · refreshed 2026-09-29 12:22 UTC

Status above doesn't look right?

• Anything look wrong? Report it with what you expected; it helps us improve the dashboard.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 91.99%. Comparing base (4b89d68) to head (4a16e81).
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #7780      +/-   ##
==========================================
+ Coverage   91.94%   91.99%   +0.04%     
==========================================
  Files         343      343              
  Lines       18841    18865      +24     
==========================================
+ Hits        17324    17354      +30     
+ Misses       1517     1511       -6     

Flag	Coverage Δ
unittests-Project-Experimental	92.07% <100.00%> (+<0.01%)	⬆️
unittests-Project-Stable	92.07% <100.00%> (-0.01%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
...y/Trace/Builder/TracerProviderBuilderExtensions.cs	100.00% <100.00%> (ø)
...elemetry/Trace/Builder/TracerProviderBuilderSdk.cs	96.42% <100.00%> (+0.20%)	⬆️
src/OpenTelemetry/Trace/TracerProviderSdk.cs	97.77% <100.00%> (+0.06%)	⬆️

... and 6 files with indirect coverage changes

[martincostello]

Just some comments around documentation.

[Kielek]

I understand why such changes might be needed, but before merging, I need to understand what otel-spec is saying about such methods. There is a chance that it should be agreed on the specificiation level first.

Ref: https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/sdk.md#configuration

@pellared, could you please advice here?

[stevejgordon]

No worries! Thanks @Kielek. From a quick reread myself, I don’t believe the spec blocks this API:

• The callback runs only during provider construction; it is not a runtime configuration update.
• The final sampler remains owned by the TracerProvider.
• The configuration spec permits language-idiomatic programmatic mechanisms.
• Java already exposes the equivalent addSamplerCustomizer for this same purpose.

[Kielek]

In general LGTM. It will be great to have also @alanwest opinion as it creates new public API (and it is not so obvious as adding new mandatory Sampler).

Reviewed also with Codex, it states that it might be not obvious what is the precedence between SetSampler/ConfigureSampler/env.vars/other sources for this.

I am dropping here proposed changes, but feel free to fully ignore the wording/tests.

diff --git a/docs/trace/customizing-the-sdk/README.md b/docs/trace/customizing-the-sdk/README.md
index ac126a79c..0fa700694 100644
--- a/docs/trace/customizing-the-sdk/README.md
+++ b/docs/trace/customizing-the-sdk/README.md
@@ -390,10 +390,9 @@ to learn about writing custom samplers.
 
 #### Adjusting the sampler
 
-`SetSampler` sets the sampler unconditionally: any `OTEL_TRACES_SAMPLER` value
-is ignored. This is appropriate for an application that fully controls its own
-configuration, but causes problems for a library that wants to influence
-sampling without affecting any explicit user configuration of the sampler.
+`SetSampler` selects the sampler ahead of any `OTEL_TRACES_SAMPLER` value.
+`ConfigureSampler` callbacks then receive that sampler and can keep, wrap, or
+replace it. A callback can therefore change a sampler selected by `SetSampler`.
 
 `ConfigureSampler` registers a callback which receives the sampler the SDK
 resolved - whether that came from `SetSampler`, from `OTEL_TRACES_SAMPLER`, or
@@ -409,10 +408,11 @@ var tracerProvider = Sdk.CreateTracerProviderBuilder()
     .Build();
 \`\`\`
 
-The callback runs once, while the provider is being built. Registering it several
-times chains the callbacks in registration order, each one receiving the sampler
-returned by the previous one, so several libraries can take part without
-conflicting. Returning `null` or throwing from a callback fails the build.
+The callback runs once, while the provider is being built, regardless of whether
+it was registered before or after `SetSampler`. Registering it several times
+chains the callbacks in registration order, each one receiving the sampler
+returned by the previous one. Returning `null` or throwing from a callback
+fails the build.
 
 When a callback returns a sampler other than the one it was given, the provider
 disposes only the final resolved sampler.
diff --git a/src/OpenTelemetry/CHANGELOG.md b/src/OpenTelemetry/CHANGELOG.md
index b867d32ea..adc9c313f 100644
--- a/src/OpenTelemetry/CHANGELOG.md
+++ b/src/OpenTelemetry/CHANGELOG.md
@@ -10,10 +10,9 @@ Notes](../../RELEASENOTES.md).
   inherited asynchronous execution contexts.
   ([#7803](https://github.com/open-telemetry/opentelemetry-dotnet/pull/7803))
 
-* Added `TracerProviderBuilder.ConfigureSampler` which registers a callback
-  invoked during provider construction with the resolved `Sampler`, allowing the
-  sampler to be wrapped, conditionally replaced, or observed without discarding
-  any sampler configured by the `OTEL_TRACES_SAMPLER` environment variable.
+* Added `TracerProviderBuilder.ConfigureSampler` to adjust the sampler selected by
+  `SetSampler`, `OTEL_TRACES_SAMPLER`, or the default during provider construction.
+  Its callbacks can wrap or replace that sampler.
   ([#7780](https://github.com/open-telemetry/opentelemetry-dotnet/pull/7780))
 
 ## 1.19.1
diff --git a/src/OpenTelemetry/Trace/Builder/TracerProviderBuilderExtensions.cs b/src/OpenTelemetry/Trace/Builder/TracerProviderBuilderExtensions.cs
index fc5373e4d..fea80c91f 100644
--- a/src/OpenTelemetry/Trace/Builder/TracerProviderBuilderExtensions.cs
+++ b/src/OpenTelemetry/Trace/Builder/TracerProviderBuilderExtensions.cs
@@ -52,9 +52,10 @@ public static class TracerProviderBuilderExtensions
     /// <para sampler-precedence="true">Note: A sampler set programmatically
     /// takes precedence over the <c>OTEL_TRACES_SAMPLER</c> environment
     /// variable, which in turn takes precedence over the default sampler
-    /// (<c>ParentBased(AlwaysOnSampler)</c>). To adjust the sampler the SDK
-    /// resolves, instead of overriding it, use
-    /// <see cref="ConfigureSampler(TracerProviderBuilder, Func{IServiceProvider, Sampler, Sampler})"/>.</para>
+    /// (<c>ParentBased(AlwaysOnSampler)</c>).
+    /// <see cref="ConfigureSampler(TracerProviderBuilder, Func{IServiceProvider, Sampler, Sampler})"/>
+    /// callbacks run after this selection and can wrap or replace the sampler,
+    /// regardless of registration order.</para>
     /// </remarks>
     /// <param name="tracerProviderBuilder"><see cref="TracerProviderBuilder"/>.</param>
     /// <param name="sampler">Sampler instance.</param>
@@ -135,9 +136,11 @@ public static class TracerProviderBuilderExtensions
     /// use.
     /// </summary>
     /// <remarks>
-    /// <para>Note: Unlike <see cref="SetSampler(TracerProviderBuilder, Sampler)"/>,
-    /// this method does not discard a sampler configured using the
-    /// <c>OTEL_TRACES_SAMPLER</c> environment variable.</para>
+    /// <para>Callbacks run after the SDK selects a sampler from
+    /// <see cref="SetSampler(TracerProviderBuilder, Sampler)"/>, the
+    /// <c>OTEL_TRACES_SAMPLER</c> environment variable, or the default,
+    /// regardless of whether they are registered before or after
+    /// <c>SetSampler</c>.</para>
     /// <para>The callback is invoked once, while the
     /// <see cref="TracerProvider"/> is being built, and is passed the sampler
     /// which would otherwise have been used. The callback may return the original
diff --git a/test/OpenTelemetry.Tests/Trace/TracerProviderBuilderExtensionsTests.cs b/test/OpenTelemetry.Tests/Trace/TracerProviderBuilderExtensionsTests.cs
index 22a8ee032..3ab8e1b26 100644
--- a/test/OpenTelemetry.Tests/Trace/TracerProviderBuilderExtensionsTests.cs
+++ b/test/OpenTelemetry.Tests/Trace/TracerProviderBuilderExtensionsTests.cs
@@ -642,23 +642,63 @@ public class TracerProviderBuilderExtensionsTests
         Assert.Same(receivedSampler, tracerProvider.Sampler);
     }
 
-    [Fact]
-    public void ConfigureSamplerReceivesSamplerSetProgrammatically()
+    [Theory]
+    [InlineData(false, "instance")]
+    [InlineData(true, "instance")]
+    [InlineData(false, "type")]
+    [InlineData(true, "type")]
+    [InlineData(false, "factory")]
+    [InlineData(true, "factory")]
+    public void ConfigureSamplerOverridesSetSamplerRegardlessOfRegistrationOrder(bool configureSamplerFirst, string setSamplerOverload)
     {
-        var resolvedSampler = new MySampler();
-
+        using var activitySource = new ActivitySource(Utils.GetCurrentMethodName());
         Sampler? receivedSampler = null;
+        var builder = Sdk.CreateTracerProviderBuilder()
+            .AddSource(activitySource.Name)
+            .AddSamplerConfiguration("always_on");
 
-        using var tracerProvider = Sdk.CreateTracerProviderBuilder()
-            .SetSampler(resolvedSampler)
-            .ConfigureSampler((sp, sampler) =>
+        if (configureSamplerFirst)
+        {
+            RegisterConfigurator();
+        }
+
+        switch (setSamplerOverload)
+        {
+            case "instance":
+                builder.SetSampler(new MySampler());
+                break;
+            case "type":
+                builder.SetSampler<MySampler>();
+                break;
+            case "factory":
+                builder.SetSampler(sp => new MySampler());
+                break;
+            default:
+                throw new ArgumentOutOfRangeException(nameof(setSamplerOverload));
+        }
+
+        if (!configureSamplerFirst)
+        {
+            RegisterConfigurator();
+        }
+
+        using var tracerProvider = builder.Build() as TracerProviderSdk;
+
+        Assert.NotNull(tracerProvider);
+        Assert.IsType<MySampler>(receivedSampler);
+        Assert.IsType<AlwaysOffSampler>(tracerProvider.Sampler);
+
+        using var activity = activitySource.StartActivity("Activity");
+
+        Assert.NotNull(activity);
+        Assert.False(activity.Recorded);
+
+        void RegisterConfigurator() =>
+            builder.ConfigureSampler((sp, sampler) =>
             {
                 receivedSampler = sampler;
-                return sampler;
-            })
-            .Build();
-
-        Assert.Same(resolvedSampler, receivedSampler);
+                return new AlwaysOffSampler();
+            });
     }
 
     [Fact]
@@ -734,25 +774,6 @@ public class TracerProviderBuilderExtensionsTests
             messages);
     }
 
-    [Fact]
-    public void ConfigureSamplerReceivesResolvedSamplerWhenRegisteredBeforeSetSampler()
-    {
-        var resolvedSampler = new MySampler();
-
-        Sampler? receivedSampler = null;
-
-        using var tracerProvider = Sdk.CreateTracerProviderBuilder()
-            .ConfigureSampler((sp, sampler) =>
-            {
-                receivedSampler = sampler;
-                return sampler;
-            })
-            .SetSampler(resolvedSampler)
-            .Build();
-
-        Assert.Same(resolvedSampler, receivedSampler);
-    }
-
     [Fact]
     public void ConfigureSamplerReturningInputLeavesSamplerUnchanged()
     {

[stevejgordon]

I am dropping here proposed changes, but feel free to fully ignore the wording/tests.

Thanks, @Kielek. I've applied some of the docs suggestions and refined a couple of them + the improved testing.