0
# Sampling Control
1

2
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.
3

4
## Capabilities
5

6
### Sampling Decision Inspection
7

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

10
```python { .api }
11
def is_sampled() -> bool:
12
    """
13
    Check if the current trace entity is sampled.
14
    
15
    Returns:
16
        bool: True if current entity is sampled, False otherwise
17
        
18
    Notes:
19
        - Returns False if no active trace entity exists
20
        - Useful for expensive annotation/metadata generation code
21
        - Should be checked before adding costly trace data
22
    """
23
```
24

25
### Usage Examples
26

27
#### Conditional Expensive Operations
28

29
Use sampling checks to avoid expensive operations for unsampled traces:
30

31
```python
32
from aws_xray_sdk.core import xray_recorder
33

34
# Only generate expensive metadata for sampled traces
35
if xray_recorder.is_sampled():
36
    expensive_annotation = compute_expensive_annotation()
37
    complex_metadata = generate_complex_metadata()
38
    
39
    xray_recorder.put_annotation('expensive_key', expensive_annotation)
40
    xray_recorder.put_metadata('complex_data', complex_metadata)
41
```
42

43
#### Unsampled Subsegments
44

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

47
```python
48
from aws_xray_sdk.core import xray_recorder
49

50
# Create an unsampled subsegment for expensive background operation
51
subsegment = xray_recorder.begin_subsegment_without_sampling('background-task')
52
try:
53
    # Perform background operation
54
    process_background_data()
55
finally:
56
    xray_recorder.end_subsegment()
57
```
58

59
### Sampling Configuration
60

61
#### Local Sampling Rules
62

63
Configure local sampling rules using JSON file or dictionary:
64

65
```python
66
from aws_xray_sdk.core import xray_recorder
67

68
# Using JSON file path
69
xray_recorder.configure(
70
    sampling_rules='/path/to/sampling-rules.json'
71
)
72

73
# Using dictionary
74
sampling_rules = {
75
    "version": 2,
76
    "default": {
77
        "fixed_target": 1,
78
        "rate": 0.1
79
    },
80
    "rules": [
81
        {
82
            "description": "High priority service",
83
            "service_name": "important-service",
84
            "http_method": "*",
85
            "url_path": "*",
86
            "fixed_target": 2,
87
            "rate": 0.5
88
        }
89
    ]
90
}
91

92
xray_recorder.configure(sampling_rules=sampling_rules)
93
```
94

95
#### Custom Sampler Implementation
96

97
Implement custom sampling logic:
98

99
```python
100
from aws_xray_sdk.core import xray_recorder
101
from aws_xray_sdk.core.sampling.local.sampler import LocalSampler
102

103
class CustomSampler(LocalSampler):
104
    def should_trace(self, sampling_req):
105
        # Custom sampling logic
106
        service_name = sampling_req.get('service')
107
        if service_name == 'critical-service':
108
            return True
109
        return super().should_trace(sampling_req)
110

111
# Configure recorder with custom sampler
112
custom_sampler = CustomSampler()
113
xray_recorder.configure(sampler=custom_sampler)
114
```
115

116
### Sampling Rule Format
117

118
Local sampling rules follow this JSON schema:
119

120
```json
121
{
122
  "version": 2,
123
  "default": {
124
    "fixed_target": 1,
125
    "rate": 0.1
126
  },
127
  "rules": [
128
    {
129
      "description": "Customer orders service",
130
      "service_name": "order-service",
131
      "http_method": "POST",
132
      "url_path": "/api/orders/*",
133
      "fixed_target": 2,
134
      "rate": 0.5
135
    }
136
  ]
137
}
138
```
139

140
**Rule Parameters:**
141
- `fixed_target`: Minimum number of traces per second to sample
142
- `rate`: Percentage of additional traces to sample (0.0 to 1.0)
143
- `service_name`: Service name pattern (supports wildcards)
144
- `http_method`: HTTP method filter (supports wildcards)
145
- `url_path`: URL path pattern (supports wildcards)
146

147
### Environment Variables
148

149
Control sampling behavior through environment variables:
150

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

154
### Integration with AWS X-Ray Service
155

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