AWS X-Ray Remote Sampler Part 1 - Initial Classes and Rules Poller Implementation (#3366)

* remote sampling - initial classes and rules poller

* run generate-workflows and ruff

* add component owner for aws sampler, run lint

* move sampler into aws sdk-extensions

* move sampler tests to trace dir, update otel api/sdk deps, update changelog

* move mock_clock into tests dir

* update component owners for sdk-extension-aws

* ruff and lint

* address comments

* make sampler implementation internal until completion, update tests to not make http requests

* remove use of Optional, restore README of the package

* remove unused clock and client_id

* Update component_owners.yml

* Update CHANGELOG.md

---------

Co-authored-by: Riccardo Magliocchetti <[email protected]>

Author: jj22ee

.github/component_owners.yml

@@ -33,12 +33,11 @@ components:
     - dorkolog
 
   propagator/opentelemetry-propagator-aws-xray:
-    - NathanielRN
+    - jj22ee
 
   sdk-extension/opentelemetry-sdk-extension-aws:
-    - NathanielRN
-    - Kausik-A
     - srprash
+    - jj22ee
 
   instrumentation/opentelemetry-instrumentation-tortoiseorm:
     - tonybaloney

CHANGELOG.md

@@ -26,7 +26,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   ([#3685](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/3685))
 - `opentelemetry-instrumentation-system-metrics`: Add `cpython.gc.collected_objects` and `cpython.gc.uncollectable_objects` metrics
   ([#3666](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/3666))
-
+- `opentelemetry-sdk-extension-aws` Add AWS X-Ray Remote Sampler with initial Rules Poller implementation
+  ([#3366](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/3366))
 
 ## Version 1.36.0/0.57b0 (2025-07-29)
 

sdk-extension/opentelemetry-sdk-extension-aws/pyproject.toml

@@ -25,7 +25,11 @@ classifiers = [
   "Programming Language :: Python :: 3.13",
 ]
 dependencies = [
-  "opentelemetry-sdk ~= 1.12",
+  "opentelemetry-api ~= 1.23",
+  "opentelemetry-sdk ~= 1.23",
+  "opentelemetry-instrumentation ~= 0.44b0",
+  "opentelemetry-semantic-conventions ~= 0.44b0",
+  "requests ~= 2.28",
 ]
 
 [project.entry-points.opentelemetry_id_generator]
@@ -38,6 +42,10 @@ aws_eks = "opentelemetry.sdk.extension.aws.resource.eks:AwsEksResourceDetector"
 aws_elastic_beanstalk = "opentelemetry.sdk.extension.aws.resource.beanstalk:AwsBeanstalkResourceDetector"
 aws_lambda = "opentelemetry.sdk.extension.aws.resource._lambda:AwsLambdaResourceDetector"
 
+# TODO: Uncomment this when Sampler implementation is complete
+# [project.entry-points.opentelemetry_sampler]
+# aws_xray_remote_sampler = "opentelemetry.sdk.extension.aws.trace.sampler:AwsXRayRemoteSampler"
+
 [project.urls]
 Homepage = "https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/sdk-extension/opentelemetry-sdk-extension-aws"
 Repository = "https://github.com/open-telemetry/opentelemetry-python-contrib"

sdk-extension/opentelemetry-sdk-extension-aws/src/opentelemetry/sdk/extension/aws/trace/sampler/__init__.py

@@ -0,0 +1,20 @@
+# 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.
+
+# pylint: disable=no-name-in-module
+from opentelemetry.sdk.extension.aws.trace.sampler.aws_xray_remote_sampler import (
+    _AwsXRayRemoteSampler,
+)
+
+__all__ = ["_AwsXRayRemoteSampler"]

sdk-extension/opentelemetry-sdk-extension-aws/src/opentelemetry/sdk/extension/aws/trace/sampler/_aws_xray_sampling_client.py

@@ -0,0 +1,143 @@
+# 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.
+
+# Includes work from:
+# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+import json
+from logging import getLogger
+from typing import List
+
+import requests
+
+# pylint: disable=no-name-in-module
+from opentelemetry.instrumentation.utils import suppress_instrumentation
+from opentelemetry.sdk.extension.aws.trace.sampler._sampling_rule import (
+    _SamplingRule,
+)
+from opentelemetry.sdk.extension.aws.trace.sampler._sampling_target import (
+    _SamplingTargetResponse,
+)
+
+_logger = getLogger(__name__)
+DEFAULT_SAMPLING_PROXY_ENDPOINT = "http://127.0.0.1:2000"
+
+
+class _AwsXRaySamplingClient:
+    def __init__(
+        self,
+        endpoint: str = DEFAULT_SAMPLING_PROXY_ENDPOINT,
+        log_level: str | None = None,
+    ):
+        # Override default log level
+        if log_level is not None:
+            _logger.setLevel(log_level)
+
+        self.__get_sampling_rules_endpoint = endpoint + "/GetSamplingRules"
+        self.__get_sampling_targets_endpoint = endpoint + "/SamplingTargets"
+
+        self.__session = requests.Session()
+
+    def get_sampling_rules(self) -> List[_SamplingRule]:
+        sampling_rules: List["_SamplingRule"] = []
+        headers = {"content-type": "application/json"}
+
+        with suppress_instrumentation():
+            try:
+                xray_response = self.__session.post(
+                    url=self.__get_sampling_rules_endpoint,
+                    headers=headers,
+                    timeout=20,
+                )
+                sampling_rules_response = xray_response.json()
+                if (
+                    sampling_rules_response is None
+                    or "SamplingRuleRecords" not in sampling_rules_response
+                ):
+                    _logger.error(
+                        "SamplingRuleRecords is missing in getSamplingRules response: %s",
+                        sampling_rules_response,
+                    )
+                    return []
+                sampling_rules_records = sampling_rules_response[
+                    "SamplingRuleRecords"
+                ]
+                for record in sampling_rules_records:
+                    if "SamplingRule" not in record:
+                        _logger.error(
+                            "SamplingRule is missing in SamplingRuleRecord"
+                        )
+                    else:
+                        sampling_rules.append(
+                            _SamplingRule(**record["SamplingRule"])
+                        )
+
+            except requests.exceptions.RequestException as req_err:
+                _logger.error("Request error occurred: %s", req_err)
+            except json.JSONDecodeError as json_err:
+                _logger.error("Error in decoding JSON response: %s", json_err)
+            # pylint: disable=broad-exception-caught
+            except Exception as err:
+                _logger.error(
+                    "Error occurred when attempting to fetch rules: %s", err
+                )
+
+            return sampling_rules
+
+    def get_sampling_targets(
+        self, statistics: List["dict[str, str | float | int]"]
+    ) -> _SamplingTargetResponse:
+        sampling_targets_response = _SamplingTargetResponse(
+            LastRuleModification=None,
+            SamplingTargetDocuments=None,
+            UnprocessedStatistics=None,
+        )
+        headers = {"content-type": "application/json"}
+
+        with suppress_instrumentation():
+            try:
+                xray_response = self.__session.post(
+                    url=self.__get_sampling_targets_endpoint,
+                    headers=headers,
+                    timeout=20,
+                    json={"SamplingStatisticsDocuments": statistics},
+                )
+                xray_response_json = xray_response.json()
+                if (
+                    xray_response_json is None
+                    or "SamplingTargetDocuments" not in xray_response_json
+                    or "LastRuleModification" not in xray_response_json
+                ):
+                    _logger.debug(
+                        "getSamplingTargets response is invalid. Unable to update targets."
+                    )
+                    return sampling_targets_response
+
+                sampling_targets_response = _SamplingTargetResponse(
+                    **xray_response_json
+                )
+            except requests.exceptions.RequestException as req_err:
+                _logger.debug("Request error occurred: %s", req_err)
+            except json.JSONDecodeError as json_err:
+                _logger.debug("Error in decoding JSON response: %s", json_err)
+            # pylint: disable=broad-exception-caught
+            except Exception as err:
+                _logger.debug(
+                    "Error occurred when attempting to fetch targets: %s", err
+                )
+
+            return sampling_targets_response

sdk-extension/opentelemetry-sdk-extension-aws/src/opentelemetry/sdk/extension/aws/trace/sampler/_clock.py

@@ -0,0 +1,37 @@
+# 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.
+
+# Includes work from:
+# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+import datetime
+
+
+class _Clock:
+    def __init__(self):
+        self.__datetime = datetime.datetime
+
+    def now(self) -> datetime.datetime:
+        return self.__datetime.now()
+
+    # pylint: disable=no-self-use
+    def from_timestamp(self, timestamp: float) -> datetime.datetime:
+        return datetime.datetime.fromtimestamp(timestamp)
+
+    def time_delta(self, seconds: float) -> datetime.timedelta:
+        return datetime.timedelta(seconds=seconds)
+
+    def max(self) -> datetime.datetime:
+        return datetime.datetime.max

sdk-extension/opentelemetry-sdk-extension-aws/src/opentelemetry/sdk/extension/aws/trace/sampler/_sampling_rule.py

@@ -0,0 +1,80 @@
+# 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.
+
+# Includes work from:
+# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+
+# Disable snake_case naming style so this class can match the sampling rules response from X-Ray
+# pylint: disable=invalid-name
+class _SamplingRule:
+    def __init__(
+        self,
+        Attributes: dict[str, str] | None = None,
+        FixedRate: float | None = None,
+        HTTPMethod: str | None = None,
+        Host: str | None = None,
+        Priority: int | None = None,
+        ReservoirSize: int | None = None,
+        ResourceARN: str | None = None,
+        RuleARN: str | None = None,
+        RuleName: str | None = None,
+        ServiceName: str | None = None,
+        ServiceType: str | None = None,
+        URLPath: str | None = None,
+        Version: int | None = None,
+    ):
+        self.Attributes = Attributes if Attributes is not None else {}
+        self.FixedRate = FixedRate if FixedRate is not None else 0.0
+        self.HTTPMethod = HTTPMethod if HTTPMethod is not None else ""
+        self.Host = Host if Host is not None else ""
+        # Default to value with lower priority than default rule
+        self.Priority = Priority if Priority is not None else 10001
+        self.ReservoirSize = ReservoirSize if ReservoirSize is not None else 0
+        self.ResourceARN = ResourceARN if ResourceARN is not None else ""
+        self.RuleARN = RuleARN if RuleARN is not None else ""
+        self.RuleName = RuleName if RuleName is not None else ""
+        self.ServiceName = ServiceName if ServiceName is not None else ""
+        self.ServiceType = ServiceType if ServiceType is not None else ""
+        self.URLPath = URLPath if URLPath is not None else ""
+        self.Version = Version if Version is not None else 0
+
+    def __lt__(self, other: "_SamplingRule") -> bool:
+        if self.Priority == other.Priority:
+            # String order priority example:
+            # "A","Abc","a","ab","abc","abcdef"
+            return self.RuleName < other.RuleName
+        return self.Priority < other.Priority
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, _SamplingRule):
+            return False
+        return (
+            self.FixedRate == other.FixedRate
+            and self.HTTPMethod == other.HTTPMethod
+            and self.Host == other.Host
+            and self.Priority == other.Priority
+            and self.ReservoirSize == other.ReservoirSize
+            and self.ResourceARN == other.ResourceARN
+            and self.RuleARN == other.RuleARN
+            and self.RuleName == other.RuleName
+            and self.ServiceName == other.ServiceName
+            and self.ServiceType == other.ServiceType
+            and self.URLPath == other.URLPath
+            and self.Version == other.Version
+            and self.Attributes == other.Attributes
+        )

sdk-extension/opentelemetry-sdk-extension-aws/src/opentelemetry/sdk/extension/aws/trace/sampler/_sampling_rule_applier.py

@@ -0,0 +1,47 @@
+# 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.
+
+# Includes work from:
+# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+# pylint: disable=no-name-in-module
+from opentelemetry.sdk.extension.aws.trace.sampler._clock import _Clock
+from opentelemetry.sdk.extension.aws.trace.sampler._sampling_rule import (
+    _SamplingRule,
+)
+from opentelemetry.sdk.extension.aws.trace.sampler._sampling_statistics_document import (
+    _SamplingStatisticsDocument,
+)
+from opentelemetry.sdk.extension.aws.trace.sampler._sampling_target import (
+    _SamplingTarget,
+)
+
+
+class _SamplingRuleApplier:
+    def __init__(
+        self,
+        sampling_rule: _SamplingRule,
+        client_id: str,
+        clock: _Clock,
+        statistics: _SamplingStatisticsDocument | None = None,
+        target: _SamplingTarget | None = None,
+    ):
+        self.__client_id = client_id  # pylint: disable=W0238
+        self._clock = clock
+        self.sampling_rule = sampling_rule
+
+        # (TODO) Just store Sampling Rules for now, rest of implementation for later