Merge branch 'main' into bump-semconv-1370

Author: xrmx

CHANGELOG.md

@@ -12,6 +12,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## Unreleased
 
+- Add experimental composite samplers
+  ([#4714](https://github.com/open-telemetry/opentelemetry-python/pull/4714))
 - Filter duplicate logs out of some internal `logger`'s logs on the export logs path that might otherwise endlessly log or cause a recursion depth exceeded issue in cases where logging itself results in an exception.
   ([#4695](https://github.com/open-telemetry/opentelemetry-python/pull/4695)).
 - docs: linked the examples with their github source code location and added Prometheus example

docs/examples/auto-instrumentation/client.py

@@ -12,7 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-from sys import argv
+import sys
 
 from requests import get
 
@@ -31,16 +31,16 @@
     BatchSpanProcessor(ConsoleSpanExporter())
 )
 
-
-assert len(argv) == 2
+# Get parameter from command line argument or use default value "testing"
+param_value = sys.argv[1] if len(sys.argv) > 1 else "testing"
 
 with tracer.start_as_current_span("client"):
     with tracer.start_as_current_span("client-server"):
         headers = {}
         inject(headers)
         requested = get(
             "http://localhost:8082/server_request",
-            params={"param": argv[1]},
+            params={"param": param_value},
             headers=headers,
         )
 

docs/getting_started/tests/test_metrics.py

@@ -0,0 +1,103 @@
+# 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.
+
+import json
+import os
+import subprocess
+import sys
+import unittest
+
+
+class TestMetrics(unittest.TestCase):
+    def test_metrics(self):
+        """Test that metrics example produces expected values"""
+        # Run the metrics example
+        test_script = f"{os.path.dirname(os.path.realpath(__file__))}/../metrics_example.py"
+
+        result = subprocess.run(
+            [sys.executable, test_script],
+            capture_output=True,
+            text=True,
+            timeout=10,
+            check=True,
+        )
+
+        # Script should run successfully
+        self.assertEqual(result.returncode, 0)
+
+        # Parse the JSON output
+        output_data = json.loads(result.stdout)
+
+        # Get the metrics from the JSON structure
+        metrics = output_data["resource_metrics"][0]["scope_metrics"][0][
+            "metrics"
+        ]
+
+        # Create a lookup dict for easier testing
+        metrics_by_name = {metric["name"]: metric for metric in metrics}
+
+        # Test Counter: should be 1 (called counter.add(1))
+        counter_value = metrics_by_name["counter"]["data"]["data_points"][0][
+            "value"
+        ]
+        self.assertEqual(counter_value, 1, "Counter should have value 1")
+
+        # Test UpDownCounter: should be -4 (1 + (-5) = -4)
+        updown_value = metrics_by_name["updown_counter"]["data"][
+            "data_points"
+        ][0]["value"]
+        self.assertEqual(
+            updown_value, -4, "UpDownCounter should have value -4"
+        )
+
+        # Test Histogram: should have count=1, sum=99.9
+        histogram_data = metrics_by_name["histogram"]["data"]["data_points"][0]
+        self.assertEqual(
+            histogram_data["count"], 1, "Histogram should have count 1"
+        )
+        self.assertEqual(
+            histogram_data["sum"], 99.9, "Histogram should have sum 99.9"
+        )
+
+        # Test Gauge: should be 1 (last value set)
+        gauge_value = metrics_by_name["gauge"]["data"]["data_points"][0][
+            "value"
+        ]
+        self.assertEqual(gauge_value, 1, "Gauge should have value 1")
+
+        # Test Observable Counter: should be 1 (from callback)
+        obs_counter_value = metrics_by_name["observable_counter"]["data"][
+            "data_points"
+        ][0]["value"]
+        self.assertEqual(
+            obs_counter_value, 1, "Observable counter should have value 1"
+        )
+
+        # Test Observable UpDownCounter: should be -10 (from callback)
+        obs_updown_value = metrics_by_name["observable_updown_counter"][
+            "data"
+        ]["data_points"][0]["value"]
+        self.assertEqual(
+            obs_updown_value,
+            -10,
+            "Observable updown counter should have value -10",
+        )
+
+        # Test Observable Gauge: should be 9 (from callback)
+        obs_gauge_value = metrics_by_name["observable_gauge"]["data"][
+            "data_points"
+        ][0]["value"]
+        self.assertEqual(
+            obs_gauge_value, 9, "Observable gauge should have value 9"
+        )

docs/getting_started/tests/test_otlpcollector.py

@@ -0,0 +1,43 @@
+# 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.
+
+# oltpcollector_example.py
+import os
+import subprocess
+import sys
+import unittest
+
+
+class TestOTLPCollector(unittest.TestCase):
+    def test_otlpcollector(self):
+        """Test that OTLP collector example outputs 'Hello world!'"""
+        dirpath = os.path.dirname(os.path.realpath(__file__))
+        test_script = f"{dirpath}/../otlpcollector_example.py"
+
+        # Run the script with a short timeout since it will retry forever
+        with subprocess.Popen(
+            [sys.executable, test_script],
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            text=True,
+        ) as process:
+            # Wait 2 seconds then kill it (enough time to print "Hello world!")
+            try:
+                stdout, _ = process.communicate(timeout=2)
+            except subprocess.TimeoutExpired:
+                process.kill()
+                stdout, _ = process.communicate()
+
+        # Check that it printed the expected message
+        self.assertIn("Hello world!", stdout)

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

@@ -0,0 +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",
+    "SamplingIntent",
+    "composable_always_off",
+    "composable_always_on",
+    "composable_parent_threshold",
+    "composable_traceid_ratio_based",
+    "composite_sampler",
+]
+
+
+from ._always_off import composable_always_off
+from ._always_on import composable_always_on
+from ._composable import ComposableSampler, SamplingIntent
+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

@@ -0,0 +1,55 @@
+# 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 ._util import INVALID_THRESHOLD
+
+_intent = SamplingIntent(threshold=INVALID_THRESHOLD, threshold_reliable=False)
+
+
+class _ComposableAlwaysOffSampler(ComposableSampler):
+    def sampling_intent(
+        self,
+        parent_ctx: Context | None,
+        name: str,
+        span_kind: SpanKind | None,
+        attributes: Attributes,
+        links: Sequence[Link] | None,
+        trace_state: TraceState | None = None,
+    ) -> SamplingIntent:
+        return _intent
+
+    def get_description(self) -> str:
+        return "ComposableAlwaysOff"
+
+
+_always_off = _ComposableAlwaysOffSampler()
+
+
+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

@@ -0,0 +1,55 @@
+# 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 ._util import MIN_THRESHOLD
+
+_intent = SamplingIntent(threshold=MIN_THRESHOLD)
+
+
+class _ComposableAlwaysOnSampler(ComposableSampler):
+    def sampling_intent(
+        self,
+        parent_ctx: Context | None,
+        name: str,
+        span_kind: SpanKind | None,
+        attributes: Attributes,
+        links: Sequence[Link] | None,
+        trace_state: TraceState | None = None,
+    ) -> SamplingIntent:
+        return _intent
+
+    def get_description(self) -> str:
+        return "ComposableAlwaysOn"
+
+
+_always_on = _ComposableAlwaysOnSampler()
+
+
+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

@@ -0,0 +1,61 @@
+# 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, Protocol, Sequence
+
+from opentelemetry.context import Context
+from opentelemetry.trace import Link, SpanKind, TraceState
+from opentelemetry.util.types import Attributes
+
+
+@dataclass(frozen=True)
+class SamplingIntent:
+    """Information to make a consistent sampling decision."""
+
+    threshold: int
+    """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 sampling decision."""
+
+    def sampling_intent(
+        self,
+        parent_ctx: Context | None,
+        name: str,
+        span_kind: SpanKind | None,
+        attributes: Attributes,
+        links: Sequence[Link] | None,
+        trace_state: TraceState | None,
+    ) -> SamplingIntent:
+        """Returns information to make a sampling decision."""
+        ...  # pylint: disable=unnecessary-ellipsis
+
+    def get_description(self) -> str:
+        """Returns a description of the sampler."""
+        ...  # pylint: disable=unnecessary-ellipsis