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

Resolution

Prerequisite: Establish internet connectivity in your Amazon 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 instance

Complete the following steps:

1. Open the AWS Identity and Access Management (IAM) console.
2. In the navigation pane, choose Roles.
3. Choose Create role.
4. For Service or use case, choose EC2.
5. Choose Next.
6. In the list of policies, select CloudWatchAgentServerPolicy.
7. Choose Next.
8. Provide the following information:
   For Role name, enter a name for the role, such as CloudWatchAgentServerRole.
   For Description, provide a description for the role.
9. In the Permissions policy summary section, confirm that CloudWatchAgentServerPolicy appears.
10. Choose Create role.
11. Attach the new IAM role to the instance.

Download and install the unified CloudWatch agent

Linux instance

Complete the following steps:

1. Run the following wget command to download the CloudWatch agent:

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

   Note: Replace REGION with your AWS Region.
2. Run the following command to install the CloudWatch agent:

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

Windows instance

Complete the following steps as an administrator in AWS Tools for PowerShell:

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

   cd "path"

   Note: Replace path with the path to the folder where you want to download the installer.

2. To download the CloudWatch agent, run the following Invoke-WebRequest 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: Replace REGION with your Region. If your TLS version is earlier than version 1.2, then 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"

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

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

4. Run the following command to start the agent installer:

   msiexec /i amazon-cloudwatch-agent.msi

Create the agent configuration file

To create the agent configuration file, use the wizard. To answer the questions in the agent configuration file wizard, use the following information as a guide.

Guide to answer wizard questions

Do you want to turn on StatsD daemon? Do you want to monitor metrics from collectd?

If you have the StatsD and collectd plugins installed on your 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. 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.

Use the wizard

For Linux instances, run the following command:

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

For Windows instances, run the following command as an administrator in Tools for PowerShell:

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

The wizard stores the agent configuration file at the following default paths:

Linux: /opt/aws/amazon-cloudwatch-agent/bin/config.json

Windows: C:\Program Files\Amazon\AmazonCloudWatchAgent\config.json

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

Then, edit the file to add or remove metrics or logs.

To apply changes to the configuration file, run the fetch-config command to restart the agent.

Start the CloudWatch agent

Note: In the following commands, replace configuration-file-path with the path for your configuration file.

For Linux instances, 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

For Windows instances, run the following command as an administrator in Tools for PowerShell:

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

By default, the agent sends metrics to the CWAgent namespace.

Verify the agent status

After the agent starts, it might take a few minutes to publish metrics to CloudWatch. To verify whether the agent is running before metrics appear in CloudWatch, run the following commands.

For Linux instances, run the following command:

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

For Windows instance, run the following command:

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