Skip to main content

​
Awsxray Receiver

Status Available in: contrib Maintainers: @wangzlei, @srprash Source: opentelemetry-collector-contrib

​
Supported Telemetry

Traces

​
Overview

​
Overview

The AWS X-Ray receiver accepts segments (i.e. spans) in the X-Ray Segment format. This enables the collector to receive spans emitted by the existing X-Ray SDK. Centralized sampling is also supported via a local TCP port. The requests sent to AWS using the go sdk’s default authentication mechanism.

​
Configuration

Example: 
receivers:
  awsxray:
    endpoint: 0.0.0.0:2000
    transport: udp
    proxy_server:
      endpoint: 0.0.0.0:2000
      proxy_address: ""
      tls:
        insecure: false
        server_name_override: ""
      region: ""
      role_arn: ""
      aws_endpoint: ""
      local_mode: false
The default configurations below are based on the default configurations of the existing X-Ray Daemon.

​
endpoint (Optional)

The UDP address and port on which this receiver listens for X-Ray segment documents emitted by the X-Ray SDK. Default: localhost:2000 See our security best practices doc to understand how to set the endpoint in different environments.

​
transport (Optional)

This should always be “udp” as X-Ray SDKs only send segments using UDP. Default: udp

​
proxy_server (Optional)

Defines configurations related to the local TCP proxy server.

​
endpoint (Optional)

The TCP address and port on which this receiver listens for calls from the X-Ray SDK and relays them to the AWS X-Ray backend to get sampling rules and report sampling statistics. Default: 0.0.0.0:2000 See our security best practices doc to understand how to set the endpoint in different environments.

​
proxy_address (Optional)

Defines the proxy address that the local TCP server forwards HTTP requests to AWS X-Ray backend through. If left unconfigured, requests will be sent directly.

​
insecure (Optional)

Enables or disables TLS certificate verification when the local TCP server forwards HTTP requests to the AWS X-Ray backend. This sets the InsecureSkipVerify in the TLSConfig. When setting to true, TLS is susceptible to man-in-the-middle attacks so it should be used only for testing. Default: false

​
server_name_override (Optional)

This sets the “ServerName` in the TLSConfig.

​
region (Optional)

The AWS region the local TCP server forwards requests to. When missing, we will try to retrieve this value through environment variables or optionally ECS/EC2 metadata endpoint (depends on local_mode below).

​
role_arn (Optional)

The IAM role used by the local TCP server when communicating with the AWS X-Ray service. If non-empty, the receiver will attempt to call STS to retrieve temporary credentials, otherwise the standard AWS credential lookup will be performed.

​
aws_endpoint (Optional)

The X-Ray service endpoint which the local TCP server forwards requests to.

​
local_mode (Optional)

Determines whether the ECS/EC2 instance metadata endpoint will be called to fetch the AWS region to send requests to. Set to true to skip metadata check. Default: false

​
Configuration

​
Example Configuration

awsxray: # ensure the default configurations are correctly generated

awsxray/udp_endpoint:
  # ensure the UDP endpoint can be properly overwritten
  endpoint: "0.0.0.0:5678"
  # transport can only be "udp"
  transport: udp

awsxray/proxy_server:
  # ensure the fields under proxy_server can be overwritten
  proxy_server:
    endpoint: "0.0.0.0:1234"
    proxy_address: "https://proxy.proxy.com"
    tls:
      insecure: true
      server_name_override: "something"
    region: "us-west-1"
    role_arn: "arn:aws:iam::123456789012:role/awesome_role"
    aws_endpoint: "https://another.aws.endpoint.com"
    local_mode: true
Last generated: 2026-04-13