OpenTelemetry Boto3 SQS Instrumentation

Warnings

• gotcha This library is in beta (`b` in version number) and its API or behavior might change in future versions without strict adherence to semantic versioning for non-beta releases. Production use should proceed with caution and thorough testing.
  Fix: Regularly review release notes for `opentelemetry-python-contrib` for changes. Pin exact versions for stability and test thoroughly before deploying updates.
• gotcha The `boto3` library, which this package instruments, must be installed separately. OpenTelemetry instrumentation packages typically do not include their target libraries as direct dependencies to avoid version conflicts. Failing to install `boto3` will result in `ModuleNotFoundError` or similar issues.
  Fix: Ensure `boto3` is explicitly installed alongside the instrumentation package (e.g., `pip install boto3`).
• gotcha The OpenTelemetry SDK (`opentelemetry-sdk`) and an exporter (e.g., `opentelemetry-exporter-otlp`, `ConsoleSpanExporter`) must be configured and a `TracerProvider` set *before* calling `Boto3SQSInstrumentor().instrument()`. Otherwise, no spans will be generated.
  Fix: Always initialize your `TracerProvider` and add at least one `SpanProcessor` with an `SpanExporter` before enabling any instrumentation.
• gotcha Trace context is automatically injected into SQS message attributes (e.g., `_OPEN_TELEMETRY_TRACE_CONTEXT`) when sending messages. For end-to-end tracing, consumers of these SQS messages must also be instrumented or manually extract and activate the trace context from the message attributes.
  Fix: Ensure both producers and consumers of SQS messages are correctly instrumented. If using non-Python consumers or custom message processing, implement explicit trace context extraction and activation.

Install

• pip install opentelemetry-instrumentation-boto3sqs opentelemetry-sdk boto3 Install core, instrumentation, and boto3

Imports

• Boto3SQSInstrumentor

  from opentelemetry.instrumentation.boto3sqs import Boto3SQSInstrumentor

Quickstart

This quickstart demonstrates how to set up the OpenTelemetry SDK with a console exporter, instrument `boto3` for SQS, and then perform basic SQS operations (create, send, receive, delete queue/messages). This will output trace spans to the console.

import os
import boto3
from opentelemetry import trace
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import ConsoleSpanExporter, SimpleSpanProcessor
from opentelemetry.instrumentation.boto3sqs import Boto3SQSInstrumentor

# 1. Configure OpenTelemetry Tracer Provider and Exporter
resource = Resource.create({"service.name": "sqs-test-app"})
provider = TracerProvider(resource=resource)
processor = SimpleSpanProcessor(ConsoleSpanExporter())
provider.add_span_processor(processor)
trace.set_tracer_provider(provider)

# 2. Instrument boto3 SQS
Boto3SQSInstrumentor().instrument()

# 3. Use boto3 SQS client, operations will be traced
session = boto3.Session(
    aws_access_key_id=os.environ.get("AWS_ACCESS_KEY_ID", "TEST_ACCESS_KEY"),
    aws_secret_access_key=os.environ.get("AWS_SECRET_ACCESS_KEY", "TEST_SECRET_KEY"),
    region_name=os.environ.get("AWS_REGION", "us-east-1")
)
sqs_client = session.client("sqs")

queue_name = "otel-test-queue"
queue_url = None

try:
    print(f"Creating queue: {queue_name}")
    response = sqs_client.create_queue(QueueName=queue_name, Attributes={'DelaySeconds': '5'})
    queue_url = response['QueueUrl']
    print(f"Queue URL: {queue_url}")

    print("Sending message...")
    sqs_client.send_message(QueueUrl=queue_url, MessageBody="Hello SQS from OpenTelemetry!")

    print("Receiving messages...")
    messages = sqs_client.receive_message(
        QueueUrl=queue_url,
        MaxNumberOfMessages=1,
        WaitTimeSeconds=10 # Use long polling for testing
    )
    if messages and 'Messages' in messages:
        for message in messages['Messages']:
            print(f"Received message: {message['Body']}")
            print(f"Deleting message: {message['MessageId']}")
            sqs_client.delete_message(
                QueueUrl=queue_url,
                ReceiptHandle=message['ReceiptHandle']
            )
    else:
        print("No messages received.")

except Exception as e:
    print(f"An error occurred: {e}")
finally:
    if queue_url:
        print(f"Deleting queue: {queue_name}")
        try:
            sqs_client.delete_queue(QueueUrl=queue_url)
            print("Queue deleted.")
        except Exception as e:
            print(f"Error deleting queue: {e}")