Cleanup and match spec better

Author: anuraaga

CHANGELOG.md

@@ -7,7 +7,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## Unreleased
 
-- Add experimental consistent samplers
+- Add experimental composite samplers
   ([#4714](https://github.com/open-telemetry/opentelemetry-python/pull/4714))
 
 ## Version 1.36.0/0.57b0 (2025-07-29)

opentelemetry-sdk/src/opentelemetry/sdk/trace/_sampling_experimental/__init__.py

@@ -1,17 +1,31 @@
+# Copyright The OpenTelemetry Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
 __all__ = [
     "ComposableSampler",
-    "ConsistentSampler",
     "SamplingIntent",
-    "consistent_always_off",
-    "consistent_always_on",
-    "consistent_parent_based",
-    "consistent_probability_based",
+    "composable_always_off",
+    "composable_always_on",
+    "composable_parent_threshold",
+    "composable_traceid_ratio_based",
+    "composite_sampler",
 ]
 
 
-from ._always_off import consistent_always_off
-from ._always_on import consistent_always_on
+from ._always_off import composable_always_off
+from ._always_on import composable_always_on
 from ._composable import ComposableSampler, SamplingIntent
-from ._fixed_threshold import consistent_probability_based
-from ._parent_based import consistent_parent_based
-from ._sampler import ConsistentSampler
+from ._parent_threshold import composable_parent_threshold
+from ._sampler import composite_sampler
+from ._traceid_ratio import composable_traceid_ratio_based

opentelemetry-sdk/src/opentelemetry/sdk/trace/_sampling_experimental/_always_off.py

@@ -1,37 +1,55 @@
-from typing import Optional, Sequence
+# Copyright The OpenTelemetry Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from __future__ import annotations
+
+from typing import Sequence
 
 from opentelemetry.context import Context
 from opentelemetry.trace import Link, SpanKind, TraceState
 from opentelemetry.util.types import Attributes
 
 from ._composable import ComposableSampler, SamplingIntent
-from ._sampler import ConsistentSampler
 from ._util import INVALID_THRESHOLD
 
-_intent = SamplingIntent(
-    threshold=INVALID_THRESHOLD, adjusted_count_reliable=False
-)
+_intent = SamplingIntent(threshold=INVALID_THRESHOLD, threshold_reliable=False)
 
 
-class ConsistentAlwaysOffSampler(ComposableSampler):
+class _ComposableAlwaysOffSampler(ComposableSampler):
     def sampling_intent(
         self,
-        parent_ctx: Optional[Context],
+        parent_ctx: Context | None,
         name: str,
-        span_kind: Optional[SpanKind],
+        span_kind: SpanKind | None,
         attributes: Attributes,
-        links: Optional[Sequence[Link]],
-        trace_state: Optional[TraceState] = None,
+        links: Sequence[Link] | None,
+        trace_state: TraceState | None = None,
     ) -> SamplingIntent:
         return _intent
 
     def get_description(self) -> str:
-        return "ConsistentAlwaysOffSampler"
+        return "ComposableAlwaysOff"
 
 
-_always_off = ConsistentSampler(ConsistentAlwaysOffSampler())
+_always_off = _ComposableAlwaysOffSampler()
 
 
-def consistent_always_off() -> ConsistentSampler:
-    """Returns a consistent sampler that does not sample any span."""
+def composable_always_off() -> ComposableSampler:
+    """Returns a composable sampler that does not sample any span.
+
+    - Always returns a SamplingIntent with no threshold, indicating all spans should be dropped
+    - Sets threshold_reliable to false
+    - Does not add any attributes
+    """
     return _always_off

opentelemetry-sdk/src/opentelemetry/sdk/trace/_sampling_experimental/_always_on.py

@@ -1,35 +1,55 @@
-from typing import Optional, Sequence
+# Copyright The OpenTelemetry Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from __future__ import annotations
+
+from typing import Sequence
 
 from opentelemetry.context import Context
 from opentelemetry.trace import Link, SpanKind, TraceState
 from opentelemetry.util.types import Attributes
 
 from ._composable import ComposableSampler, SamplingIntent
-from ._sampler import ConsistentSampler
 from ._util import MIN_THRESHOLD
 
 _intent = SamplingIntent(threshold=MIN_THRESHOLD)
 
 
-class ConsistentAlwaysOnSampler(ComposableSampler):
+class _ComposableAlwaysOnSampler(ComposableSampler):
     def sampling_intent(
         self,
-        parent_ctx: Optional[Context],
+        parent_ctx: Context | None,
         name: str,
-        span_kind: Optional[SpanKind],
+        span_kind: SpanKind | None,
         attributes: Attributes,
-        links: Optional[Sequence[Link]],
-        trace_state: Optional[TraceState] = None,
+        links: Sequence[Link] | None,
+        trace_state: TraceState | None = None,
     ) -> SamplingIntent:
         return _intent
 
     def get_description(self) -> str:
-        return "ConsistentAlwaysOnSampler"
+        return "ComposableAlwaysOn"
 
 
-_always_on = ConsistentSampler(ConsistentAlwaysOnSampler())
+_always_on = _ComposableAlwaysOnSampler()
 
 
-def consistent_always_on() -> ConsistentSampler:
-    """Returns a consistent sampler that samples all spans."""
+def composable_always_on() -> ComposableSampler:
+    """Returns a composable sampler that samples all spans.
+
+    - Always returns a SamplingIntent with threshold set to sample all spans (threshold = 0)
+    - Sets threshold_reliable to true
+    - Does not add any attributes
+    """
     return _always_on

opentelemetry-sdk/src/opentelemetry/sdk/trace/_sampling_experimental/_composable.py

@@ -1,5 +1,21 @@
+# Copyright The OpenTelemetry Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from __future__ import annotations
+
 from dataclasses import dataclass, field
-from typing import Callable, Optional, Protocol, Sequence
+from typing import Callable, Protocol, Sequence
 
 from opentelemetry.context import Context
 from opentelemetry.trace import Link, SpanKind, TraceState
@@ -11,26 +27,33 @@ class SamplingIntent:
     """Information to make a consistent sampling decision."""
 
     threshold: int
-    adjusted_count_reliable: bool = field(default=True)
+    """The sampling threshold value. A lower threshold increases the likelihood of sampling."""
+
+    threshold_reliable: bool = field(default=True)
+    """Indicates whether the threshold is reliable for Span-to-Metrics estimation."""
+
     attributes: Attributes = field(default=None)
+    """Any attributes to be added to a sampled span."""
+
     update_trace_state: Callable[[TraceState], TraceState] = field(
         default=lambda ts: ts
     )
+    """Any updates to be made to trace state."""
 
 
 class ComposableSampler(Protocol):
-    """A sampler that can be composed to make a final consistent sampling decision."""
+    """A sampler that can be composed to make a final sampling decision."""
 
     def sampling_intent(
         self,
-        parent_ctx: Optional[Context],
+        parent_ctx: Context | None,
         name: str,
-        span_kind: Optional[SpanKind],
+        span_kind: SpanKind | None,
         attributes: Attributes,
-        links: Optional[Sequence[Link]],
-        trace_state: Optional[TraceState],
+        links: Sequence[Link] | None,
+        trace_state: TraceState | None,
     ) -> SamplingIntent:
-        """Returns information to make a consistent sampling decision."""
+        """Returns information to make a sampling decision."""
 
     def get_description(self) -> str:
         """Returns a description of the sampler."""