Install & Compatibility
Where this runs
tested against v1.7.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.000s · 63.2MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 6.8s · import 0.000s · 65MB
63MB installed
● package 63MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
AiobotocoreInstrumentor
✓ from opentelemetry.instrumentation.aiobotocore import AiobotocoreInstrumentor
✗ from opentelemetry.instrumentation.aiobotocore import AiobotocoreInstrumentor
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.
import asyncio
import os
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import ConsoleSpanExporter, SimpleSpanProcessor
from opentelemetry.instrumentation.botocore import AiobotocoreInstrumentor
import aiobotocore.session
async def main():
# 1. Setup OpenTelemetry TracerProvider
provider = TracerProvider()
processor = SimpleSpanProcessor(ConsoleSpanExporter())
provider.add_span_processor(processor)
trace.set_tracer_provider(provider)
# 2. Instrument aiobotocore
AiobotocoreInstrumentor().instrument()
# 3. Use aiobotocore client (e.g., S3)
session = aiobotocore.session.get_session()
# Use environment variables for AWS credentials in a real scenario
aws_access_key_id = os.environ.get('AWS_ACCESS_KEY_ID', 'YOUR_ACCESS_KEY')
aws_secret_access_key = os.environ.get('AWS_SECRET_ACCESS_KEY', 'YOUR_SECRET_KEY')
# Ensure a proper region and dummy credentials for a runnable example
if aws_access_key_id == 'YOUR_ACCESS_KEY' or aws_secret_access_key == 'YOUR_SECRET_KEY':
print("WARNING: Using dummy AWS credentials. Replace with actual credentials or environment variables.")
async with session.create_client(
's3',
region_name='us-east-1',
aws_access_key_id=aws_access_key_id,
aws_secret_access_key=aws_secret_access_key
) as client:
try:
# This call will be traced if instrumentation is active
response = await client.list_buckets()
print("Successfully listed S3 buckets (or attempted to if credentials are dummy).")
except Exception as e:
print(f"Error listing S3 buckets: {e}. If using dummy credentials, this is expected.")
if __name__ == "__main__":
asyncio.run(main())
Debug
Known issues
gotchaWhen 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.fixExplicitly 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.
affects: All versions of aiobotocore-otel when used with aiobotocore's S3 multipart transfers.
gotchaOlder 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`.fixEnsure `aiobotocore` is updated to a version compatible with your `aiohttp` version (e.g., `aiobotocore >= 3.4.0` for `aiohttp >= 3.9.2`).
affects: aiobotocore versions before `3.4.0` when used with `aiohttp>=3.9.2`.
gotchaDirectly 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.fixFor 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.
affects: All versions of aiobotocore-otel when attempting to use `moto` for direct mocking without a server.
Upgrade
Version history
1.7.0latest on PyPI · released Jun 7, 2026
Audit
Dependencies
aiobotocorerequiredCore library for AWS asynchronous clients that is being instrumented.
opentelemetry-apirequiredProvides the core OpenTelemetry API interfaces.
opentelemetry-sdkrequiredProvides the OpenTelemetry SDK implementation (typically needed for a full tracing setup).
opentelemetry-instrumentationrequiredBase classes and utilities for OpenTelemetry instrumentation.
opentelemetry-propagator-aws-xrayoptionalOptional, for AWS X-Ray trace context propagation.
opentelemetry-semantic-conventionsrequiredProvides standard semantic conventions for OpenTelemetry attributes.
opentelemetry-instrumentation-threadingoptionalRequired for proper trace context propagation in aiobotocore's S3 multipart transfers which use background threads.