Setting up AWS Distro for OpenTelemetry Collector in Amazon Elastic Computer Cloud

In this tutorial, we will demonstrate how to set up AWS Distro for OpenTelemetry Collector (ADOT Collector) on Amazon Elastic Computer Cloud(EC2) to collect application metrics.

Note This tutorial will set up ADOT Collector on an Amazon EC2 instance in us-west-2 with a provided CloudFormation template. if you want to run the example in the other AWS regions, please replace AMI ID in CloudFormation template we provided.

Create IAM Policy

See the Permissions section for the permissions required and IAM policy setup steps.

Attach the IAM Policy

1. Open the IAM console.
2. In the navigation pane, choose Roles, and then choose Create role.
3. In the Select type of trusted entity section, choose AWS service.
4. For Choose a use case, select EC2, then choose Next: Permission.
5. For Attach permissions policies, choose the policy AWSDistroOpenTelemetryPolicy, and then choose Next: Tags.
6. Choose Next: Review.
7. On the Review page, type AWSDistroOpenTelemetryRole for the Name, and then choose Create role.

Install AWS Distro for OpenTelemetry Collector on EC2 instance using CloudFormation

1. Download the CloudFormation template file aws-otel-ec2-deployment-cfn.yaml for installing ADOT Collector on Amazon EC2.

Copy
curl -O https://raw.githubusercontent.com/aws-observability/aws-otel-collector/main/deployment-template/ec2/aws-otel-ec2-deployment-cfn.yaml

2. Replace the below parameters and then run AWS CloudFormation CLI command. It will launch one EC2 instance with ADOT Collector installed.
   • ec2-ssh-key-name - the key pair name for login to EC2 instance
   • template_path - the local location where CloudFormation template file is downloaded in step 1

Copy
1Region=us-west-2
2IAMRole=AWSDistroOpenTelemetryRole
3EC2Key=<*ec2**-**ssh**-**key**-**name*>
4aws cloudformation create-stack --stack-name AOCEC2-Test \
5    --template-body file://<*template_path*>/aws-otel-ec2-deployment-cfn.yaml \
6    --parameters ParameterKey=IAMRole,ParameterValue=${IAMRole} \
7                 ParameterKey=KeyName,ParameterValue=${EC2Key} \
8    --capabilities CAPABILITY_NAMED_IAM \
9    --region ${Region}

3. Go to Amazon EC2 Console and verify there is a new EC2 instance that has been launched.
4. Select the instance, and then choose Connect. You can login to the EC2 host with the example command below.

Copy
ssh -i "<ec2-ssh-key-name>.pem" ec2-user@ec2-<instance_id>.us-west-2.compute.amazonaws.com (mailto:ec2-user@ec2-34-221-1-180.us-west-2.compute.amazonaws.com)

5. Check if ADOT Collector is set up and running on the new EC2 instance. If it is, you’ll see the following status.

Copy
sudo /opt/aws/aws-otel-collector/bin/aws-otel-collector-ctl -a status

Install AWS Distro for OpenTelemetry Collector on EC2 instance using AWS Systems Manager Distributor

AWS Systems Manager Distributor can simplify and scale distribution, installation, and update process of software package, such as AWS Distro for OpenTelemetry Collector. With Distributor, you manage your software packages from a centralized location. Software packages are securely stored in Systems Manager, providing a centralized repository with version control. You can use Run Command to install AWS Distro for OpenTelemetry Collector on demand, or you can use State Manager to update AWS Distro for OpenTelemetry Collector on target instances automatically or on a schedule.

To use AWS Systems Manager Distributor to install ADOT Collector on EC2 instances, the target EC2 instances need to meet following requirements.

• SSM agent version 2.3.1550.0 or later installed
• Permissions Policy AmazonSSMManagedInstanceCore attached in IAM Role of EC2 instance

To install AWSDistroOTel-Collector package using AWS Systems Manager Distributor.

1. Based on your preferences, prepare AWS Distro for OpenTelemetry Collector YAML configuration file according to ADOT Collector Configuration.

2. SSM parameter doesn't support mulit-line text as String Type. So encode AWS Distro for OpenTelemetry Collector YAML configuration file as Base64 and copy the Base64 string to a new SSM parameter in SSM Parameter Store. Listed below are examples to do Base64 encoding:

   • Linux: base64 -w0 config.yaml > aoc-config-base64.txt
   • Windows: certutil.exe -f -encodehex config.yaml aoc-config-base64.txt 0x40000001
   • MacOSX: base64 -i config.yaml -o aoc-config-base64.txt

3. Navigate to the SSM Distributor console and open the Owned by Amazon tab. Select AWSDistroOTel-Collector and choose Install one time.

   

4. Update the SSM parameter you created in the first step by replacing Additional Arguments with the following (e.g. SSM parameter name is "aoc-config-base64"):

Copy
{"SSM_CONFIG": "{{ssm:aoc-config-base64}}"}

5. Continue to select the EC2 instances by EC2 instance tags, EC2 instance IDs or Resource Group in Targets and click Run button to start installation. Visit Install or update packages for more installation options.

To install AWSDistroOTel-Collector package on EC2 instances of Auto Scaling groups.

1. Navigate to the SSM Distributor console and open the Owned by Amazon tab. Select AWSDistroOTel-Collector and choose Install on a schedule.

   

2. Update the SSM parameter you created in the previous step by replacing Additional Arguments with the following (e.g. SSM parameter name is "aoc-config-base64"):

Copy
{"SSM_CONFIG": "{{ssm:aoc-config-base64}}"}

3. Select Specify instance tags in Targets. Add aws:autoscaling:groupName as Tag key and name of Auto Scaling group as Tag value. In this example, the name of Auto Scaling group is my-first-asg.

   

4. Set schedule in Specify schedule and default is 30 minutes. So Systems Manager will scan tag of Auto Scaling group and install AWSDistroOTel-Collector package in new EC2 instances every 30 minutes.

   

Notes

The SSM distributor creates an environment file at /opt/aws/aws-otel-collector/etc/.env . Any environment variable that will be used in the open telemetry configuration needs to be added to this file.

After you finished the tutorial, remember to shut down the new EC2 instance we created in the tutorial in order to avoid additional charges.