Updated November 2026Migrating from AWS X-Ray SDKs to OpenTelemetry
Class Duration
7 hours of live training delivered over 1 day.
Student Prerequisites
- Software development experience in Java, Python, Node.js, .NET, or Go
- Working knowledge of AWS Lambda, Amazon ECS, or Amazon EKS
- Existing applications instrumented with the AWS X-Ray SDKs, or familiarity with X-Ray traces
- No prior OpenTelemetry experience required
Target Audience
Developers, SREs, and platform engineers whose AWS services use the X-Ray SDKs or the X-Ray daemon. It also fits architects choosing between the X-Ray console, CloudWatch Application Signals, and third-party backends. For OpenTelemetry beyond AWS, see Observability with OpenTelemetry.
Description
AWS moved the X-Ray SDKs and the X-Ray daemon into maintenance mode on February 25, 2026, with security fixes only. AWS now recommends OpenTelemetry for instrumentation, while the X-Ray service stays as a trace backend. This one-day course walks through the migration, starting with how X-Ray concepts map to OpenTelemetry. Students replace X-Ray SDK calls with ADOT or upstream OpenTelemetry SDKs on Lambda, ECS, and EKS. The course closes with sampling, backend choices, and a verified cutover.
Learning Outcomes
- Explain what changes and what stays when moving off the X-Ray SDKs.
- Map X-Ray segments, annotations, and trace headers to OpenTelemetry concepts.
- Choose between the CloudWatch agent, the OpenTelemetry Collector, and direct OTLP export.
- Replace X-Ray SDK instrumentation with ADOT or upstream OpenTelemetry SDKs.
- Instrument Lambda functions with the AWS Lambda Layer for OpenTelemetry.
- Migrate ECS tasks and EKS workloads off the X-Ray daemon.
- Carry X-Ray sampling rules forward with the X-Ray remote sampler.
- Choose a trace backend for migrated services.
- Verify trace continuity and cut over safely.
- Remove the X-Ray SDKs and daemon after cutover.
Training Materials
Comprehensive courseware is distributed online at the start of class. All students receive a downloadable MP4 recording of the training.
Software Requirements
Students will need a free, personal GitHub account to access the courseware, an AWS account with permissions for Lambda, ECS or EKS, CloudWatch, X-Ray, and IAM, the AWS CLI v2, Docker Desktop or Podman, a code editor (VS Code recommended), and a development environment for at least one of Java, Python, Node.js, .NET, or Go.
Training Topics
Why Migrate
- Maintenance mode for the X-Ray SDKs and daemon
- What stays the same in X-Ray
- What changes in instrumentation and collection
- OpenTelemetry signals beyond traces
- Planning by service, runtime, and platform
OpenTelemetry for X-Ray Users
- Segments and subsegments vs. spans
- Annotations and metadata vs. attributes
- Resource attributes
- X-Ray trace IDs and the X-Ray propagator
- W3C Trace Context
- Keeping traces connected during migration
- ADOT vs. upstream OpenTelemetry
Target Architectures
- The CloudWatch agent as an OpenTelemetry collector
- The OpenTelemetry Collector with the X-Ray exporter
- Direct OTLP export to the X-Ray endpoint
- CloudWatch Transaction Search
- SigV4 authentication and IAM permissions
Replacing X-Ray SDK Instrumentation
- ADOT auto-instrumentation
- Upstream OpenTelemetry SDKs, including Go
- AWS per-language migration guides
- Replacing manual segments and annotations
- Instrumenting AWS SDK, HTTP, and database calls
- Removing X-Ray SDK dependencies
AWS Lambda
- The AWS Lambda Layer for OpenTelemetry
- The exec wrapper
- Tracing-only mode vs. Application Signals
- Lambda active tracing
- ADOT Lambda layers with an embedded collector
- Go functions with the OpenTelemetry Go SDK
- Cold starts and package size
Amazon ECS
- Replacing the X-Ray daemon sidecar
- The CloudWatch agent on ECS
- Sidecar vs. daemon on EC2 and Fargate
- Task roles for telemetry export
- Collector images instead of the CloudWatch agent
Amazon EKS
- The Amazon CloudWatch Observability EKS add-on
- Application Signals and Container Insights
- The ADOT EKS add-on
- OpenTelemetry Operator auto-instrumentation
- Replacing the X-Ray daemon DaemonSet
- EKS Pod Identity or IRSA for collectors
Sampling
- X-Ray sampling rules with the remote sampler
- Proxying sampling requests through a collector
- X-Ray adaptive sampling
- Sampling boost and anomaly span capture
- Head-based vs. tail-based sampling
- Transaction Search indexing costs
Choosing a Backend
- The X-Ray console and CloudWatch traces
- CloudWatch Application Signals
- Service maps, metrics, and SLOs
- Third-party OpenTelemetry backends
- Sending to multiple backends
- Span ingestion, indexing, and retention costs
Verification and Cutover
- Comparing traces before and after migration
- Checking trace continuity across mixed services
- Updating dashboards, alarms, and runbooks
- Rollback options
- Decommissioning the X-Ray SDKs and daemon
