Collecting application trace data - Amazon Elastic Container Service
Required IAM permissions for Amazon Distro for OpenTelemetry integration with Amazon X-RaySpecifying the Amazon Distro for OpenTelemetry sidecar for Amazon X-Ray integration in your task definition
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Collecting application trace data

Amazon ECS integrates with Amazon Distro for OpenTelemetry to collect trace data from your application. Amazon ECS uses an Amazon Distro for OpenTelemetry sidecar container to collect and route trace data to Amazon X-Ray. For more information, see Setting up Amazon Distro for OpenTelemetry Collector in Amazon ECS.

For the Amazon Distro for OpenTelemetry Collector to send trace data to Amazon X-Ray, your application must be configured to create the trace data. For more information, see Instrumenting your application for Amazon X-Ray in the Amazon X-Ray Developer Guide.

Required IAM permissions for Amazon Distro for OpenTelemetry integration with Amazon X-Ray

The Amazon ECS integration with Amazon Distro for OpenTelemetry requires that you create a task IAM role and specify the role in your task definition. We recommend that the Amazon Distro for OpenTelemetry sidecar also be configured to route container logs to CloudWatch Logs which requires a task execution IAM role be created and specified in your task definition as well. The new Amazon ECS console experience takes care of the task execution IAM role on your behalf, but the task IAM role must be created manually. For more information about creating a task execution IAM role, see Amazon ECS task execution IAM role.

Important

If you're also collecting application metrics using the Amazon Distro for OpenTelemetry integration, ensure your task IAM role also contains the permissions necessary for that integration. For more information, see Collecting application metrics.

To create a task IAM role for Amazon Distro for OpenTelemetry integration

  1. Open the IAM console at https://console.amazonaws.cn/iam/.

  2. In the navigation pane, choose Policies, Create policy.

  3. On the Create policy page, switch to the JSON tab, copy and paste the following IAM policy JSON into the field, then choose Next: Tags.

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

  4. (Optional) Add one or more tags to the policy, then choose Next: Review.

  5. For Name, specify AWSDistroOpenTelemetryPolicyForXray.

  6. For Description, specify an optional description, then choose Create policy.

  7. In the navigation pane, choose Roles, Create role.

  8. In the Select type of trusted entity section, choose Amazon service, Elastic Container Service.

  9. For Select your use case, choose Elastic Container Service Task, then choose Next: Permissions.

  10. In the Attach permissions policy section, search for AWSDistroOpenTelemetryPolicyForXray, select the policy, and then choose Next: Tags.

  11. For Add tags (optional), specify any custom tags to associate with the policy and then choose Next: Review.

  12. For Role name, specify AmazonECS_OpenTelemetryXrayRole and choose Create role.

Specifying the Amazon Distro for OpenTelemetry sidecar for Amazon X-Ray integration in your task definition

The new Amazon ECS console experience simplifies the experience of creating the Amazon Distro for OpenTelemetry sidecar container by using the Use trace collection option. For more information, see Creating a task definition using the console.

If you're not using the Amazon ECS console, you can add the Amazon Distro for OpenTelemetry sidecar container to your task definition. The following task definition snippet shows the container definition for adding the Amazon Distro for OpenTelemetry sidecar for Amazon X-Ray integration.

{
	"family": "otel-using-xray",
	"taskRoleArn": "arn:aws:iam::111122223333:role/AmazonECS_OpenTelemetryXrayRole",
	"executionRoleArn": "arn:aws:iam::111122223333:role/ecsTaskExecutionRole",
	"containerDefinitions": [{
			"name": "aws-otel-emitter",
			"image": "application-image",
			"logConfiguration": {
				"logDriver": "awslogs",
				"options": {
					"awslogs-create-group": "true",
					"awslogs-group": "/ecs/aws-otel-emitter",
					"awslogs-region": "us-east-1",
					"awslogs-stream-prefix": "ecs"
				}
			},
			"dependsOn": [{
				"containerName": "aws-otel-collector",
				"condition": "START"
			}]
		},
		{
			"name": "aws-otel-collector",
			"image": "public.ecr.aws/aws-observability/aws-otel-collector:v0.29.0",
			"essential": true,
			"command": [
				"--config=/etc/ecs/otel-instance-metrics-config.yaml"
			],
			"logConfiguration": {
				"logDriver": "awslogs",
				"options": {
					"awslogs-create-group": "True",
					"awslogs-group": "/ecs/ecs-aws-otel-sidecar-collector",
					"awslogs-region": "us-east-1",
					"awslogs-stream-prefix": "ecs"
				}
			}
		}
	],
	"networkMode": "awsvpc",
	"requiresCompatibilities": [
		"FARGATE"
	],
	"cpu": "1024",
	"memory": "3072"
}