AWS X-Ray Remote Sampler Part 2 - Add Rules Caching, Rules Matching Logic, Rate Limiter, and Sampling Targets Poller

[jj22ee]

Description

• Followup PR of AWS X-Ray Remote Sampler Part 1 - Initial Classes and Rules Poller Implementation #3366

Changes:

• Add Sampling RuleCache
  • Caches a list of _SamplingRuleAppliers, ordered by rule priority then rule name. Each Rule Applier corresponds to the Sampling Rule from GetSamplingRules. Each call to GetSamplingRules will only update the Rules that have changed properties, to preserve the state of unchanged rules. This means Reservoir and Statistics will persist in Rules for unchanged rules.
  • The RuleCache will determine which Rule a set of {resource, attributes} matches with that has highest priority.
• Added logic to fetch sampling targets for each _SamplingRuleApplier.
  • The sampling targets are periodically fetched every 10 seconds by making the GetSamplingTargets API call to X-Ray.
  • The targets determine the reservoir quota and the rate at which a _SamplingRuleApplier will sample the requests.
  • Each rule applier keeps and updates a sampling statistics document which is required in GetSamplingTargets call to determine the next target
• Update _SamplingRuleApplier to perform Fixed Rate & Reservoir Sampling, and to include a method to apply matching logic against a set of {resource, attributes} by using the wild card and attribute matching from Utils
• Added a _RateLimitingSampler (applied before the fixed rate sampler) to be used in each rule applier.
  • Together these samplers determine how many requests to sample every second and what percentage of additional requests to sample in that second.
• Added class for FallbackSampler, a combination of _RateLimitingSampler and TraceIdRatioBased samplers to sample 1 req/sec and 5% of additional requests in that second.
• Update _InternalAwsXRayRemoteSampler to depend on RuleCache and a FallbackSampler Sampler for making sampling decisions

Fixes #3305 -- This is the final PR to support X-Ray Remote Sampling.

Type of change

Please delete options that are not relevant.

• New feature (non-breaking change which adds functionality)

How Has This Been Tested?

• The current implementation was tested against X-Ray's Centralized Sampling Integration tests.

Does This PR Require a Core Repo Change?

• No.

Checklist:

See contributing.md for styleguide, changelog guidelines, and more.

• Followed the style guidelines of this project
• Changelogs have been updated
• Unit tests have been added
• Documentation has been updated

[xrmx]

opentelemetry-sdk-extension-aws is released on its own and it has its own changelog in sdk-extension/opentelemetry-sdk-extension-aws

[xrmx]

Could you please add the following and take care of any eventual output of tox -e typecheck?

diff --git a/pyproject.toml b/pyproject.toml
index 30ada5bb2..45b8ea632 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -206,6 +206,7 @@ include = [
   "instrumentation-genai/opentelemetry-instrumentation-weaviate",
   "util/opentelemetry-util-genai",
   "exporter/opentelemetry-exporter-credential-provider-gcp",
+  "sdk-extension/opentelemetry-sdk-extension-aws/src/opentelemetry/sdk/extension/aws/trace/sampler",
 ]
 # We should also add type hints to the test suite - It helps on finding bugs.
 # We are excluding for now because it's easier, and more important to add to the instrumentation packages.