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

4 minute read
1

I want to use the unified Amazon CloudWatch agent to push metrics and logs from my Amazon Elastic Compute Cloud (Amazon EC2) instance to Amazon CloudWatch.

Resolution

Note: 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

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 the CloudWatchAgentServerPolicy check box.

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 on your EC2 instance

Amazon Linux, Amazon Linux 2, and Amazon Linux 2023

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

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

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

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

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

Windows

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

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

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

2.    Move to the directory containing the package, and then enter the following command:

msiexec /i amazon-cloudwatch-agent.msi

Create the agent configuration file

Note: For simplicity, use the wizard to create the agent configuration file. Later, manually edit the file to add or remove metrics or logs. For more information, see the following section, Tips for completing the agent configuration file wizard.

Amazon Linux, Amazon Linux 2, and Amazon Linux 2023

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

Windows

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

By default, the wizard creates the agent configuration file in the following location: C:\Program Files\Amazon\AmazonCloudWatchAgent\config.json.

Start the CloudWatch agent

Amazon Linux, Amazon Linux 2, and Amazon Linux 2023

To start the CloudWatch agent, 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 your configuration file path.

Windows

Enter the following command in PowerShell as an administrator:

& $Env:ProgramFiles\Amazon\AmazonCloudWatchAgent\amazon-cloudwatch-agent-ctl.ps1 -a fetch-config -m ec2 -c file:configuration-file-path -s 

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

Example command:

& $Env:ProgramFiles\Amazon\AmazonCloudWatchAgent\amazon-cloudwatch-agent-ctl.ps1 -a fetch-config -m ec2 -c file:'C:\Program Files\Amazon\AmazonCloudWatchAgent\config.json' -s

Metrics and logs are now pushed to CloudWatch. By default, the agent pushes metrics to NameSpace CWAgent.

Tips for configuring 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 on detail 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 awslogs agent is installed and 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? If you want to store this agent configuration file in the Parameter Store to reuse the file later, then choose Yes.
    Important: When you store the agent configuration file in the Parameter Store, the command for starting the agent varies.
  • When you complete the wizard, the agent configuration file is stored in /opt/aws/amazon-cloudwatch-agent/bin/config.json by default. You can manually edit this file to add or remove metrics or logs.

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.