tessl/pypi-opentelemetry-instrumentation-bedrock

OpenTelemetry instrumentation for AWS Bedrock runtime services providing automatic tracing, metrics, and event emission for AI model invocations

—

Pending

Overview

Eval results

Files

Core Instrumentation

Name: tessl/pypi-opentelemetry-instrumentation-bedrock
Author: tessl

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.

Capabilities

BedrockInstrumentor

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.

class BedrockInstrumentor(BaseInstrumentor):
    """
    An instrumentor for Bedrock's client library.
    
    This class automatically instruments boto3 clients created for the 
    bedrock-runtime service, adding comprehensive tracing, metrics, and 
    event emission capabilities.
    """
    
    def __init__(
        self,
        enrich_token_usage: bool = False,
        exception_logger = None,
        use_legacy_attributes: bool = True
    ):
        """
        Initialize the Bedrock instrumentor.
        
        Parameters:
        - enrich_token_usage: Enable detailed token counting using model-specific APIs
        - exception_logger: Custom exception handling callback function
        - use_legacy_attributes: Use legacy span attributes instead of semantic conventions
        """
        
    def instrumentation_dependencies(self) -> Collection[str]:
        """
        Return the list of packages required for instrumentation.
        
        Returns:
        Collection of package specifications that must be installed
        """
        
    def instrument(self, **kwargs) -> None:
        """
        Enable instrumentation for Bedrock clients.
        
        Parameters:
        - tracer_provider: OpenTelemetry tracer provider
        - meter_provider: OpenTelemetry meter provider  
        - event_logger_provider: OpenTelemetry event logger provider
        """
        
    def uninstrument(self, **kwargs) -> None:
        """
        Disable instrumentation and unwrap all instrumented methods.
        
        Removes all instrumentation wrappers and restores original
        boto3 client behavior.
        """

Global Configuration

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

class Config:
    """
    Global configuration for Bedrock instrumentation.
    
    These settings control the behavior of all instrumented Bedrock clients
    and are set when the instrumentor is initialized.
    """
    
    enrich_token_usage: bool
    """Enable detailed token counting using model-specific tokenizer APIs"""
    
    exception_logger: Any  
    """Custom exception handling callback for instrumentation errors"""
    
    use_legacy_attributes: bool
    """Control span attribute format - legacy attributes vs semantic conventions"""

Instrumentation Control

Functions for checking and controlling instrumentation behavior at runtime.

def is_metrics_enabled() -> bool:
    """
    Check if metrics collection is enabled.
    
    Returns:
    Boolean indicating if metrics should be collected based on 
    TRACELOOP_METRICS_ENABLED environment variable (default: true)
    """

Usage Examples

Basic Instrumentation

from opentelemetry.instrumentation.bedrock import BedrockInstrumentor
import boto3

# Enable instrumentation with default settings
BedrockInstrumentor().instrument()

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

Advanced Configuration

from opentelemetry.instrumentation.bedrock import BedrockInstrumentor
from opentelemetry import trace, metrics
import logging

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

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

# Initialize with advanced options
instrumentor = BedrockInstrumentor(
    enrich_token_usage=True,  # Enable detailed token counting
    exception_logger=custom_exception_handler,
    use_legacy_attributes=False  # Use semantic conventions
)

# Instrument with custom providers
instrumentor.instrument(
    tracer_provider=tracer_provider,
    meter_provider=meter_provider
)

Conditional Instrumentation

from opentelemetry.instrumentation.bedrock import BedrockInstrumentor, is_metrics_enabled
import os

# Check environment before instrumenting
if os.getenv('ENABLE_BEDROCK_TRACING', 'false').lower() == 'true':
    instrumentor = BedrockInstrumentor(
        enrich_token_usage=is_metrics_enabled(),
        use_legacy_attributes=False
    )
    instrumentor.instrument()
    print("Bedrock instrumentation enabled")
else:
    print("Bedrock instrumentation disabled")

Instrumentation Lifecycle Management

from opentelemetry.instrumentation.bedrock import BedrockInstrumentor

# Store instrumentor reference for lifecycle management
instrumentor = BedrockInstrumentor()

try:
    # Enable instrumentation
    instrumentor.instrument()
    
    # Application code using Bedrock clients
    # ... (client usage here)
    
finally:
    # Clean up instrumentation on shutdown
    instrumentor.uninstrument()

Instrumented Methods

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

Client Creation Methods

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

Bedrock Runtime Methods

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

invoke_model: Synchronous model invocation with complete response
invoke_model_with_response_stream: Streaming model invocation
converse: Synchronous conversation API calls
converse_stream: Streaming conversation API calls

Span Names and Structure

The instrumentation creates spans with the following naming convention:

Span Names

bedrock.completion: For invoke_model and invoke_model_with_response_stream operations
bedrock.converse: For converse and converse_stream operations

Span Attributes

Spans include comprehensive attributes covering:

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

Dependencies

The instrumentation requires the following packages:

_instruments = ("boto3 >= 1.28.57",)

Additional dependencies are automatically managed:

opentelemetry-api ^1.28.0
opentelemetry-instrumentation >=0.55b0
opentelemetry-semantic-conventions >=0.55b0
opentelemetry-semantic-conventions-ai ^0.4.13
anthropic >=0.17.0 (for token counting)
tokenizers >=0.13.0 (for token counting)

Install with Tessl CLI

npx tessl i tessl/pypi-opentelemetry-instrumentation-bedrock

docs