Registry /
observability / opentelemetry-instrumentation-botocore
Install & Compatibility
Where this runs
tested against v0.65b0 · 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.910 runs
installs and imports cleanly · install 0.0s · import 0.000s · 22.9MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 3.2s · import 0.000s · 23MB
38MB installed
● package 38MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
BotocoreInstrumentor
✓ from opentelemetry.instrumentation.botocore import BotocoreInstrumentor
✗ from opentelemetry.instrumentation.botocore import BotocoreInstrumentor
This quickstart demonstrates how to set up the OpenTelemetry TracerProvider, enable the `botocore` instrumentation, and then make an AWS SDK call using `boto3`. The `BotocoreInstrumentor().instrument()` call must occur before any `boto3` or `botocore` clients are created to ensure the operations are properly intercepted and traced. The `ConsoleSpanExporter` will print the generated trace spans to the console. Ensure AWS credentials are configured for the `boto3` call to succeed and generate meaningful spans.
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.botocore import BotocoreInstrumentor
# 1. Configure OpenTelemetry Tracer Provider
resource = Resource.create(
{"service.name": "botocore-example", "service.version": "1.0.0"}
)
provider = TracerProvider(resource=resource)
processor = SimpleSpanProcessor(ConsoleSpanExporter())
provider.add_span_processor(processor)
trace.set_tracer_provider(provider)
# 2. Instrument botocore: MUST be called BEFORE any botocore/boto3 client is created
BotocoreInstrumentor().instrument()
# 3. Use boto3 (which uses botocore under the hood)
# For a runnable example, ensure AWS credentials are configured (e.g., via
# AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY environment variables, or ~/.aws/credentials).
# This example uses STS which is a generally available service.
try:
# Simulate an environment variable for a generic 'auth check' placeholder
# though boto3 picks up credentials automatically.
_ = os.environ.get('AWS_ACCESS_KEY_ID', '')
sts_client = boto3.client("sts", region_name="us-east-1")
response = sts_client.get_caller_identity()
print(f"AWS Account ID: {response['Account']}")
except Exception as e:
print(f"Error calling AWS STS: {e}")
print("Please ensure AWS credentials are configured for this example to run successfully.")
print("You can set AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment variables.")
print("Span details should be printed above by ConsoleSpanExporter.")
Debug
Known issues
breakingThe library is currently in beta (version `0.61b0`). This means that the API, attribute names, and internal implementation details are subject to change without strict adherence to semantic versioning until a stable 1.0.0 release. Backward compatibility is not guaranteed.fixReview release notes for each upgrade and adapt your code. Pin to specific beta versions (`==0.61b0`) to prevent unexpected updates, but be prepared for breaking changes when upgrading.
affects: All versions before 1.0.0
gotchaThe `BotocoreInstrumentor().instrument()` method MUST be called before any `botocore` or `boto3` client instances are created or used. If clients are initialized before instrumentation, their calls will not be traced.fixEnsure the instrumentation initialization (`BotocoreInstrumentor().instrument()`) is one of the first lines of your application's startup code, after setting up your OpenTelemetry `TracerProvider`.
affects: All versions
gotchaThis instrumentation does not automatically install `botocore` or `boto3`. You must explicitly install `boto3` (which includes `botocore`) in your project for the instrumentation to have a library to instrument.fixAdd `pip install boto3` to your project's `requirements.txt` or installation steps.
affects: All versions
gotchaOpenTelemetry semantic conventions, which dictate the names and types of spans and attributes, are actively evolving. Span names (e.g., `aws.s3.list_buckets`) and attribute keys (`aws.region`, `db.system`) may change between versions, especially during beta phases.fixConsult the OpenTelemetry AWS semantic conventions documentation and `opentelemetry-python-contrib` release notes regularly to keep up with potential changes. Adjust your trace analysis tools (e.g., dashboards, alerts) accordingly.
affects: All versions, particularly before 1.0.0
Upgrade
Version history
0.65b0latest on PyPI · released Jul 16, 2026
Audit
Dependencies
botocorerequiredThe core library being instrumented. Typically installed as a dependency of `boto3`.
boto3optionalCommonly used higher-level AWS SDK which relies on botocore. Required for most practical examples.