feat(trace): support runtime sampler updates

sdk/trace/src/main/java/io/opentelemetry/sdk/trace/SdkTracerProvider.java

@@ -21,6 +21,7 @@
 import io.opentelemetry.sdk.trace.samplers.Sampler;
 import java.io.Closeable;
 import java.util.List;
+import java.util.Objects;
 import java.util.concurrent.TimeUnit;
 import java.util.function.Supplier;
 import java.util.logging.Level;
@@ -109,6 +110,18 @@ public SpanLimits getSpanLimits() {
     return sharedState.getSpanLimits();
   }
 
+  /**
+   * Updates the sampler used for new spans.
+   *
+   * <p>The {@code sampler} must be thread-safe and return immediately (no remote calls, as
+   * contention free as possible).
+   *
+   * @param sampler the sampler to use for sampling new spans.
+   */
+  public void setSampler(Sampler sampler) {
+    sharedState.setSampler(Objects.requireNonNull(sampler, "sampler"));
+  }
+
   /** Returns the configured {@link Sampler}. */
   public Sampler getSampler() {
     return sharedState.getSampler();

sdk/trace/src/main/java/io/opentelemetry/sdk/trace/TracerSharedState.java

@@ -26,7 +26,7 @@ final class TracerSharedState {
   private final Resource resource;
 
   private final Supplier<SpanLimits> spanLimitsSupplier;
-  private final Sampler sampler;
+  private volatile Sampler sampler;
   private final SpanProcessor activeSpanProcessor;
   private final ExceptionAttributeResolver exceptionAttributeResolver;
   private final SdkTracerInstrumentation tracerInstrumentation;
@@ -74,11 +74,24 @@ SpanLimits getSpanLimits() {
     return spanLimitsSupplier.get();
   }
 
-  /** Returns the configured {@link Sampler}. */
+  /** Returns the currently configured {@link Sampler}. */
   Sampler getSampler() {
     return sampler;
   }
 
+  void setSampler(Sampler sampler) {
+    synchronized (lock) {
+      if (shutdownResult != null) {
+        sampler.shutdown();
+        return;
+      }
+
+      Sampler previousSampler = this.sampler;
+      this.sampler = sampler;
+      previousSampler.shutdown();
+    }
+  }
+
   /**
    * Returns the active {@code SpanProcessor}.
    *

sdk/trace/src/test/java/io/opentelemetry/sdk/trace/SdkTracerProviderTest.java

@@ -14,6 +14,7 @@
 import static org.mockito.Mockito.spy;
 import static org.mockito.Mockito.verify;
 import static org.mockito.Mockito.when;
+import static org.mockito.Mockito.never;
 
 import io.opentelemetry.api.common.Attributes;
 import io.opentelemetry.api.trace.Span;
@@ -87,6 +88,85 @@ void builder_configureSampler_null() {
         .hasMessage("sampler");
   }
 
+  @Test
+  void setSampler() {
+    SdkTracerProvider tracerProvider =
+        SdkTracerProvider.builder().setSampler(Sampler.alwaysOn()).build();
+
+    assertThat(tracerProvider.getSampler()).isEqualTo(Sampler.alwaysOn());
+
+    tracerProvider.setSampler(Sampler.alwaysOff());
+
+    assertThat(tracerProvider.getSampler()).isEqualTo(Sampler.alwaysOff());
+  }
+
+  @Test
+  void setSampler_null() {
+    SdkTracerProvider tracerProvider = SdkTracerProvider.builder().build();
+
+    assertThatThrownBy(() -> tracerProvider.setSampler(null))
+        .isInstanceOf(NullPointerException.class)
+        .hasMessage("sampler");
+  }
+
+  @Test
+  void setSampler_affectsExistingTracer() {
+    SdkTracerProvider tracerProvider =
+        SdkTracerProvider.builder().setSampler(Sampler.alwaysOff()).build();
+
+    Tracer tracer = tracerProvider.get("test");
+
+    Span firstSpan = tracer.spanBuilder("first").startSpan();
+    assertThat(firstSpan.getSpanContext().isSampled()).isFalse();
+    firstSpan.end();
+
+    tracerProvider.setSampler(Sampler.alwaysOn());
+
+    Span secondSpan = tracer.spanBuilder("second").startSpan();
+    assertThat(secondSpan.getSpanContext().isSampled()).isTrue();
+    secondSpan.end();
+  }
+
+  @Test
+  void setSampler_shutsDownPreviousSampler() {
+    Sampler firstSampler = mock(Sampler.class);
+    Sampler secondSampler = mock(Sampler.class);
+
+    when(firstSampler.shutdown()).thenReturn(CompletableResultCode.ofSuccess());
+    when(secondSampler.shutdown()).thenReturn(CompletableResultCode.ofSuccess());
+
+    SdkTracerProvider tracerProvider =
+        SdkTracerProvider.builder().setSampler(firstSampler).build();
+
+    tracerProvider.setSampler(secondSampler);
+
+    verify(firstSampler).shutdown();
+    verify(secondSampler, never()).shutdown();
+
+    tracerProvider.shutdown();
+
+    verify(secondSampler).shutdown();
+  }
+
+  @Test
+  void setSampler_afterShutdown_shutsDownNewSampler() {
+    Sampler initialSampler = mock(Sampler.class);
+    Sampler newSampler = mock(Sampler.class);
+
+    when(initialSampler.shutdown()).thenReturn(CompletableResultCode.ofSuccess());
+    when(newSampler.shutdown()).thenReturn(CompletableResultCode.ofSuccess());
+
+    SdkTracerProvider tracerProvider =
+        SdkTracerProvider.builder().setSampler(initialSampler).build();
+
+    tracerProvider.shutdown();
+    verify(initialSampler).shutdown();
+
+    tracerProvider.setSampler(newSampler);
+
+    verify(newSampler).shutdown();
+  }
+
   @Test
   void builder_serviceNameProvided() {
     Resource resource =