How do I install and configure the unified CloudWatch agent to send metrics and logs from my EC2 instance to CloudWatch?

Resolution

Before you begin, establish internet connectivity in your EC2 instance. The EC2 instance must have internet connectivity to connect to the required endpoints.

Create an IAM role to run the CloudWatch agent on your EC2 instance

Complete the following steps:

1. Open the AWS Identify and Access Management (IAM) console.
2. In the navigation pane, choose Roles.
3. Choose Create role.
4. For Choose the service that will use this role, choose EC2.
5. Choose Next: Permissions.
6. In the list of policies, select CloudWatchAgentServerPolicy.
7. Choose Next: Tags, and then choose Next: Review.
8. For Role name, enter a name for the role, such as CloudWatchAgentServerRole.
9. (Optional) Provide a role description.
10. Confirm that CloudWatchAgentServerPolicy appears next to Policies.
11. Choose Create role.
12. Attach the new IAM role to the EC2 instance.

Download and install the unified CloudWatch agent

Linux EC2 instance

Complete the following steps:

1. To download the CloudWatch agent, run the following command in your terminal:

   wget https://s3.region.amazonaws.com/amazoncloudwatch-agent-region/amazon_linux/amd64/latest/amazon-cloudwatch-agent.rpm

   Note: In the preceding command, replace region with your AWS Region.

2. To install the CloudWatch agent, run the following command in your terminal:

   sudo rpm -U ./amazon-cloudwatch-agent.rpm

Windows EC2 instance

Complete the following steps as an administrator in Windows PowerShell:

1. Navigate to the folder where you want to download the installer:

   cd "path"

   Note: In the preceding command, replace path with the path to the folder where you want to download the installer.

2. To download the CloudWatch agent, run the following command:

   Invoke-WebRequest -Uri https://s3.region.amazonaws.com/amazoncloudwatch-agent-region/windows/amd64/latest/amazon-cloudwatch-agent.msi -outFile amazon-cloudwatch-agent.msi

   Note: In the preceding command, replace region with your Region.

   If your TLS version is earlier than version 1.2, the you get the following error when you run the preceding Invoke-WebRequest command:

   "Invoke-WebRequest : The request was aborted: Could not create SSL/TLS secure channel"

   To configure your TLS version, run the following command, and then run the preceding Invoke-WeRequest command again:

   [Net.ServicePointManager]::SecurityProtocol = "Tls, Tls11, Tls12, Ssl3"

3. To start the agent installer, run the following command:

   msiexec /i amazon-cloudwatch-agent.msi

Create the agent configuration file

To create the agent configuration file, use the wizard. Then, manually edit the file to add or remove metrics or logs.

Linux EC2 instance

Run the following command:

sudo /opt/aws/amazon-cloudwatch-agent/bin/amazon-cloudwatch-agent-config-wizard

Windows EC2 instance

Run the following command as an administrator in Windows PowerShell:

cd "C:\Program Files\Amazon\AmazonCloudWatchAgent"  
.\amazon-cloudwatch-agent-config-wizard.exe

The wizard creates the agent configuration file with the path C:\Program Files\Amazon\AmazonCloudWatchAgent\config.json by default.

Start the CloudWatch agent

Linux EC2 instance

Run the following command:

sudo /opt/aws/amazon-cloudwatch-agent/bin/amazon-cloudwatch-agent-ctl -a fetch-config -m ec2 -c file:configuration-file-path -s

Note: In the preceding example, replace configuration-file-path with the path for your configuration file.

Windows EC2 instance

Run the following command as an administrator in Windows PowerShell:

& "C:\Program Files\Amazon\AmazonCloudWatchAgent\amazon-cloudwatch-agent-ctl.ps1" -a fetch-config -m ec2 -c file:configuration-file-path -s

Note: In the preceding command, replace configuration-file-path with the path for your configuration.

By default, the agent sends metrics to NameSpace CWAgent.

Verify the agent status

The agent takes time to populate the metrics that you configured in CloudWatch. To verify whether the agent is running before the agent populates metrics, run the following commands.

Linux EC2 instance:

sudo /opt/aws/amazon-cloudwatch-agent/bin/amazon-cloudwatch-agent-ctl -m ec2 -a status

Windows EC2 instance:

& "C:\Program Files\Amazon\AmazonCloudWatchAgent\amazon-cloudwatch-agent-ctl.ps1" -m ec2 -a status

Tips for the agent configuration file wizard

Use the following tips to help you answer questions when you're using the agent configuration file wizard.

Do you want to turn on StatsD daemon? and Do you want to monitor metrics from collectd? If you have the StatsD and collectd plugins installed on your EC2 instance, then choose Yes for these questions.

Which default metrics configuration do you want? For more information about default configurations, see CloudWatch agent predefined metric sets. Then, choose the option that's best for your use case.

Do you have an existing CloudWatch Logs Agent configuration file to import for migration? If you installed awslogs agent and it's running, then choose Yes. If you choose Yes, then the wizard reads the awslogs agent configuration file, /etc/awslogs/awslogs.conf or /var/awslogs/etc/awslogs.conf, to determine the log files that you must monitor.

Do you want to store the configuration in the Parameter Store, a capability of AWS Systems Manager? To store the agent configuration file in Parameter Store to reuse the file later, choose Yes. When you store the agent configuration file in Parameter Store, the command to start the agent varies.

After you configure the wizard, the agent configuration file is stored in /opt/aws/amazon-cloudwatch-agent/bin/config.json by default. To add or remove metrics or logs, you can manually edit the file.

For a custom configuration file example, see CloudWatch agent configuration file: Complete examples.

Note: When you modify the agent configuration file, use the fetch-config command to start the agent to make sure that the agent reflects your changes.

Start and stop the CloudWatch agent

For more information, see Stopping and restarting the CloudWatch agent.