Registry / observability / opentelemetry-instrumentation-botocore

opentelemetry-instrumentation-botocore

JSON →
library0.65b0pypypi✓ verified 24d ago

This library provides OpenTelemetry automatic instrumentation for the `botocore` library, which is the underlying core for `boto3`, allowing you to trace AWS SDK operations. It automatically generates spans for calls made to AWS services. The current version is 0.61b0, indicating it's still in beta. The OpenTelemetry Python Contrib project, which this library is part of, has a frequent release cadence, often aligning with core SDK updates and semantic convention changes, with individual instrumentations releasing independently as features and fixes are added.

pip install opentelemetry-instrumentation-botocore
INSTALL
IMPORT
SIG · OPENTELEMETRY-INST
O
opentelemetry-instrumentation-botocore
observabilitypythonv0.65b0
Install
3.2s avg
Import
Disk
38MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
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
musl
py 3.103.910 runs
installs and imports cleanly · install 0.0s · import 0.000s · 22.9MB
glibc
py 3.103.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.
fix
Review 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.
fix
Ensure 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.
fix
Add `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.
fix
Consult 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.
Agent activity
33 hits · last 30 days
node
30
Amazon
1
OpenAI (training)
1
Resources
opentelemetry-instrumentation-botocore — pip install opentelemetry-instrumentation-botocore · libregistry