OpenTelemetry Botocore Instrumentation

0.61b0 · active · verified Thu Apr 09

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.

Warnings

breaking The 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.
gotcha The `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`.
gotcha This 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.
gotcha OpenTelemetry 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.

Install

pip install opentelemetry-instrumentation-botocore Install instrumentation
pip install boto3 Install boto3 (which includes botocore)

Imports

BotocoreInstrumentor

from opentelemetry.instrumentation.botocore import BotocoreInstrumentor

Quickstart

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.")

view raw JSON →