factory methods for consistent samplers, avoid exposure of implementa…

…tions

consistent-sampling/src/main/java/io/opentelemetry/contrib/samplers/ConsistentAlwaysOffSampler.java

@@ -9,7 +9,15 @@
 import javax.annotation.concurrent.Immutable;
 
 @Immutable
-public final class ConsistentAlwaysOffSampler extends ConsistentSampler {
+final class ConsistentAlwaysOffSampler extends ConsistentSampler {
+
+  private ConsistentAlwaysOffSampler() {}
+
+  private static final ConsistentSampler INSTANCE = new ConsistentAlwaysOffSampler();
+
+  static ConsistentSampler getInstance() {
+    return INSTANCE;
+  }
 
   @Override
   protected int getP(int parentP, boolean isRoot) {

consistent-sampling/src/main/java/io/opentelemetry/contrib/samplers/ConsistentAlwaysOnSampler.java

@@ -8,7 +8,15 @@
 import javax.annotation.concurrent.Immutable;
 
 @Immutable
-public class ConsistentAlwaysOnSampler extends ConsistentSampler {
+final class ConsistentAlwaysOnSampler extends ConsistentSampler {
+
+  private ConsistentAlwaysOnSampler() {}
+
+  private static final ConsistentSampler INSTANCE = new ConsistentAlwaysOnSampler();
+
+  static ConsistentSampler getInstance() {
+    return INSTANCE;
+  }
 
   @Override
   protected int getP(int parentP, boolean isRoot) {

consistent-sampling/src/main/java/io/opentelemetry/contrib/samplers/ConsistentComposedAndSampler.java

@@ -16,18 +16,13 @@
  * <p>This sampler samples if both samplers would sample.
  */
 @Immutable
-public final class ConsistentComposedAndSampler extends ConsistentSampler {
+final class ConsistentComposedAndSampler extends ConsistentSampler {
 
   private final ConsistentSampler sampler1;
   private final ConsistentSampler sampler2;
   private final String description;
 
-  public static ConsistentComposedAndSampler create(
-      ConsistentSampler sampler1, ConsistentSampler sampler2) {
-    return new ConsistentComposedAndSampler(sampler1, sampler2);
-  }
-
-  private ConsistentComposedAndSampler(ConsistentSampler sampler1, ConsistentSampler sampler2) {
+  ConsistentComposedAndSampler(ConsistentSampler sampler1, ConsistentSampler sampler2) {
     this.sampler1 = requireNonNull(sampler1);
     this.sampler2 = requireNonNull(sampler2);
     this.description =

consistent-sampling/src/main/java/io/opentelemetry/contrib/samplers/ConsistentComposedOrSampler.java

@@ -16,18 +16,13 @@
  * <p>This sampler samples if any of the two samplers would sample.
  */
 @Immutable
-public final class ConsistentComposedOrSampler extends ConsistentSampler {
+final class ConsistentComposedOrSampler extends ConsistentSampler {
 
   private final ConsistentSampler sampler1;
   private final ConsistentSampler sampler2;
   private final String description;
 
-  public static ConsistentComposedOrSampler create(
-      ConsistentSampler sampler1, ConsistentSampler sampler2) {
-    return new ConsistentComposedOrSampler(sampler1, sampler2);
-  }
-
-  private ConsistentComposedOrSampler(ConsistentSampler sampler1, ConsistentSampler sampler2) {
+  ConsistentComposedOrSampler(ConsistentSampler sampler1, ConsistentSampler sampler2) {
     this.sampler1 = requireNonNull(sampler1);
     this.sampler2 = requireNonNull(sampler2);
     this.description =

consistent-sampling/src/main/java/io/opentelemetry/contrib/samplers/ConsistentParentBasedSampler.java

@@ -17,7 +17,7 @@
  * spans).
  */
 @Immutable
-public final class ConsistentParentBasedSampler extends ConsistentSampler {
+final class ConsistentParentBasedSampler extends ConsistentSampler {
 
   private final ConsistentSampler rootSampler;
 
@@ -28,7 +28,7 @@ public final class ConsistentParentBasedSampler extends ConsistentSampler {
    *
    * @param rootSampler the root sampler
    */
-  public ConsistentParentBasedSampler(ConsistentSampler rootSampler) {
+  ConsistentParentBasedSampler(ConsistentSampler rootSampler) {
     this(rootSampler, DefaultRandomGenerator.get());
   }
 
@@ -39,7 +39,7 @@ public ConsistentParentBasedSampler(ConsistentSampler rootSampler) {
    * @param rootSampler the root sampler
    * @param threadSafeRandomGenerator a thread-safe random generator
    */
-  public ConsistentParentBasedSampler(
+  ConsistentParentBasedSampler(
       ConsistentSampler rootSampler, RandomGenerator threadSafeRandomGenerator) {
     super(threadSafeRandomGenerator);
     this.rootSampler = requireNonNull(rootSampler);

consistent-sampling/src/main/java/io/opentelemetry/contrib/samplers/ConsistentProbabilityBasedSampler.java

@@ -11,7 +11,7 @@
 
 /** A consistent sampler that samples with a fixed probability. */
 @Immutable
-public class ConsistentProbabilityBasedSampler extends ConsistentSampler {
+final class ConsistentProbabilityBasedSampler extends ConsistentSampler {
 
   private final int lowerPValue;
   private final int upperPValue;
@@ -23,7 +23,7 @@ public class ConsistentProbabilityBasedSampler extends ConsistentSampler {
    *
    * @param samplingProbability the sampling probability
    */
-  public ConsistentProbabilityBasedSampler(double samplingProbability) {
+  ConsistentProbabilityBasedSampler(double samplingProbability) {
     this(samplingProbability, DefaultRandomGenerator.get());
   }
 
@@ -33,7 +33,7 @@ public ConsistentProbabilityBasedSampler(double samplingProbability) {
    * @param samplingProbability the sampling probability
    * @param threadSafeRandomGenerator a thread-safe random generator
    */
-  public ConsistentProbabilityBasedSampler(
+  ConsistentProbabilityBasedSampler(
       double samplingProbability, RandomGenerator threadSafeRandomGenerator) {
     super(threadSafeRandomGenerator);
     if (samplingProbability < 0.0 || samplingProbability > 1.0) {

consistent-sampling/src/main/java/io/opentelemetry/contrib/samplers/ConsistentRateLimitingSampler.java

@@ -21,7 +21,7 @@
  * J. "Forecasting data published at irregular time intervals using an extension of Holt's method."
  * Management science 32.4 (1986): 499-510.) to estimate the current rate of spans.
  */
-public class ConsistentRateLimitingSampler extends ConsistentSampler {
+final class ConsistentRateLimitingSampler extends ConsistentSampler {
 
   private final String description;
   private final LongSupplier nanoTimeSupplier;
@@ -44,8 +44,7 @@ public class ConsistentRateLimitingSampler extends ConsistentSampler {
    * @param adaptationTimeSeconds the typical time to adapt to a new load (time constant used for
    *     exponential smoothing)
    */
-  public ConsistentRateLimitingSampler(
-      double targetSpansPerSecondLimit, double adaptationTimeSeconds) {
+  ConsistentRateLimitingSampler(double targetSpansPerSecondLimit, double adaptationTimeSeconds) {
     this(
         targetSpansPerSecondLimit,
         adaptationTimeSeconds,
@@ -62,7 +61,7 @@ public ConsistentRateLimitingSampler(
    * @param threadSafeRandomGenerator a thread-safe random generator
    * @param nanoTimeSupplier a supplier for the current nano time
    */
-  public ConsistentRateLimitingSampler(
+  ConsistentRateLimitingSampler(
       double targetSpansPerSecondLimit,
       double adaptationTimeSeconds,
       RandomGenerator threadSafeRandomGenerator,

consistent-sampling/src/main/java/io/opentelemetry/contrib/samplers/ConsistentSampler.java

@@ -21,9 +21,122 @@
 import io.opentelemetry.sdk.trace.samplers.SamplingDecision;
 import io.opentelemetry.sdk.trace.samplers.SamplingResult;
 import java.util.List;
+import java.util.function.LongSupplier;
+import javax.annotation.Nonnull;
 
 /** Abstract base class for consistent samplers. */
-abstract class ConsistentSampler implements Sampler {
+public abstract class ConsistentSampler implements Sampler {
+
+  /**
+   * Returns a {@link ConsistentSampler} that samples all spans.
+   *
+   * @return a sampler
+   */
+  public static final ConsistentSampler alwaysOn() {
+    return ConsistentAlwaysOnSampler.getInstance();
+  }
+
+  /**
+   * Returns a {@link ConsistentSampler} that does not sample any span.
+   *
+   * @return a sampler
+   */
+  public static final ConsistentSampler alwaysOff() {
+    return ConsistentAlwaysOffSampler.getInstance();
+  }
+
+  /**
+   * Returns a {@link ConsistentSampler} that samples each span with a fixed probability.
+   *
+   * @param samplingProbability the sampling probability
+   * @return a sampler
+   */
+  public static final ConsistentSampler probabilityBased(double samplingProbability) {
+    return new ConsistentProbabilityBasedSampler(samplingProbability);
+  }
+
+  /**
+   * Returns a {@link ConsistentSampler} that samples each span with a fixed probability.
+   *
+   * @param samplingProbability the sampling probability
+   * @param threadSafeRandomGenerator a thread-safe random generator
+   * @return a sampler
+   */
+  public static final ConsistentSampler probabilityBased(
+      double samplingProbability, RandomGenerator threadSafeRandomGenerator) {
+    return new ConsistentProbabilityBasedSampler(samplingProbability, threadSafeRandomGenerator);
+  }
+
+  /**
+   * Returns a new {@link ConsistentSampler} that respects the sampling decision of the parent span
+   * or falls-back to the given sampler if it is a root span.
+   *
+   * @param rootSampler the root sampler
+   */
+  public static final ConsistentSampler parentBased(@Nonnull ConsistentSampler rootSampler) {
+    return new ConsistentParentBasedSampler(rootSampler);
+  }
+
+  /**
+   * Returns a new {@link ConsistentSampler} that respects the sampling decision of the parent span
+   * or falls-back to the given sampler if it is a root span.
+   *
+   * @param rootSampler the root sampler
+   * @param threadSafeRandomGenerator a thread-safe random generator
+   */
+  public static final ConsistentSampler parentBased(
+      ConsistentSampler rootSampler, RandomGenerator threadSafeRandomGenerator) {
+    return new ConsistentParentBasedSampler(rootSampler, threadSafeRandomGenerator);
+  }
+
+  /**
+   * Returns a new {@link ConsistentSampler} that attempts to adjust the sampling probability
+   * dynamically to meet the target span rate.
+   *
+   * @param targetSpansPerSecondLimit the desired spans per second limit
+   * @param adaptationTimeSeconds the typical time to adapt to a new load (time constant used for
+   *     exponential smoothing)
+   */
+  public static final ConsistentSampler rateLimited(
+      double targetSpansPerSecondLimit, double adaptationTimeSeconds) {
+    return new ConsistentRateLimitingSampler(targetSpansPerSecondLimit, adaptationTimeSeconds);
+  }
+
+  /**
+   * Returns a new {@link ConsistentSampler} that attempts to adjust the sampling probability
+   * dynamically to meet the target span rate.
+   *
+   * @param targetSpansPerSecondLimit the desired spans per second limit
+   * @param adaptationTimeSeconds the typical time to adapt to a new load (time constant used for
+   *     exponential smoothing)
+   * @param threadSafeRandomGenerator a thread-safe random generator
+   * @param nanoTimeSupplier a supplier for the current nano time
+   */
+  public static final ConsistentSampler rateLimited(
+      double targetSpansPerSecondLimit,
+      double adaptationTimeSeconds,
+      RandomGenerator threadSafeRandomGenerator,
+      LongSupplier nanoTimeSupplier) {
+    return new ConsistentRateLimitingSampler(
+        targetSpansPerSecondLimit,
+        adaptationTimeSeconds,
+        threadSafeRandomGenerator,
+        nanoTimeSupplier);
+  }
+
+  public ConsistentSampler and(ConsistentSampler otherConsistentSampler) {
+    if (otherConsistentSampler == this) {
+      return this;
+    }
+    return new ConsistentComposedAndSampler(this, otherConsistentSampler);
+  }
+
+  public ConsistentSampler or(ConsistentSampler otherConsistentSampler) {
+    if (otherConsistentSampler == this) {
+      return this;
+    }
+    return new ConsistentComposedOrSampler(this, otherConsistentSampler);
+  }
 
   protected final RandomGenerator threadSafeRandomGenerator;
 

consistent-sampling/src/test/java/io/opentelemetry/contrib/export/ConsistentReservoirSamplingBatchSpanProcessorTest.java

@@ -21,8 +21,7 @@
 import io.opentelemetry.api.internal.GuardedBy;
 import io.opentelemetry.api.trace.Span;
 import io.opentelemetry.api.trace.Tracer;
-import io.opentelemetry.contrib.samplers.ConsistentAlwaysOnSampler;
-import io.opentelemetry.contrib.samplers.ConsistentProbabilityBasedSampler;
+import io.opentelemetry.contrib.samplers.ConsistentSampler;
 import io.opentelemetry.contrib.state.OtelTraceState;
 import io.opentelemetry.contrib.util.RandomGenerator;
 import io.opentelemetry.sdk.common.CompletableResultCode;
@@ -729,7 +728,7 @@ void exportDifferentConsistentlySampledSpans() {
 
     sdkTracerProvider =
         SdkTracerProvider.builder()
-            .setSampler(new ConsistentAlwaysOnSampler())
+            .setSampler(ConsistentSampler.alwaysOn())
             .addSpanProcessor(spanProcessor)
             .build();
 
@@ -791,8 +790,7 @@ private void testConsistentSampling(
     sdkTracerProvider =
         SdkTracerProvider.builder()
             .setSampler(
-                new ConsistentProbabilityBasedSampler(
-                    samplingProbability, threadSafeRandomGenerator2))
+                ConsistentSampler.probabilityBased(samplingProbability, threadSafeRandomGenerator2))
             .addSpanProcessor(spanProcessor)
             .build();
 
@@ -1013,8 +1011,7 @@ private StatisticalSummary calculateStatisticalSummary(
     sdkTracerProvider =
         SdkTracerProvider.builder()
             .setSampler(
-                new ConsistentProbabilityBasedSampler(
-                    samplingProbability, threadSafeRandomGenerator2))
+                ConsistentSampler.probabilityBased(samplingProbability, threadSafeRandomGenerator2))
             .addSpanProcessor(spanProcessor)
             .build();
 

consistent-sampling/src/test/java/io/opentelemetry/contrib/samplers/ConsistentProbabilityBasedSamplerTest.java

@@ -48,7 +48,7 @@ public void init() {
   private void test(SplittableRandom rng, double samplingProbability) {
     int numSpans = 1000000;
 
-    Sampler sampler = new ConsistentProbabilityBasedSampler(samplingProbability, rng::nextLong);
+    Sampler sampler = ConsistentSampler.probabilityBased(samplingProbability, rng::nextLong);
 
     Map<Integer, Long> observedPvalues = new HashMap<>();
     for (long i = 0; i < numSpans; ++i) {

consistent-sampling/src/test/java/io/opentelemetry/contrib/samplers/ConsistentRateLimitingSamplerTest.java

@@ -61,8 +61,8 @@ void testConstantRate() {
     double adaptationTimeSeconds = 5;
     SplittableRandom random = new SplittableRandom(0L);
 
-    ConsistentRateLimitingSampler sampler =
-        new ConsistentRateLimitingSampler(
+    ConsistentSampler sampler =
+        ConsistentSampler.rateLimited(
             targetSpansPerSecondLimit, adaptationTimeSeconds, random::nextLong, nanoTimeSupplier);
 
     long nanosBetweenSpans = TimeUnit.MICROSECONDS.toNanos(100);
@@ -95,8 +95,8 @@ void testRateIncrease() {
     double adaptationTimeSeconds = 5;
     SplittableRandom random = new SplittableRandom(0L);
 
-    ConsistentRateLimitingSampler sampler =
-        new ConsistentRateLimitingSampler(
+    ConsistentSampler sampler =
+        ConsistentSampler.rateLimited(
             targetSpansPerSecondLimit, adaptationTimeSeconds, random::nextLong, nanoTimeSupplier);
 
     long nanosBetweenSpans1 = TimeUnit.MICROSECONDS.toNanos(100);
@@ -151,8 +151,8 @@ void testRateDecrease() {
     double adaptationTimeSeconds = 5;
     SplittableRandom random = new SplittableRandom(0L);
 
-    ConsistentRateLimitingSampler sampler =
-        new ConsistentRateLimitingSampler(
+    ConsistentSampler sampler =
+        ConsistentSampler.rateLimited(
             targetSpansPerSecondLimit, adaptationTimeSeconds, random::nextLong, nanoTimeSupplier);
 
     long nanosBetweenSpans1 = TimeUnit.MICROSECONDS.toNanos(10);