AWS X-Ray

Configuring the AWS X-Ray backend (Managed)

Getting Started

Make sure that you have the necessary AWS Credentials and permissions set up.
AWS credentials are retrieved from the default credential chain.

Setting up AWS credentials with AWS EKS (Elastic Kubernetes Service)

The following command will create a link between your EKS cluster and your IAM account, effectively allowing the EKS cluster to assume IAM roles and access AWS services.

Replace $EKS_CLUSTER_REGION with the region of your EKS cluster and $EKS_CLUSTER_NAME with the name of your EKS cluster (or set them as environment variables).

eksctl utils associate-iam-oidc-provider --region=$EKS_CLUSTER_REGION --cluster=$EKS_CLUSTER_NAME --approve

Setting up the IAM policy

{
  "Version": "2012-10-17",
  "Statement": {
    "Effect": "Allow",
    "Action": [
      "xray:PutTraceSegments",
      "xray:PutTelemetryRecords"
    ],
    "Resource": [
      "*"
    ]
  }
}

Configuring Destination Fields

Supported Signals:

✅ Traces ❌ Metrics ❌ Logs

• AWS_XRAY_REGION string : Region. Send segments to AWS X-Ray service in a specific region.
  • This field is optional
• AWS_XRAY_ENDPOINT string : Endpoint. Optionally override the default X-Ray service endpoint.
  • This field is optional
• AWS_XRAY_PROXY_ADDRESS string : Proxy Address. Upload segments to AWS X-Ray through a proxy.
  • This field is optional
• AWS_XRAY_RESOURCE_ARN string : Resource ARN. Amazon Resource Name (ARN) of the AWS resource running the collector.
  • This field is optional
• AWS_XRAY_ROLE_ARN string : Role ARN. IAM role to upload segments to a different account.
  • This field is optional
• AWS_XRAY_EXTERNAL_ID string : External ID. Shared identitier used when assuming an IAM role in an external AWS account.
  • This field is optional
• AWS_XRAY_LOG_GROUPS string[] : Log Groups. List of log group names for CloudWatch.
  • This field is optional
• AWS_XRAY_DISABLE_SSL boolean : Disable SSL Verification. Enable or disable TLS certificate verification.
  • This field is optional and defaults to False
• AWS_XRAY_LOCAL_MODE boolean : Local Mode. Local mode to skip EC2 instance metadata check.
  • This field is optional and defaults to False
• AWS_XRAY_TELEMETRY_ENABLED boolean : Telemetry - Enabled. Whether telemetry collection is enabled at all.
  • This field is optional and defaults to False
• AWS_XRAY_TELEMETRY_INCLUDE_METADATA boolean : Telemetry - Include Metadata. Whether to include metadata in the telemetry (InstanceID, Hostname, ResourceARN)
  • This field is optional and defaults to False
• AWS_XRAY_TELEMETRY_HOSTNAME string : Telemetry - Hostname. Sets the Hostname included in the telemetry.
  • This field is optional
• AWS_XRAY_TELEMETRY_INSTANCE_ID string : Telemetry - Instance ID. Sets the InstanceID included in the telemetry.
  • This field is optional
• AWS_XRAY_TELEMETRY_RESOURCE_ARN string : Telemetry - Resource ARN. Sets the Amazon Resource Name (ARN) included in the telemetry.
  • This field is optional
• AWS_XRAY_TELEMETRY_CONTRIBUTORS string[] : Telemetry - Contributors. List of X-Ray component IDs contributing to the telemetry (ex. for multiple X-Ray receivers: awsxray/1, awsxray/2)
  • This field is optional
• AWS_XRAY_INDEX_ALL_ATTRIBUTES boolean : Index All Attributes. Enable or disable conversion of all OpenTelemetry attributes to X-Ray annotations.
  • This field is optional and defaults to False
• AWS_XRAY_INDEXED_ATTRIBUTES string[] : Indexed Attributes. List of attribute names to be converted to X-Ray annotations.
  • This field is optional

Traces and logs correlation

AWS X-Ray can be integrated with CloudWatch Logs to correlate traces with logs.

For this integration to work, the X-Ray segments must have the AWS Property cloudwatch_logs set. This property is set using the AWS X-Ray exporter with the following values that are evaluated in this order:

1. aws.log.group.arns resource attribute.
2. aws.log.group.names resource attribute.
3. aws_log_groups configuration property.

aws.log.group.arns and aws.log.group.names are slice resource attributes, alternatively those resource attributes can be set using the OTEL_RESOURCE_ATTRIBUTES environment variable.

To set multiple log group names / log group arns, you can use & to separate them.
For example 3 log groups: log-group1, log-group2, and log-group3 are set in the following command:

export OTEL_RESOURCE_ATTRIBUTES="aws.log.group.names=log-group1&log-group2&log-group3"

Adding Destination to Odigos

There are two primary methods for configuring destinations in Odigos:

Using the UI

1. Use the Odigos CLI to access the UI

   odigos ui
   

2. Click on Add Destination, select AWS X-Ray and follow the on-screen instructions

Using Kubernetes manifests

1. Save the YAML below to a file (e.g. xray.yaml)

   apiVersion: odigos.io/v1alpha1
   kind: Destination
   metadata:
     name: xray-example
     namespace: odigos-system
   spec:
     data: {}
     destinationName: xray
     signals:
     - TRACES
     type: xray
   

2. Apply the YAML using kubectl

   kubectl apply -f xray.yaml