tessl/pypi-aws-xray-sdk

The AWS X-Ray SDK for Python enables Python developers to record and emit information from within their applications to the AWS X-Ray service for distributed tracing.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Sampling Control

Name: tessl/pypi-aws-xray-sdk
Author: tessl

Advanced sampling control and decision inspection for optimizing trace collection, performance, and cost management. The X-Ray SDK provides flexible sampling strategies through both centralized and local sampling rules.

Capabilities

Sampling Decision Inspection

Check sampling status and make decisions based on current trace sampling state.

def is_sampled() -> bool:
    """
    Check if the current trace entity is sampled.
    
    Returns:
        bool: True if current entity is sampled, False otherwise
        
    Notes:
        - Returns False if no active trace entity exists
        - Useful for expensive annotation/metadata generation code
        - Should be checked before adding costly trace data
    """

Usage Examples

Conditional Expensive Operations

Use sampling checks to avoid expensive operations for unsampled traces:

from aws_xray_sdk.core import xray_recorder

# Only generate expensive metadata for sampled traces
if xray_recorder.is_sampled():
    expensive_annotation = compute_expensive_annotation()
    complex_metadata = generate_complex_metadata()
    
    xray_recorder.put_annotation('expensive_key', expensive_annotation)
    xray_recorder.put_metadata('complex_data', complex_metadata)

Unsampled Subsegments

Create unsampled subsegments for operations that should not affect sampling decisions:

from aws_xray_sdk.core import xray_recorder

# Create an unsampled subsegment for expensive background operation
subsegment = xray_recorder.begin_subsegment_without_sampling('background-task')
try:
    # Perform background operation
    process_background_data()
finally:
    xray_recorder.end_subsegment()

Sampling Configuration

Local Sampling Rules

Configure local sampling rules using JSON file or dictionary:

from aws_xray_sdk.core import xray_recorder

# Using JSON file path
xray_recorder.configure(
    sampling_rules='/path/to/sampling-rules.json'
)

# Using dictionary
sampling_rules = {
    "version": 2,
    "default": {
        "fixed_target": 1,
        "rate": 0.1
    },
    "rules": [
        {
            "description": "High priority service",
            "service_name": "important-service",
            "http_method": "*",
            "url_path": "*",
            "fixed_target": 2,
            "rate": 0.5
        }
    ]
}

xray_recorder.configure(sampling_rules=sampling_rules)

Custom Sampler Implementation

Implement custom sampling logic:

from aws_xray_sdk.core import xray_recorder
from aws_xray_sdk.core.sampling.local.sampler import LocalSampler

class CustomSampler(LocalSampler):
    def should_trace(self, sampling_req):
        # Custom sampling logic
        service_name = sampling_req.get('service')
        if service_name == 'critical-service':
            return True
        return super().should_trace(sampling_req)

# Configure recorder with custom sampler
custom_sampler = CustomSampler()
xray_recorder.configure(sampler=custom_sampler)

Sampling Rule Format

Local sampling rules follow this JSON schema:

{
  "version": 2,
  "default": {
    "fixed_target": 1,
    "rate": 0.1
  },
  "rules": [
    {
      "description": "Customer orders service",
      "service_name": "order-service",
      "http_method": "POST",
      "url_path": "/api/orders/*",
      "fixed_target": 2,
      "rate": 0.5
    }
  ]
}

Rule Parameters:

fixed_target: Minimum number of traces per second to sample
rate: Percentage of additional traces to sample (0.0 to 1.0)
service_name: Service name pattern (supports wildcards)
http_method: HTTP method filter (supports wildcards)
url_path: URL path pattern (supports wildcards)

Environment Variables

Control sampling behavior through environment variables:

AWS_XRAY_TRACING_NAME: Default service name for segments
AWS_XRAY_NOOP_ID: Generate no-op trace IDs for unsampled requests (default: true)

Integration with AWS X-Ray Service

The SDK automatically integrates with centralized sampling when running in AWS environments, with local rules serving as fallback when centralized sampling is unavailable.

Install with Tessl CLI