{"id":2155,"library":"opentelemetry-instrumentation-boto3sqs","title":"OpenTelemetry Boto3 SQS Instrumentation","description":"This library provides instrumentation for the `boto3` SQS client, enabling automatic tracing of Amazon SQS operations with OpenTelemetry. It generates spans for `send_message`, `receive_message`, `delete_message` and other SQS client calls, capturing relevant attributes like queue URLs and message IDs. It is part of the OpenTelemetry Python Contrib repository, currently at version `0.62b0`, following the OpenTelemetry release cadence.","status":"active","version":"0.62b0","language":"en","source_language":"en","source_url":"https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation/opentelemetry-instrumentation-boto3sqs","tags":["opentelemetry","tracing","instrumentation","aws","boto3","sqs","cloud"],"install":[{"cmd":"pip install opentelemetry-instrumentation-boto3sqs opentelemetry-sdk boto3","lang":"bash","label":"Install core, instrumentation, and boto3"}],"dependencies":[{"reason":"The underlying AWS SDK for Python that this library instruments. Must be installed separately.","package":"boto3","optional":false},{"reason":"Core OpenTelemetry SDK components required for trace generation and processing. While often pulled transitively by other OTel packages, it's a fundamental functional requirement for setting up tracing.","package":"opentelemetry-sdk","optional":false}],"imports":[{"symbol":"Boto3SQSInstrumentor","correct":"from opentelemetry.instrumentation.boto3sqs import Boto3SQSInstrumentor"}],"quickstart":{"code":"import os\nimport boto3\nfrom opentelemetry import trace\nfrom opentelemetry.sdk.resources import Resource\nfrom opentelemetry.sdk.trace import TracerProvider\nfrom opentelemetry.sdk.trace.export import ConsoleSpanExporter, SimpleSpanProcessor\nfrom opentelemetry.instrumentation.boto3sqs import Boto3SQSInstrumentor\n\n# 1. Configure OpenTelemetry Tracer Provider and Exporter\nresource = Resource.create({\"service.name\": \"sqs-test-app\"})\nprovider = TracerProvider(resource=resource)\nprocessor = SimpleSpanProcessor(ConsoleSpanExporter())\nprovider.add_span_processor(processor)\ntrace.set_tracer_provider(provider)\n\n# 2. Instrument boto3 SQS\nBoto3SQSInstrumentor().instrument()\n\n# 3. Use boto3 SQS client, operations will be traced\nsession = boto3.Session(\n    aws_access_key_id=os.environ.get(\"AWS_ACCESS_KEY_ID\", \"TEST_ACCESS_KEY\"),\n    aws_secret_access_key=os.environ.get(\"AWS_SECRET_ACCESS_KEY\", \"TEST_SECRET_KEY\"),\n    region_name=os.environ.get(\"AWS_REGION\", \"us-east-1\")\n)\nsqs_client = session.client(\"sqs\")\n\nqueue_name = \"otel-test-queue\"\nqueue_url = None\n\ntry:\n    print(f\"Creating queue: {queue_name}\")\n    response = sqs_client.create_queue(QueueName=queue_name, Attributes={'DelaySeconds': '5'})\n    queue_url = response['QueueUrl']\n    print(f\"Queue URL: {queue_url}\")\n\n    print(\"Sending message...\")\n    sqs_client.send_message(QueueUrl=queue_url, MessageBody=\"Hello SQS from OpenTelemetry!\")\n\n    print(\"Receiving messages...\")\n    messages = sqs_client.receive_message(\n        QueueUrl=queue_url,\n        MaxNumberOfMessages=1,\n        WaitTimeSeconds=10 # Use long polling for testing\n    )\n    if messages and 'Messages' in messages:\n        for message in messages['Messages']:\n            print(f\"Received message: {message['Body']}\")\n            print(f\"Deleting message: {message['MessageId']}\")\n            sqs_client.delete_message(\n                QueueUrl=queue_url,\n                ReceiptHandle=message['ReceiptHandle']\n            )\n    else:\n        print(\"No messages received.\")\n\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")\nfinally:\n    if queue_url:\n        print(f\"Deleting queue: {queue_name}\")\n        try:\n            sqs_client.delete_queue(QueueUrl=queue_url)\n            print(\"Queue deleted.\")\n        except Exception as e:\n            print(f\"Error deleting queue: {e}\")","lang":"python","description":"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."},"warnings":[{"fix":"Regularly review release notes for `opentelemetry-python-contrib` for changes. Pin exact versions for stability and test thoroughly before deploying updates.","message":"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.","severity":"gotcha","affected_versions":"0.x.y"},{"fix":"Ensure `boto3` is explicitly installed alongside the instrumentation package (e.g., `pip install boto3`).","message":"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.","severity":"gotcha","affected_versions":"All"},{"fix":"Always initialize your `TracerProvider` and add at least one `SpanProcessor` with an `SpanExporter` before enabling any instrumentation.","message":"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.","severity":"gotcha","affected_versions":"All"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}