0
# Core Instrumentation
1

2
Core instrumentation functionality for automatically tracing AWS Bedrock AI model invocations. The BedrockInstrumentor class provides the primary interface for enabling comprehensive OpenTelemetry instrumentation of boto3 Bedrock clients.
3

4
## Capabilities
5

6
### BedrockInstrumentor
7

8
Main instrumentor class that enables automatic tracing of Bedrock API calls by wrapping boto3 client creation methods. Inherits from OpenTelemetry's BaseInstrumentor and follows the standard instrumentation lifecycle.
9

10
```python { .api }
11
class BedrockInstrumentor(BaseInstrumentor):
12
    """
13
    An instrumentor for Bedrock's client library.
14
    
15
    This class automatically instruments boto3 clients created for the 
16
    bedrock-runtime service, adding comprehensive tracing, metrics, and 
17
    event emission capabilities.
18
    """
19
    
20
    def __init__(
21
        self,
22
        enrich_token_usage: bool = False,
23
        exception_logger = None,
24
        use_legacy_attributes: bool = True
25
    ):
26
        """
27
        Initialize the Bedrock instrumentor.
28
        
29
        Parameters:
30
        - enrich_token_usage: Enable detailed token counting using model-specific APIs
31
        - exception_logger: Custom exception handling callback function
32
        - use_legacy_attributes: Use legacy span attributes instead of semantic conventions
33
        """
34
        
35
    def instrumentation_dependencies(self) -> Collection[str]:
36
        """
37
        Return the list of packages required for instrumentation.
38
        
39
        Returns:
40
        Collection of package specifications that must be installed
41
        """
42
        
43
    def instrument(self, **kwargs) -> None:
44
        """
45
        Enable instrumentation for Bedrock clients.
46
        
47
        Parameters:
48
        - tracer_provider: OpenTelemetry tracer provider
49
        - meter_provider: OpenTelemetry meter provider  
50
        - event_logger_provider: OpenTelemetry event logger provider
51
        """
52
        
53
    def uninstrument(self, **kwargs) -> None:
54
        """
55
        Disable instrumentation and unwrap all instrumented methods.
56
        
57
        Removes all instrumentation wrappers and restores original
58
        boto3 client behavior.
59
        """
60
```
61

62
### Global Configuration
63

64
Global configuration management for controlling instrumentation behavior across all instrumented clients. Configuration is set at instrumentation time and affects all subsequent Bedrock client operations.
65

66
```python { .api }
67
class Config:
68
    """
69
    Global configuration for Bedrock instrumentation.
70
    
71
    These settings control the behavior of all instrumented Bedrock clients
72
    and are set when the instrumentor is initialized.
73
    """
74
    
75
    enrich_token_usage: bool
76
    """Enable detailed token counting using model-specific tokenizer APIs"""
77
    
78
    exception_logger: Any  
79
    """Custom exception handling callback for instrumentation errors"""
80
    
81
    use_legacy_attributes: bool
82
    """Control span attribute format - legacy attributes vs semantic conventions"""
83
```
84

85
### Instrumentation Control
86

87
Functions for checking and controlling instrumentation behavior at runtime.
88

89
```python { .api }
90
def is_metrics_enabled() -> bool:
91
    """
92
    Check if metrics collection is enabled.
93
    
94
    Returns:
95
    Boolean indicating if metrics should be collected based on 
96
    TRACELOOP_METRICS_ENABLED environment variable (default: true)
97
    """
98
```
99

100
## Usage Examples
101

102
### Basic Instrumentation
103

104
```python
105
from opentelemetry.instrumentation.bedrock import BedrockInstrumentor
106
import boto3
107

108
# Enable instrumentation with default settings
109
BedrockInstrumentor().instrument()
110

111
# All bedrock-runtime clients created after this point will be instrumented
112
client = boto3.client('bedrock-runtime', region_name='us-east-1')
113
```
114

115
### Advanced Configuration
116

