consistent-sampling: rebase on upstream ComposableSampler API

Rewrites the consistent-sampling module on top of the composable-samplers API in opentelemetry-sdk-extension-incubator. The legacy OTEP 4673 probability samplers are removed, the consistent56 package is promoted into io.opentelemetry.contrib.sampler.consistent, and classes that duplicated upstream functionality are dropped. The remaining ConsistentRateLimitingSampler, ConsistentVariableThresholdSampler, and ConsistentAnyOf now implement upstream ComposableSampler. ConsistentReservoirSamplingSpanProcessor and the parentbased_consistent_probability autoconfigure provider are retained; the provider now delegates to CompositeSampler.wrap(ComposableSampler.parentThreshold(ComposableSampler.probability(p))).

Author: trask

CHANGELOG.md

@@ -2,6 +2,40 @@
 
 ## Unreleased
 
+### Consistent sampling
+
+- **Breaking change**: the legacy OTEP 4673 probability samplers in the
+  `io.opentelemetry.contrib.sampler.consistent` package
+  (`ConsistentProbabilityBasedSampler`, `ConsistentComposedAnd/OrSampler`,
+  and the legacy `ConsistentAlwaysOn/OffSampler` / `ConsistentParentBasedSampler`
+  factories on `ConsistentSampler`) have been removed.
+- `ConsistentReservoirSamplingSpanProcessor` and the
+  `parentbased_consistent_probability` autoconfigure sampler name are retained.
+  The autoconfigure provider now builds its sampler on top of the upstream
+  `ComposableSampler` / `CompositeSampler` API; the resulting behavior is
+  equivalent to `CompositeSampler.wrap(ComposableSampler.parentThreshold(ComposableSampler.probability(p)))`.
+- **Breaking change**: the `consistent56` package has been rewritten on top of
+  the upstream `opentelemetry-sdk-extension-incubator` composable-samplers API
+  and promoted to the `io.opentelemetry.contrib.sampler.consistent` package
+  name. Classes that duplicated upstream functionality (`Composable`,
+  `SamplingIntent`, `ConsistentAlwaysOn/OffSampler`,
+  `ConsistentFixedThresholdSampler`, `ConsistentParentBasedSampler`,
+  `ConsistentRuleBasedSampler`, `RandomValueGenerator(s)`,
+  `Predicate`/`PredicatedSampler`) have been removed. The remaining
+  `ConsistentRateLimitingSampler`, `ConsistentVariableThresholdSampler`, and
+  `ConsistentAnyOf` now implement the upstream
+  `io.opentelemetry.sdk.extension.incubator.trace.samplers.ComposableSampler`
+  interface. Use `CompositeSampler.wrap(composable)` to turn a composable
+  sampler into a `Sampler`, and use `ComposableSampler`'s static factories
+  (`alwaysOn`, `alwaysOff`, `probability`, `parentThreshold`, …) directly
+  instead of the removed `ConsistentSampler.alwaysOn/alwaysOff/probabilityBased/parentBased/asSampler`.
+  Migration mapping:
+  - `ConsistentSampler.alwaysOn()` → `ComposableSampler.alwaysOn()`
+  - `ConsistentSampler.alwaysOff()` → `ComposableSampler.alwaysOff()`
+  - `ConsistentSampler.probabilityBased(p)` → `ComposableSampler.probability(p)`
+  - `ConsistentSampler.parentBased(root)` → `ComposableSampler.parentThreshold(root)`
+  - `ConsistentSampler.asSampler(c)` → `CompositeSampler.wrap(c)`
+
 ## Version 1.55.0 (2026-03-31)
 
 ### Disk buffering
