Registry / observability / opentelemetry-sdk-extension-aws

opentelemetry-sdk-extension-aws

JSON →
library2.1.0pypypi✓ verified 23d ago

The opentelemetry-sdk-extension-aws library, currently at version 2.1.0, provides components to configure the OpenTelemetry SDK for Python, primarily enabling compatibility with AWS X-Ray tracing. It offers custom ID generators for X-Ray compatible trace IDs and AWS resource detectors to automatically enrich telemetry data with AWS-specific metadata. The project is actively maintained as part of the wider opentelemetry-python-contrib monorepo and follows its release cadence.

pip install opentelemetry-sdk-extension-aws opentelemetry-sdk opentelemetry-propagator-aws-xray
INSTALL
IMPORT
SIG · OPENTELEMETRY-SDK-
O
opentelemetry-sdk-extension-aws
observabilitypythonv2.1.0
Install
2.0s avg
Import
189ms
Disk
20MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v2.1.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
musl
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 0.196s · 22.1MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 2.0s · import 0.182s · 23MB
20MB installed
● package 20MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

AwsXRayIdGenerator
from opentelemetry.sdk.extension.aws.trace import AwsXRayIdGenerator
Ec2ResourceDetector
from opentelemetry.sdk.extension.aws.resource.ec2 import Ec2ResourceDetector
from opentelemetry.sdk.extension.aws.resource import Ec2ResourceDetector
The Ec2ResourceDetector is located in a submodule specific to resource detectors.

This quickstart demonstrates how to configure the OpenTelemetry Python SDK using `opentelemetry-sdk-extension-aws`. It initializes a `TracerProvider` with `AwsXRayIdGenerator` to ensure trace ID compatibility with AWS X-Ray and includes an `Ec2ResourceDetector` to automatically add AWS EC2 metadata to your traces. Spans are then exported to the console.

import os 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.sdk.extension.aws.trace import AwsXRayIdGenerator from opentelemetry.sdk.extension.aws.resource.ec2 import Ec2ResourceDetector # 1. Configure the TracerProvider with the X-Ray ID Generator for trace ID compatibility # This is crucial for traces to be accepted and correlated correctly by AWS X-Ray. tracer_provider = TracerProvider(id_generator=AwsXRayIdGenerator()) trace.set_tracer_provider(tracer_provider) # 2. Detect AWS specific resource attributes (e.g., EC2 instance metadata) # For a local runnable example, we use a basic resource and merge with detected EC2 attributes. # In an actual EC2 environment, Ec2ResourceDetector.detect() would populate real metadata. resource = Resource.create({"service.name": os.environ.get("OTEL_SERVICE_NAME", "my-aws-app")}) # Attempt to detect EC2 resources; if not on EC2, this will yield an empty resource. # The merge operation combines the service name with any detected AWS resource attributes. tracer_provider.resource = resource.merge(Ec2ResourceDetector().detect()) # 3. Configure a simple span processor and console exporter for demonstration span_processor = SimpleSpanProcessor(ConsoleSpanExporter()) tracer_provider.add_span_processor(span_processor) # 4. Get a tracer and create some spans tracer = trace.get_tracer(__name__) with tracer.start_as_current_span("my-aws-operation"): print("Performing an operation traced with OpenTelemetry and AWS X-Ray compatible IDs.") with tracer.start_as_current_span("sub-operation"): print("This is a sub-operation within the main task.") print("OpenTelemetry with AWS X-Ray compatibility and resource detection configured.") print("Check console output for example spans.")
Debug
Known issues
gotchaOpenTelemetry's default trace ID generation is not compatible with AWS X-Ray. To ensure traces can be ingested and properly correlated in X-Ray, you MUST configure the `AwsXRayIdGenerator` from this package when initializing your `TracerProvider`.
fix
Initialize your TracerProvider with `id_generator=AwsXRayIdGenerator()`.
affects: All versions
gotchaFor correct trace context propagation across AWS services (e.g., SQS, SNS, Lambda), the `opentelemetry-propagator-aws-xray` package is strongly recommended. Without it, trace context may not propagate correctly, leading to broken traces across service boundaries.
fix
Install `opentelemetry-propagator-aws-xray` and configure it as a global propagator: `from opentelemetry.propagate import set_global_textmap;
from opentelemetry.propagators.aws.xray import AwsXRayPropagator;
set_global_textmap(AwsXRayPropagator())`.
affects: All versions
deprecatedAWS is transitioning its native X-Ray SDKs and Daemon to maintenance mode, focusing new feature development on OpenTelemetry-based solutions. While existing X-Ray SDKs will continue to function, new development or migrations should leverage OpenTelemetry and this extension for better future compatibility and access to new features.
fix
Adopt `opentelemetry-sdk-extension-aws` and other OpenTelemetry components for new tracing implementations in AWS environments.
affects: All versions
gotchaAWS resource detectors (e.g., `Ec2ResourceDetector`, `EcsResourceDetector`) included in this package rely on specific environment variables, IAM permissions, or runtime metadata services to automatically detect and populate resource attributes. Ensure your application's deployment environment provides the necessary access for accurate resource attribution.
fix
Review the documentation for each specific resource detector to understand its requirements and ensure your AWS environment is configured accordingly (e.g., IAM roles, environment variables).
affects: All versions
Upgrade
Version history
2.1.0latest on PyPI · released Dec 24, 2024
Audit
Dependencies
opentelemetry-sdkrequiredProvides the core OpenTelemetry SDK functionalities and interfaces.
opentelemetry-propagator-aws-xrayrequiredStrongly recommended for correct trace context propagation across AWS services like SQS and SNS.
Agent activity
15 hits · last 30 days
node
12
Amazon
1
OpenAI (training)
1
Resources
opentelemetry-sdk-extension-aws — pip install opentelemetry-sdk-extension-aws · libregistry