Repository navigation
Introduce a ConfigureSampler API - #7780
Conversation
Pull request dashboard statusMerged · refreshed 2026-09-29 12:22 UTC Status above doesn't look right?
|
Codecov Report✅ All modified and coverable lines are covered by tests. 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
Flags with carried forward coverage won't be shown. Click here to find out more.
|
martincostello
left a comment
There was a problem hiding this comment.
Just some comments around documentation.
…s.cs Co-authored-by: Martin Costello <martin@martincostello.com>
|
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. @pellared, could you please advice here? |
|
No worries! Thanks @Kielek. From a quick reread myself, I don’t believe the spec blocks this API:
|
There was a problem hiding this comment.
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()
{
Thanks, @Kielek. I've applied some of the docs suggestions and refined a couple of them + the improved testing. |
Relates to #7192
Changes
Introduces
ConfigureSampleron theTracerProviderSdk.Today the only way to influence the SDK's sampler is
SetSampler, which wins outright: when a programmatic sampler is present, the user'sOTEL_TRACES_SAMPLERvalue 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).ConfigureSamplerregisters 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 hasSetResourceBuilder,ConfigureResourceandGetResource, all stable, and the signature is the existing stableSetSampler(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, viaSetSamplerwith 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
GetSamplerin this PR as it adds less value. A type check would be needed to access which specificSamplerimplementation 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
CHANGELOG.mdfiles updated for non-trivial changes