{"id":6504,"library":"aiobotocore-otel","title":"OpenTelemetry aiobotocore instrumentation","description":"aiobotocore-otel (version 1.3.0, released Feb 25, 2026) provides OpenTelemetry instrumentation for aiobotocore, enabling tracing of asynchronous AWS service requests. It is a specialized fork of opentelemetry-instrumentation-botocore, adapted for aiobotocore's async nature. The library is actively maintained and relies on the regular updates of both aiobotocore and the broader OpenTelemetry Python ecosystem, both of which have frequent release cadences.","status":"active","version":"1.3.0","language":"en","source_language":"en","source_url":"https://github.com/kjagiello/aiobotocore-otel","tags":["opentelemetry","aws","aiobotocore","asyncio","instrumentation","tracing","observability"],"install":[{"cmd":"pip install aiobotocore-otel","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Core library for AWS asynchronous clients that is being instrumented.","package":"aiobotocore"},{"reason":"Provides the core OpenTelemetry API interfaces.","package":"opentelemetry-api"},{"reason":"Provides the OpenTelemetry SDK implementation (typically needed for a full tracing setup).","package":"opentelemetry-sdk"},{"reason":"Base classes and utilities for OpenTelemetry instrumentation.","package":"opentelemetry-instrumentation"},{"reason":"Optional, for AWS X-Ray trace context propagation.","package":"opentelemetry-propagator-aws-xray","optional":true},{"reason":"Provides standard semantic conventions for OpenTelemetry attributes.","package":"opentelemetry-semantic-conventions"},{"reason":"Required for proper trace context propagation in aiobotocore's S3 multipart transfers which use background threads.","package":"opentelemetry-instrumentation-threading","optional":true}],"imports":[{"note":"Despite the package name `aiobotocore-otel`, the primary instrumentor for aiobotocore is found under `opentelemetry.instrumentation.botocore` as it extends the core botocore instrumentation.","symbol":"AiobotocoreInstrumentor","correct":"from opentelemetry.instrumentation.botocore import AiobotocoreInstrumentor"}],"quickstart":{"code":"import asyncio\nimport os\nfrom opentelemetry import trace\nfrom opentelemetry.sdk.trace import TracerProvider\nfrom opentelemetry.sdk.trace.export import ConsoleSpanExporter, SimpleSpanProcessor\nfrom opentelemetry.instrumentation.botocore import AiobotocoreInstrumentor\nimport aiobotocore.session\n\nasync def main():\n    # 1. Setup OpenTelemetry TracerProvider\n    provider = TracerProvider()\n    processor = SimpleSpanProcessor(ConsoleSpanExporter())\n    provider.add_span_processor(processor)\n    trace.set_tracer_provider(provider)\n\n    # 2. Instrument aiobotocore\n    AiobotocoreInstrumentor().instrument()\n\n    # 3. Use aiobotocore client (e.g., S3)\n    session = aiobotocore.session.get_session()\n    # Use environment variables for AWS credentials in a real scenario\n    aws_access_key_id = os.environ.get('AWS_ACCESS_KEY_ID', 'YOUR_ACCESS_KEY')\n    aws_secret_access_key = os.environ.get('AWS_SECRET_ACCESS_KEY', 'YOUR_SECRET_KEY')\n    \n    # Ensure a proper region and dummy credentials for a runnable example\n    if aws_access_key_id == 'YOUR_ACCESS_KEY' or aws_secret_access_key == 'YOUR_SECRET_KEY':\n        print(\"WARNING: Using dummy AWS credentials. Replace with actual credentials or environment variables.\")\n\n    async with session.create_client(\n        's3', \n        region_name='us-east-1', \n        aws_access_key_id=aws_access_key_id, \n        aws_secret_access_key=aws_secret_access_key\n    ) as client:\n        try:\n            # This call will be traced if instrumentation is active\n            response = await client.list_buckets()\n            print(\"Successfully listed S3 buckets (or attempted to if credentials are dummy).\")\n        except Exception as e:\n            print(f\"Error listing S3 buckets: {e}. If using dummy credentials, this is expected.\")\n\nif __name__ == \"__main__\":\n    asyncio.run(main())\n","lang":"python","description":"This quickstart demonstrates how to set up a basic OpenTelemetry `TracerProvider`, instrument `aiobotocore` using `AiobotocoreInstrumentor`, and make an example asynchronous AWS S3 call (list buckets). The console exporter will print trace information to stdout. Replace dummy AWS credentials with actual ones or environment variables for real functionality."},"warnings":[{"fix":"Explicitly instrument `threading`: `from opentelemetry.instrumentation.threading import ThreadingInstrumentor; ThreadingInstrumentor().instrument()`. If using `opentelemetry-instrument` auto-instrumentation, this is handled automatically if `opentelemetry-instrumentation-threading` is installed.","message":"When using aiobotocore (via boto3) for S3 multipart transfers (e.g., upload_file, download_file), background threads are employed. For full OpenTelemetry trace context propagation across these threads, the `opentelemetry-instrumentation-threading` package must also be installed and instrumented.","severity":"gotcha","affected_versions":"All versions of aiobotocore-otel when used with aiobotocore's S3 multipart transfers."},{"fix":"Ensure `aiobotocore` is updated to a version compatible with your `aiohttp` version (e.g., `aiobotocore >= 3.4.0` for `aiohttp >= 3.9.2`).","message":"Older versions of `aiobotocore` experienced compatibility issues and breaking changes with `aiohttp` versions, particularly `aiohttp>=3.9.2`. This could manifest as errors related to unexpected arguments like `verify_ssl`.","severity":"gotcha","affected_versions":"aiobotocore versions before `3.4.0` when used with `aiohttp>=3.9.2`."},{"fix":"For effective mocking with `aiobotocore`, it is often necessary to run `moto` in server mode and configure `aiobotocore` clients to connect to this local test server. Consult `aiobotocore`'s test suite for examples of server-based mocking patterns.","message":"Directly mocking AWS services using `moto` with `aiobotocore` might not work as seamlessly as with synchronous `boto3`, as `moto` often employs a synchronous API. Attempts to mock `aiobotocore` calls directly may result in connections to actual AWS services.","severity":"gotcha","affected_versions":"All versions of aiobotocore-otel when attempting to use `moto` for direct mocking without a server."}],"env_vars":null,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z","problems":[{"fix":"Ensure that 'aiobotocore' and 'botocore' are compatible by updating both to their latest versions.","cause":"This error occurs when there's a version mismatch between 'aiobotocore' and 'botocore', leading to missing attributes.","error":"ImportError: cannot import name 'InvalidIMDSEndpointError'"},{"fix":"Update 'aiobotocore' to a version that includes 'AioSession', ensuring compatibility with your codebase.","cause":"This error arises when the 'AioSession' attribute is missing in the 'aiobotocore' module, often due to version incompatibilities.","error":"AttributeError: module 'aiobotocore' has no attribute 'AioSession'"},{"fix":"Use the 'async with' context manager to properly create the client and then call 'send_message' on the client object.","cause":"This error occurs when attempting to call 'send_message' on a 'ClientCreatorContext' object, which lacks this method.","error":"AttributeError: 'ClientCreatorContext' object has no attribute 'send_message'"},{"fix":"Ensure the package is correctly installed using pip: `pip install aiobotocore-otel`","cause":"The `aiobotocore-otel` package is not installed in the current Python environment or there's a typo in the import statement.","error":"ModuleNotFoundError: No module named 'aiobotocore_otel'"},{"fix":"Import `AiobotocoreInstrumentor` from the correct `opentelemetry.instrumentation.botocore` module: `from opentelemetry.instrumentation.botocore import AiobotocoreInstrumentor`","cause":"Developers might mistakenly assume a dedicated `opentelemetry.instrumentation.aiobotocore` module, but the `AiobotocoreInstrumentor` is typically exposed within the `opentelemetry.instrumentation.botocore` module itself, as `aiobotocore-otel` is a fork of `opentelemetry-instrumentation-botocore` adapted for async operations.","error":"AttributeError: module 'opentelemetry.instrumentation.aiobotocore' has no attribute 'AiobotocoreInstrumentor'"}]}