{"id":1606,"library":"opentelemetry-instrumentation-botocore","title":"OpenTelemetry Botocore Instrumentation","description":"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.","status":"active","version":"0.61b0","language":"en","source_language":"en","source_url":"https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation/opentelemetry-instrumentation-botocore","tags":["opentelemetry","tracing","instrumentation","aws","botocore","boto3","observability"],"install":[{"cmd":"pip install opentelemetry-instrumentation-botocore","lang":"bash","label":"Install instrumentation"},{"cmd":"pip install boto3","lang":"bash","label":"Install boto3 (which includes botocore)"}],"dependencies":[{"reason":"The core library being instrumented. Typically installed as a dependency of `boto3`.","package":"botocore","optional":false},{"reason":"Commonly used higher-level AWS SDK which relies on botocore. Required for most practical examples.","package":"boto3","optional":true}],"imports":[{"symbol":"BotocoreInstrumentor","correct":"from opentelemetry.instrumentation.botocore import BotocoreInstrumentor"}],"quickstart":{"code":"import os\nimport boto3\nfrom opentelemetry import trace\nfrom opentelemetry.sdk.resources import Resource\nfrom opentelemetry.sdk.trace import TracerProvider\nfrom opentelemetry.sdk.trace.export import ConsoleSpanExporter, SimpleSpanProcessor\nfrom opentelemetry.instrumentation.botocore import BotocoreInstrumentor\n\n# 1. Configure OpenTelemetry Tracer Provider\nresource = Resource.create(\n    {\"service.name\": \"botocore-example\", \"service.version\": \"1.0.0\"}\n)\nprovider = TracerProvider(resource=resource)\nprocessor = SimpleSpanProcessor(ConsoleSpanExporter())\nprovider.add_span_processor(processor)\ntrace.set_tracer_provider(provider)\n\n# 2. Instrument botocore: MUST be called BEFORE any botocore/boto3 client is created\nBotocoreInstrumentor().instrument()\n\n# 3. Use boto3 (which uses botocore under the hood)\n# For a runnable example, ensure AWS credentials are configured (e.g., via\n# AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY environment variables, or ~/.aws/credentials).\n# This example uses STS which is a generally available service.\ntry:\n    # Simulate an environment variable for a generic 'auth check' placeholder\n    # though boto3 picks up credentials automatically.\n    _ = os.environ.get('AWS_ACCESS_KEY_ID', '') \n\n    sts_client = boto3.client(\"sts\", region_name=\"us-east-1\")\n    response = sts_client.get_caller_identity()\n    print(f\"AWS Account ID: {response['Account']}\")\nexcept Exception as e:\n    print(f\"Error calling AWS STS: {e}\")\n    print(\"Please ensure AWS credentials are configured for this example to run successfully.\")\n    print(\"You can set AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment variables.\")\n\nprint(\"Span details should be printed above by ConsoleSpanExporter.\")","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"All versions before 1.0.0"},{"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`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Add `pip install boto3` to your project's `requirements.txt` or installation steps.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions, particularly before 1.0.0"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}