---
id: opentelemetry-propagator-aws-xray
version: "1.0.2"
license: unclear
license_treatment: permissive
maintenance: active
---

# opentelemetry-propagator-aws-xray — AWS X-Ray Propagator for OpenTelemetry

License: permissive · Maintenance: active · Downloads: 12.0M/mo

## What it is and what it does

This package provides an OpenTelemetry propagator that handles the AWS X-Ray trace context format, specifically the X-Amzn-Trace-Id header. It allows traces initiated in one AWS service to be correctly linked to downstream services by injecting and extracting tracing context in the format X-Ray expects.

The propagator integrates with OpenTelemetry's global propagation system, either via environment variable (OTEL_PROPAGATORS=xray) or by explicitly setting it in code. It is a thin adapter layer between OpenTelemetry's span context model and AWS X-Ray's header format, with no external dependencies beyond opentelemetry-api itself.

Use it for:

- Trace requests flowing through multiple AWS Lambda functions, ECS tasks, or EC2 instances using OpenTelemetry.
- Correlate logs and metrics with X-Ray traces when using AWS CloudWatch and X-Ray together.
- Export OpenTelemetry spans to AWS X-Ray for visualization and analysis of distributed request flows.
- Integrate on-premises or third-party services into an AWS X-Ray tracing pipeline via OpenTelemetry.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Injects and extracts AWS X-Ray tracing context into OpenTelemetry spans, enabling trace propagation across AWS services.

Yes. This is a production-stable, actively maintained library with no known vulnerabilities, low install friction, and a permissive license. Install it if you are using OpenTelemetry in an AWS environment and need X-Ray trace propagation. Note the documentation caveat: ensure X-Amzn-Trace-Id headers include Sampled=1 to enable child span sampling.

## Install

pip install opentelemetry-propagator-aws-xray
uv add opentelemetry-propagator-aws-xray
poetry add opentelemetry-propagator-aws-xray

## Installing opentelemetry-propagator-aws-xray

Before you install: Low friction installation with a single runtime dependency (opentelemetry-api). Actively maintained with recent commits and production-stable status.

License in practice: Licensed under Apache Software License (permissive), allowing commercial and private use without restriction.

Quickstart:

pip install opentelemetry-propagator-aws-xray

from opentelemetry.propagate import set_global_textmap
from opentelemetry.propagators.aws import AwsXRayPropagator

set_global_textmap(AwsXRayPropagator())

Requires opentelemetry-api to be installed; Python 3.8 or later.

Verify before relying:

- Whether X-Amzn-Trace-Id headers are automatically set to Sampled=1 or require manual configuration in all deployment scenarios.
- Performance impact when propagating traces across high-volume AWS service calls.

## Package facts

- License: not declared (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 12.0M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

aws x-ray tracing, opentelemetry propagator, distributed tracing aws, trace context propagation, x-ray trace header, opentelemetry aws integration, distributed-tracing, aws-integration, observability

[View on SkillFed](https://skillfed.io/packages/opentelemetry-propagator-aws-xray) · [View on PyPI](https://pypi.org/project/opentelemetry-propagator-aws-xray/)