AWS SDK Extension for OpenTelemetry

Warnings

• gotcha OpenTelemetry'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()`.
• gotcha For 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())`.
• deprecated AWS 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.
• gotcha AWS 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).

Install

• pip install opentelemetry-sdk-extension-aws opentelemetry-sdk opentelemetry-propagator-aws-xray Install with core SDK and X-Ray propagator

Imports

• AwsXRayIdGenerator

  from opentelemetry.sdk.extension.aws.trace import AwsXRayIdGenerator

• Ec2ResourceDetector

  from opentelemetry.sdk.extension.aws.resource.ec2 import Ec2ResourceDetector

  The Ec2ResourceDetector is located in a submodule specific to resource detectors.

Quickstart

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