Getting Started with X-Ray Receiver in AWS Distro for OpenTelemetry Collector

AWS X-Ray is a service that collects data about requests that your application serves, and provides tools you can use to view, filter, and gain insights into that data to identify issues and opportunities for optimization. For any traced request to your application, you can see detailed information not only about the request and response, but also about calls that your application makes to downstream AWS resources, microservices, databases and HTTP web APIs.

AWS Container Observability team wrote a receiver in the OpenTelemetry Collector. This receiver takes place of the original X-Ray-daemon, listens to a UDP port, gathers raw segment data, and relays it to AWS X-ray API through the OpenTelemetry Collector.

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 are authenticated using the mechanism documented here.

Enable AWS X-Ray Receiver

To enable the awsxray receiver, write the name under receiver section in the OT config file (local/config.yaml) . The default UDP address and port on which this receiver listens for X-Ray segment documents emitted by the X-Ray SDK is 0.0.0.0:2000. The transport can only be udp.

Copy
1receivers:
2  awsxray:
3    transport: udp
4exporters:
5  awsxray:
6    region: "us-west-2"
7service:
8  extensions:
9  pipelines:
10    traces:
11      receivers: [awsxray]
12      exporters: [awsxray]

Set X-Ray Reciever Listening Endpoint

Customers can config the UDP address and port which the receiver listens for X-Ray segment documents emitted by the X-ray SDK endpoint. Using endpoint under awsxray receiver. This example configuration will set UDP address and port as 0.0.0.1:2001:

Copy
1receivers:
2  awsxray:
3    endpoint: 0.0.0.1:2001
4    transport: udp
5exporters:
6  awsxray:
7    region: "us-west-2"
8service:
9  extensions:
10  pipelines:
11    traces:
12      receivers: [awsxray]
13      exporters: [awsxray]

Set X-Ray Reciever Configurations Related to the Local TCP Proxy Server

Customers can config the local TCP proxy server through proxy_server, under awsxray. By configuring proxy_server, customers can tell xrayreceiver where it could get the sampling rules. Go to proxy server configuration to check the detailed explanation of every parameter under proxy_sever. It will use default value if customer did set it.

Copy
1receivers:
2  aws_xray:
3    endpoint: 0.0.0.1:2001
4    transport: udp
5    proxy_server:
6      endpoint: 0.0.0.0:2000
7      proxy_address: ""
8      insecure: false
9      server_name_override: ""
10      region: ""
11      role_arn: ""
12      aws_endpoint: ""
13      local_mode: false
14exporters:
15  logging:
16    loglevel: debug
17  awsxray:
18    region: "us-west-2"
19service:
20  extensions:
21  pipelines:
22    traces:
23      receivers: [awsxray]
24      exporters: [logging, awsxray]

Proxy Server Configuration

You can add additional configuration in the above proxy_server section.

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

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 it to true to skip metadata check.

Default: false