117
```python
118
from opentelemetry.instrumentation.bedrock import BedrockInstrumentor
119
from opentelemetry import trace, metrics
120
import logging
121

122
def custom_exception_handler(exception, context):
123
    """Custom exception handling for instrumentation errors"""
124
    logging.error(f"Bedrock instrumentation error: {exception}")
125

126
# Configure custom tracer and meter providers
127
tracer_provider = trace.get_tracer_provider()
128
meter_provider = metrics.get_meter_provider()
129

130
# Initialize with advanced options
131
instrumentor = BedrockInstrumentor(
132
    enrich_token_usage=True,  # Enable detailed token counting
133
    exception_logger=custom_exception_handler,
134
    use_legacy_attributes=False  # Use semantic conventions
135
)
136

137
# Instrument with custom providers
138
instrumentor.instrument(
139
    tracer_provider=tracer_provider,
140
    meter_provider=meter_provider
141
)
142
```
143

144
### Conditional Instrumentation
145

146
```python
147
from opentelemetry.instrumentation.bedrock import BedrockInstrumentor, is_metrics_enabled
148
import os
149

150
# Check environment before instrumenting
151
if os.getenv('ENABLE_BEDROCK_TRACING', 'false').lower() == 'true':
152
    instrumentor = BedrockInstrumentor(
153
        enrich_token_usage=is_metrics_enabled(),
154
        use_legacy_attributes=False
155
    )
156
    instrumentor.instrument()
157
    print("Bedrock instrumentation enabled")
158
else:
159
    print("Bedrock instrumentation disabled")
160
```
161

162
### Instrumentation Lifecycle Management
163

164
```python
165
from opentelemetry.instrumentation.bedrock import BedrockInstrumentor
166

167
# Store instrumentor reference for lifecycle management
168
instrumentor = BedrockInstrumentor()
169

170
try:
171
    # Enable instrumentation
172
    instrumentor.instrument()
173
    
174
    # Application code using Bedrock clients
175
    # ... (client usage here)
176
    
177
finally:
178
    # Clean up instrumentation on shutdown
179
    instrumentor.uninstrument()
180
```
181

182
## Instrumented Methods
183

184
The instrumentor automatically wraps the following boto3 methods to add tracing:
185

186
### Client Creation Methods
187

188
- **botocore.client.ClientCreator.create_client**: Wraps client creation to instrument bedrock-runtime clients
189
- **botocore.session.Session.create_client**: Wraps session-level client creation
190

191
### Bedrock Runtime Methods
192

193
When a bedrock-runtime client is created, the following methods are automatically instrumented:
194

195
- **invoke_model**: Synchronous model invocation with complete response
196
- **invoke_model_with_response_stream**: Streaming model invocation 
197
- **converse**: Synchronous conversation API calls
198
- **converse_stream**: Streaming conversation API calls
199

200
## Span Names and Structure
201

202
The instrumentation creates spans with the following naming convention:
203

204
### Span Names
205

206
- **bedrock.completion**: For invoke_model and invoke_model_with_response_stream operations
207
- **bedrock.converse**: For converse and converse_stream operations
208

209
### Span Attributes
210

211
Spans include comprehensive attributes covering:
212

213
- **Model Information**: Provider, model name, model vendor
214
- **Request Details**: Input tokens, parameters, configuration
215
- **Response Details**: Output tokens, completion reason, response metadata
216
- **Performance Metrics**: Duration, token throughput, cache hits
217
- **Guardrail Information**: Activation status, policy violations, confidence scores
218
- **Error Information**: Exception types, error messages, failure reasons
219

220
## Dependencies
221

222
The instrumentation requires the following packages:
223

224
```python { .api }
225
_instruments = ("boto3 >= 1.28.57",)
226
```
227

228
Additional dependencies are automatically managed:
229
- opentelemetry-api ^1.28.0
230
- opentelemetry-instrumentation >=0.55b0  
231
- opentelemetry-semantic-conventions >=0.55b0
232
- opentelemetry-semantic-conventions-ai ^0.4.13
233
- anthropic >=0.17.0 (for token counting)
234
- tokenizers >=0.13.0 (for token counting)