AWS Open Distro for OpenTelemetry

Getting Started with the AWS X-Ray Exporter in the Collector

Getting Started with the AWS X-Ray Exporter in the Collector

The OpenTelemetry Collector has three key components: the receiver, exporter, and processor. The receiver in the OpenTelemetry Collector is responsible for receiving data via gRPC or HTTP using the OpenTelemetry protocol (OTLP). The AWS X-Ray exporter available in the OpenTelemetry Collector converts OTLP formatted trace data to the AWS X-Ray format and then exports this data to the AWS X-Ray service.

In this guide, we will demonstrate how to configure the AWS Distro for the OpenTelemetry (ADOT) Collector for use with AWS X-Ray. To learn more about AWS X-Ray, see the X-Ray Developer Guide.




Prerequisites

To get started using the ADOT Collector to connect with AWS X-Ray to analyze distributed traces, you have to first install AWS Distro for the OpenTelemetry Collector. Make sure you have your access key ID and secret access key properly configured in the docker file. You can generate access key ID and secret access key with the information here.

In order to set up the ADOT Collector on a particular platform such as EKS, ECS, EC2 or on-premises, please see the Getting Started guide for

ADOT also includes fully managed AWS Lambda Layers, which include an OpenTelemetry SDK and the ADOT Collector to auto-instrument your function for tracing with X-Ray. See AWS Distro for OpenTelemetry Lambda to get started.




Configuring the OTLP Receiver

To enable the OTLP receiver, we include the “otlp” flag in the definitions. You will have to set the “endpoint” consisting of <host>:<port> for the gRPC or HTTP protocols. You can change the endpoints depending on how you set up your instrumentation with OpenTelemetry.

Example:

1receivers:
2 otlp:
3 protocols:
4 grpc:
5 endpoint: 0.0.0.0:4317
6 http:
7 endpoint: 0.0.0.0:55681

Note: A protocol can be disabled by not specifying it in the list of protocols.




Configuring the AWS X-Ray Exporter

By default, the AWS Distribution for the OpenTelemetry Collector has enabled exporting to AWS X-Ray without any additional configurations - converting the AWS X-Ray OTLP formatted trace data to the AWS X-Ray format and then exports this data to the AWS X-Ray service. For additional configuration options of the AWS X-Ray exporter in the Collector, you can find the comprehensive list here.

Example:

1exporters:
2 awsxray:
3 # you can add additional configuration here
4 # for example configure sending traces to AWS X-Ray in a specific region
5 region: us-west-2

Note: These configurations are optional

Enable The Customized X-Ray Annotations

By using OpenTelemetry SDK, we can add the customized attributes for each trace subsegment. By default, these OpenTelemetry attributes will be converted into metadata attributes in X-Ray raw data. If we need to convert some or all OpenTelemetry attributes into X-Ray annotation, we can follow the steps below for enabling annotation conversion.

Step 1: create an attribute by using OpenTelemetry SDK

For example:

setAttribute(“TransactionId”, <value>)
setAttribute(“AccountId”, <value>)

Note: More detailed instructions for adding attributes can be found in individual languages' guides

Step 2: In the collector, set the config in one of two ways

For specific attributes to be indexed:

1awsxray:
2 indexed_attributes: ["TransactionId", "AccountId"]

For all attributes to be indexed:

1awsxray:
2 index_all_attributes: true



Sample Collector Configuration (Putting it Together)

This is a sample configuration without additional configurations in the exporter:

1receivers:
2 otlp:
3 protocols:
4 grpc:
5 endpoint: 0.0.0.0:4317
6 http:
7 endpoint: 0.0.0.0:55681
8
9exporters:
10 awsxray:
11
12processors:
13 memorylimiter:
14 limit_mib: 100
15 check_interval: 5s
16
17service:
18 pipelines:
19 traces:
20 processors:
21 - memorylimiter
22 receivers:
23 - otlp
24 exporters:
25 - awsxray



Using the ADOT SDKs

AWS Distro for OpenTelemetry currently supports applications written in Go, Java, JavaScript, .NET, and Python. Check out the Getting Started guides for the respective languages.

If the OpenTelemetry Collector is configured correctly and an application is instrumented to generate traces, we should be able see the traces on the AWS X-Ray console.

Diagram



Questions, Issues, Missing Documentation

If you have questions or issues with this guide, you can submit an issue on the AWS Observability community page to let us know. This website is also open source, so you can submit a pull request directly to update this guide on GitHub.