@@ -220,7 +254,6 @@ an issue if this causes problems.
 - Add declarative configuration support
   ([#2262](https://github.com/open-telemetry/opentelemetry-java-contrib/pull/2262))
 
-
 ## Version 1.49.0 (2025-08-25)
 
 ### Consistent sampling
@@ -870,7 +903,7 @@ which can be sent later on demand.
 
 - JFR connection is a library to allow configuration and control of JFR
   without depending on jdk.jfr.
-  This is a contribution of https://github.com/microsoft/jfr-streaming.
+  This is a contribution of <https://github.com/microsoft/jfr-streaming>.
 
 ## Version 1.24.0 (2023-04-03)
 
@@ -1052,8 +1085,8 @@ All components updated to target OpenTelemetry SDK 1.13.0.
 ### Consistent sampling - New 🌟
 
 This component adds various Sampler implementations for consistent sampling as defined by
-https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/tracestate-probability-sampling.md
-and https://github.com/open-telemetry/opentelemetry-specification/pull/2047.
+<https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/tracestate-probability-sampling.md>
+and <https://github.com/open-telemetry/opentelemetry-specification/pull/2047>.
 
 ## Version 1.12.0 (2022-03-14)
 

consistent-sampling/README.md

@@ -1,59 +1,51 @@
 # Consistent sampling
 
-There are two major components included here.
-
-## Original proposal implementation
-
-The original specification for consistent probability sampling is defined by
-<https://github.com/open-telemetry/opentelemetry-specification/blob/main/oteps/trace/4673-experimental-probability-sampling.md>
-and <https://github.com/open-telemetry/opentelemetry-specification/pull/2047>.
-It supports sampling probabilities that are power of 2 (1, 1/2, 1/4, ...), and uses 8-bit `r-value` and 8-bit `p-value` in tracestate.
-
-The implementation of this proposal is contained by the package `io/opentelemetry/contrib/sampler/consistent` in this repository and provides various Sampler implementations.
-
-* **ConsistentSampler**:
-  abstract base class of all consistent sampler implementations below
-* **ConsistentAlwaysOffSampler**:
-  see <https://github.com/open-telemetry/opentelemetry-specification/blob/main/oteps/trace/4673-experimental-probability-sampling.md#always-off-sampler>
-* **ConsistentAlwaysOnSampler**:
-  see <https://github.com/open-telemetry/opentelemetry-specification/blob/main/oteps/trace/4673-experimental-probability-sampling.md#always-on-consistent-probability-sampler>
-* **ConsistentComposedAndSampler**:
-  allows combining two consistent samplers and samples when both samplers would sample
-* **ConsistentComposedOrSampler**:
-  allows combining two consistent sampler and samples when at least one of both samplers would sample,
-  see <https://github.com/open-telemetry/opentelemetry-specification/blob/main/oteps/trace/4673-experimental-probability-sampling.md#requirement-combine-multiple-consistent-probability-samplers-using-the-minimum-p-value>
-* **ConsistentParentBasedSampler**:
-  see <https://github.com/open-telemetry/opentelemetry-specification/blob/main/oteps/trace/4673-experimental-probability-sampling.md#parentconsistentprobabilitybased-sampler>
-* **ConsistentProbabilityBasedSampler**:
-  see <https://github.com/open-telemetry/opentelemetry-specification/blob/main/oteps/trace/4673-experimental-probability-sampling.md#consistentprobabilitybased-sampler>
-* **ConsistentRateLimitingSampler**:
-  a rate limiting sampler based on exponential smoothing that dynamically adjusts the sampling
-  probability based on the estimated rate of spans occurring to satisfy a given rate of sampled spans
-
-## Current proposal implementation
-
-The current version of the specification for consistent probability sampling is described by
+This module implements the current specification for consistent probability
+sampling described by
 <https://github.com/open-telemetry/oteps/blob/main/text/trace/0235-sampling-threshold-in-trace-state.md>.
-It uses **56** bits for representing _rejection threshold_, which corresponds to a much wider range of sampling probabilities than the original proposal.
-
-The implementation of the current proposal is contained by the package `io/opentelemetry/contrib/sampler/consistent56` in this repository and provides implementation for a number of different Samplers.
-
-* **ConsistentSampler**
-  abstract base class for all consistent sampler implementations
-* **ComposableSampler**:
-  interface used to build hierarchies of Samplers, see [Composite Samplers](https://github.com/open-telemetry/oteps/pull/250)
-* **ConsistentAlwaysOffSampler**:
-* **ConsistentAlwaysOnSampler**:
-* **ConsistentAnyOfSampler**:
-  allows combining several consistent samplers; it samples when at least one of them would sample,
-* **ConsistentParentBasedSampler**:
-* **ConsistentFixedThresholdSampler**:
-  consistent probability sampler that uses a predefined sampling probability
+It uses **56** bits for representing the _rejection threshold_, which
+corresponds to a much wider range of sampling probabilities than the original
+OTEP&nbsp;4673 proposal.
+
+The reference implementation of composable samplers now lives upstream in
+[`opentelemetry-java`](https://github.com/open-telemetry/opentelemetry-java)
+under the `opentelemetry-sdk-extension-incubator` module, in the package
+`io.opentelemetry.sdk.extension.incubator.trace.samplers`. That package provides
+`ComposableSampler` (including the static factories `alwaysOn()`, `alwaysOff()`,
+`probability(ratio)`, `parentThreshold(rootSampler)`, `ruleBasedBuilder()`,
+`annotating(sampler, attributes)`) and `CompositeSampler.wrap(ComposableSampler)`
+for turning a composable sampler into a `Sampler`.
+
+The package `io.opentelemetry.contrib.sampler.consistent` in this repository
+adds the following samplers on top of the upstream incubator:
+
 * **ConsistentRateLimitingSampler**:
   a rate limiting sampler based on exponential smoothing that dynamically adjusts the sampling
   probability based on the estimated rate of spans occurring to satisfy a given rate of sampled spans
-* **ConsistentRuleBasedSampler**
-  a sampler that performs stratified sampling by evaluating qualifying conditions and propagating the sampling decision from one of its delegate samplers
+* **ConsistentVariableThresholdSampler**:
+  a consistent probability sampler whose sampling probability can be updated at runtime
+* **ConsistentAnyOf**:
+  allows combining several composable samplers; it samples when at least one of them would sample
+* **ConsistentReservoirSamplingSpanProcessor**:
+  a `SpanProcessor` that buffers ended spans and, if more spans arrive in a
+  period than the configured reservoir size, consistently down-samples the
+  buffer before export
+
+The `ConsistentSampler` class is a convenience factory for the contrib-only
+samplers above. For the common samplers use `ComposableSampler`'s static
+factories directly.
+
+## Autoconfigure
+
+This module registers the `parentbased_consistent_probability` sampler name for
+the OpenTelemetry autoconfigure SDK, equivalent to
+`CompositeSampler.wrap(ComposableSampler.parentThreshold(ComposableSampler.probability(arg)))`.
+Use it via:
+
+```
+OTEL_TRACES_SAMPLER=parentbased_consistent_probability
+OTEL_TRACES_SAMPLER_ARG=0.1
+```
 
 ## Component owners
 

consistent-sampling/build.gradle.kts

@@ -9,8 +9,9 @@ otelJava.moduleName.set("io.opentelemetry.contrib.sampler")
 dependencies {
   api("io.opentelemetry:opentelemetry-sdk-trace")
   api("io.opentelemetry:opentelemetry-sdk-extension-autoconfigure-spi")
-  testImplementation("org.hipparchus:hipparchus-core:4.0.3")
-  testImplementation("org.hipparchus:hipparchus-stat:4.0.3")
+  api("io.opentelemetry:opentelemetry-sdk-extension-incubator")
+
+  testImplementation("io.opentelemetry:opentelemetry-sdk-testing")
 }
 
 tasks {

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

@@ -3,18 +3,21 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-package io.opentelemetry.contrib.sampler.consistent56;
+package io.opentelemetry.contrib.sampler.consistent;
 
-import static io.opentelemetry.contrib.sampler.consistent56.ConsistentSamplingUtil.getInvalidThreshold;
-import static io.opentelemetry.contrib.sampler.consistent56.ConsistentSamplingUtil.isValidThreshold;
+import static io.opentelemetry.contrib.sampler.consistent.ConsistentSamplingUtil.INVALID_THRESHOLD;
+import static io.opentelemetry.contrib.sampler.consistent.ConsistentSamplingUtil.isValidThreshold;
 
 import io.opentelemetry.api.common.Attributes;
 import io.opentelemetry.api.common.AttributesBuilder;
 import io.opentelemetry.api.trace.SpanKind;
 import io.opentelemetry.api.trace.TraceState;
 import io.opentelemetry.context.Context;
+import io.opentelemetry.sdk.extension.incubator.trace.samplers.ComposableSampler;
+import io.opentelemetry.sdk.extension.incubator.trace.samplers.SamplingIntent;
 import io.opentelemetry.sdk.trace.data.LinkData;
 import java.util.List;
+import java.util.function.Function;
 import java.util.stream.Collectors;
 import java.util.stream.Stream;
 import javax.annotation.Nullable;
@@ -25,18 +28,12 @@
  * uses the minimum threshold value received.
  */
 @Immutable
-final class ConsistentAnyOf extends ConsistentSampler {
-
-  private final Composable[] delegates;
+final class ConsistentAnyOf implements ComposableSampler {
 
+  private final ComposableSampler[] delegates;
   private final String description;
 
-  /**
-   * Constructs a new consistent AnyOf sampler using the provided delegate samplers.
-   *
-   * @param delegates the delegate samplers
-   */
-  ConsistentAnyOf(@Nullable Composable... delegates) {
+  ConsistentAnyOf(@Nullable ComposableSampler... delegates) {
     if (delegates == null || delegates.length == 0) {
       throw new IllegalArgumentException(
           "At least one delegate must be specified for ConsistentAnyOf");
@@ -46,13 +43,14 @@ final class ConsistentAnyOf extends ConsistentSampler {
 
     this.description =
         Stream.of(delegates)
-            .map(Object::toString)
+            .map(ComposableSampler::getDescription)
             .collect(Collectors.joining(",", "ConsistentAnyOf{", "}"));
   }
 
   @Override
   public SamplingIntent getSamplingIntent(
       Context parentContext,
+      String traceId,
       String name,
       SpanKind spanKind,
       Attributes attributes,
@@ -62,67 +60,53 @@ public SamplingIntent getSamplingIntent(
 
     // If any of the delegates provides a valid threshold, the resulting threshold is the minimum
     // value T from the set of those valid threshold values, otherwise it is invalid threshold.
-    long minimumThreshold = getInvalidThreshold();
+    long minimumThreshold = INVALID_THRESHOLD;
 
     // If any of the delegates returning the threshold value equal to T returns true upon calling
-    // its IsAdjustedCountReliable() method, the resulting isAdjustedCountReliable is true,
+    // its isThresholdReliable() method, the resulting thresholdReliable is true,
     // otherwise it is false.
-    boolean isAdjustedCountCorrect = false;
+    boolean thresholdReliable = false;
 
     int k = 0;
-    for (Composable delegate : delegates) {
+    for (ComposableSampler delegate : delegates) {
       SamplingIntent delegateIntent =
-          delegate.getSamplingIntent(parentContext, name, spanKind, attributes, parentLinks);
+          delegate.getSamplingIntent(
+              parentContext, traceId, name, spanKind, attributes, parentLinks);
       long delegateThreshold = delegateIntent.getThreshold();
       if (isValidThreshold(delegateThreshold)) {
         if (isValidThreshold(minimumThreshold)) {
           if (delegateThreshold == minimumThreshold) {
-            if (delegateIntent.isAdjustedCountReliable()) {
-              isAdjustedCountCorrect = true;
+            if (delegateIntent.isThresholdReliable()) {
+              thresholdReliable = true;
             }
           } else if (delegateThreshold < minimumThreshold) {
             minimumThreshold = delegateThreshold;
-            isAdjustedCountCorrect = delegateIntent.isAdjustedCountReliable();
+            thresholdReliable = delegateIntent.isThresholdReliable();
           }
         } else {
           minimumThreshold = delegateThreshold;
-          isAdjustedCountCorrect = delegateIntent.isAdjustedCountReliable();
+          thresholdReliable = delegateIntent.isThresholdReliable();
         }
       }
       intents[k++] = delegateIntent;
     }
 
-    long resultingThreshold = minimumThreshold;
-    boolean isResultingAdjustedCountCorrect = isAdjustedCountCorrect;
-
-    return new SamplingIntent() {
-      @Override
-      public long getThreshold() {
-        return resultingThreshold;
-      }
-
-      @Override
-      public boolean isAdjustedCountReliable() {
-        return isResultingAdjustedCountCorrect;
-      }
+    AttributesBuilder builder = Attributes.builder();
+    for (SamplingIntent intent : intents) {
+      builder = builder.putAll(intent.getAttributes());
+    }
+    Attributes mergedAttributes = builder.build();
 
-      @Override
-      public Attributes getAttributes() {
-        AttributesBuilder builder = Attributes.builder();
-        for (SamplingIntent intent : intents) {
-          builder = builder.putAll(intent.getAttributes());
-        }
-        return builder.build();
-      }
+    Function<TraceState, TraceState> composed =
+        s -> {
+          TraceState state = s;
+          for (SamplingIntent intent : intents) {
+            state = intent.getTraceStateUpdater().apply(state);
+          }
+          return state;
+        };
 
-      @Override
-      public TraceState updateTraceState(TraceState previousState) {
-        for (SamplingIntent intent : intents) {
-          previousState = intent.updateTraceState(previousState);
-        }
-        return previousState;
-      }
-    };
+    return SamplingIntent.create(minimumThreshold, thresholdReliable, mergedAttributes, composed);
   }
 
   @Override