How to Set Up X-Ray Tracing with ADOT Collector Configuration

The AWS Agent Toolkit for AWS provides a pre-configured OpenTelemetry (ADOT) collector that exports distributed traces to AWS X-Ray using the awsxray exporter while simultaneously publishing metrics to CloudWatch EMF, enabling complete observability without additional agents.

The aws/agent-toolkit-for-aws repository includes ready-to-use configuration files and deployment patterns for integrating AWS Distro for OpenTelemetry (ADOT) with X-Ray tracing. By leveraging the collector configuration defined in skills/core-skills/aws-observability/assets/otel-config.yaml, you can forward OTLP-formatted spans from instrumented applications to the X-Ray backend with minimal setup.

ADOT Collector Configuration Structure

The default collector configuration resides in skills/core-skills/aws-observability/assets/otel-config.yaml and defines the pipeline for processing telemetry data. This configuration receives traces via the OTLP receiver on standard gRPC and HTTP ports, processes them through a batch processor, and exports them to X-Ray using the dedicated AWS exporter.

The key components include:

• OTLP Receiver: Listens on 0.0.0.0:4317 (gRPC) and 0.0.0.0:4318 (HTTP) for incoming trace data from ADOT SDKs.
• AWS X-Ray Exporter: Translates OpenTelemetry spans into the X-Ray format and forwards them to the local X-Ray daemon.
• CloudWatch EMF Exporter: Exports metrics to CloudWatch using the Embedded Metrics Format.

# skills/core-skills/aws-observability/assets/otel-config.yaml

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      http:
        endpoint: 0.0.0.0:4318

exporters:
  awsxray:
    endpoint: 127.0.0.1:2000
  awsemf:
    namespace: AWS/Observability

processors:
  batch: {}

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [awsxray]
    metrics:
      receivers: [otlp]
      processors: [batch]
      exporters: [awsemf]

Configuring the AWS X-Ray Exporter

The awsxray exporter handles the protocol translation between OpenTelemetry and the X-Ray service. By default, it sends trace data to the X-Ray daemon endpoint at 127.0.0.1:2000, which is the standard local port for the X-Ray daemon process.

For production workloads requiring centralized sampling rules, you should enable the awsproxy extension in your collector configuration. This extension allows the collector to communicate with the X-Ray backend to fetch sampling rules and report rule statistics, ensuring consistent sampling rates across distributed services.

Deployment Patterns

You can deploy the ADOT collector as a sidecar container alongside your application or as a daemon on EC2/ECS instances. Both patterns are supported by the configuration files in skills/core-skills/aws-observability/references/tracing.md.

Docker Sidecar Configuration

When running the collector as a sidecar in a containerized environment, mount the configuration file and expose the OTLP ports:

FROM public.ecr.aws/aws-observability/aws-otel-collector:latest
COPY otel-config.yaml /etc/otel/config.yaml
ENTRYPOINT ["/awscollector"]
CMD ["--config", "/etc/otel/config.yaml"]

ECS Task Definition

For Amazon ECS deployments, define the collector as a separate container with shared volumes for the configuration:

{
  "containerDefinitions": [
    {
      "name": "app",
      "image": "<your-application-image>",
      "essential": true,
      "environment": [
        {
          "name": "OTEL_EXPORTER_OTLP_ENDPOINT",
          "value": "http://localhost:4318"
        }
      ]
    },
    {
      "name": "adot-collector",
      "image": "public.ecr.aws/aws-observability/aws-otel-collector:latest",
      "essential": true,
      "mountPoints": [
        {
          "sourceVolume": "collector-config",
          "containerPath": "/etc/otel"
        }
      ],
      "command": ["--config", "/etc/otel/otel-config.yaml"]
    }
  ],
  "volumes": [
    {
      "name": "collector-config",
      "host": {
        "sourcePath": "/path/to/otel-config.yaml"
      }
    }
  ]
}

Instrumenting Applications with ADOT SDKs

To send traces to the collector, instrument your application using the ADOT auto-instrumentation SDK for your language. The SDKs automatically capture incoming and outgoing requests and export them via OTLP to the collector endpoint.

For Python applications, install the distribution package and configure the OTLP exporter:

# Install the ADOT Python auto-instrumentation

pip install aws-opentelemetry-distro==0.18.0

# Configure environment variables

export OTEL_TRACES_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:4318

# Run with instrumentation

python -m aws_otel_distro.instrumentation.run my_app.py

The skills/core-skills/aws-observability/references/application-signals-onboarding.md file contains detailed steps for enabling Application Signals, which rely on this same ADOT collector infrastructure.

Summary

• The ADOT collector configuration in skills/core-skills/aws-observability/assets/otel-config.yaml provides a complete pipeline for exporting traces to X-Ray and metrics to CloudWatch.
• The awsxray exporter translates OpenTelemetry spans to the X-Ray format and forwards them to 127.0.0.1:2000.
• Deploy the collector as a sidecar (for ECS/EKS) or daemon (for EC2) depending on your architecture.
• Use the awsproxy extension to enable centralized sampling rules from the X-Ray console.
• Instrument applications using ADOT SDKs and point them to the collector's OTLP endpoint (http://localhost:4318).

Frequently Asked Questions

What is the default endpoint for the X-Ray daemon in the ADOT collector configuration?

The default endpoint is 127.0.0.1:2000, which is the standard local port where the X-Ray daemon listens for UDP traffic. This is configured in the awsxray exporter section of otel-config.yaml.

How do I enable centralized sampling rules with X-Ray tracing?

Enable the awsproxy extension in your collector configuration. This extension allows the collector to fetch sampling rules from the X-Ray backend and apply them consistently across your distributed services, ensuring optimal trace coverage without manual configuration.

Can the ADOT collector export both traces to X-Ray and metrics to CloudWatch simultaneously?

Yes, the collector supports multiple exporters in parallel. The default configuration includes both the awsxray exporter for traces and the awsemf exporter for CloudWatch EMF metrics, allowing you to collect full observability data through a single agent.

Where is the default OpenTelemetry configuration file located in the AWS Agent Toolkit?

The default configuration is located at skills/core-skills/aws-observability/assets/otel-config.yaml in the aws/agent-toolkit-for-aws repository. This file defines the receivers, processors, and exporters needed for X-Ray tracing and CloudWatch metrics.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}