Amazon CloudWatch
User Guide

Getting Started: Installing the CloudWatch Agent on Your First Instance

To download and install the CloudWatch agent on a running Amazon EC2 instance, you can use either AWS Systems Manager or the command line. With either method, you must first create an IAM role and attach it to the instance.

Attach an IAM Role to the Instance

An IAM role for the instance profile is required when you install the CloudWatch agent on an Amazon EC2 instance. This role enables the CloudWatch agent to perform actions on the instance. Use one of the roles you created earlier. For more information about creating these roles, see Create IAM Roles and Users for Use With CloudWatch Agent. You can scroll through the list to find them, or use the search box.

If you are going to use this instance to create the CloudWatch agent configuration file and copy it to Systems Manager Parameter Store, use the role you created that has permissions to write to Parameter Store. This role may be called CloudWatchAgentAdminRole.

For all other instances, select the role that includes just the permissions needed to install and run the agent. This role may be called CloudWatchAgentServerRole.

Attach this role to the instance on which you install the CloudWatch agent. For more information, see Attaching an IAM Role to an Instance in the Amazon EC2 User Guide for Windows Instances.

Download the CloudWatch Agent Package on an Amazon EC2 Instance

You can download the CloudWatch agent package using either Systems Manager Run Command or an Amazon S3 download link.

Download the CloudWatch Agent on an Amazon EC2 Instance Using AWS Systems Manager

Before you can use Systems Manager to install the CloudWatch agent, you must make sure that the instance is configured correctly for Systems Manager.

Install or Update the SSM Agent

On an Amazon EC2 instance, the CloudWatch agent requires that the instance is running version 2.2.93.0 or later. Before you install the CloudWatch agent, update or install the SSM Agent on the instance if you haven't already done so.

For information about installing or updating the SSM Agent on an instance running Linux, see Installing and Configuring the SSM Agent on Linux Instances in the AWS Systems Manager User Guide.

For information about installing or updating the SSM Agent, see Installing and Configuring the SSM Agent in the AWS Systems Manager User Guide.

(Optional) Verify Systems Manager Prerequisites

Before you use Systems Manager Run Command to install and configure the CloudWatch agent, verify that your instances meet the minimum Systems Manager requirements. For more information, see Systems Manager Prerequisites in the AWS Systems Manager User Guide.

Verify Internet Access

Your Amazon EC2 instances must have outbound internet access in order to send data to CloudWatch or CloudWatch Logs. For more information about how to configure internet access, see Internet Gateways in the Amazon VPC User Guide.

The endpoints and ports to configure on your proxy are as follows:

  • If you are using the agent to collect metrics, you must whitelist the CloudWatch endpoints for the appropriate Regions. These endpoints are listed in Amazon CloudWatch in the Amazon Web Services General Reference.

  • If you are using the agent to collect logs, you must whitelist the CloudWatch Logs endpoints for the appropriate Regions. These endpoints are listed in Amazon CloudWatch Logs in the Amazon Web Services General Reference.

  • If you are using SSM to install the agent or Parameter Store to store your configuration file, you must whitelist the SSM endpoints for the appropriate Regions. These endpoints are listed in AWS Systems Manager in the Amazon Web Services General Reference.

Download the CloudWatch Agent Package

Systems Manager Run Command enables you to manage the configuration of your instances. You specify a Systems Manager document, specify parameters, and execute the command on one or more instances. The SSM Agent on the instance processes the command and configures the instance as specified.

To download the CloudWatch agent using Systems Manager

  1. Open the Systems Manager console at https://console.aws.amazon.com/systems-manager/.

  2. In the navigation pane, choose Run Command.

    -or-

    If the AWS Systems Manager home page opens, scroll down and choose Explore Run Command.

  3. Choose Run command.

  4. In the Command document list, choose AWS-ConfigureAWSPackage.

  5. In the Targets area, choose the instance on which to install the CloudWatch agent. If you do not see a specific instance, it might not be configured for Run Command. For more information, see Systems Manager Prerequisites in the AWS Systems Manager User Guide.

  6. In the Action list, choose Install.

  7. In the Name field, type AmazonCloudWatchAgent.

  8. Leave Version set to latest to install the latest version of the agent.

  9. Choose Run.

  10. Optionally, in the Targets and outputs areas, select the button next to an instance name and choose View output. Systems Manager should show that the agent was successfully installed.

Download the CloudWatch Agent Package on an Amazon EC2 Instance Using an S3 Download Link

You can use an Amazon S3 download link to download the CloudWatch agent package on an Amazon EC2 instance server. Choose the download link from this table, depending on your architecture and platform.

Arch Platform Download Link Signature File Link

amd64

Amazon Linux and Amazon Linux 2

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

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

amd64

Centos

https://s3.amazonaws.com/amazoncloudwatch-agent/centos/amd64/latest/amazon-cloudwatch-agent.rpm

https://s3.amazonaws.com/amazoncloudwatch-agent/centos/amd64/latest/amazon-cloudwatch-agent.rpm.sig

amd64

Redhat

https://s3.amazonaws.com/amazoncloudwatch-agent/redhat/amd64/latest/amazon-cloudwatch-agent.rpm

https://s3.amazonaws.com/amazoncloudwatch-agent/redhat/amd64/latest/amazon-cloudwatch-agent.rpm.sig

amd64

SUSE

https://s3.amazonaws.com/amazoncloudwatch-agent/suse/amd64/latest/amazon-cloudwatch-agent.rpm

https://s3.amazonaws.com/amazoncloudwatch-agent/suse/amd64/latest/amazon-cloudwatch-agent.rpm.sig

amd64

Debian

https://s3.amazonaws.com/amazoncloudwatch-agent/debian/amd64/latest/amazon-cloudwatch-agent.deb

https://s3.amazonaws.com/amazoncloudwatch-agent/debian/amd64/latest/amazon-cloudwatch-agent.deb.sig

amd64

Ubuntu

https://s3.amazonaws.com/amazoncloudwatch-agent/ubuntu/amd64/latest/amazon-cloudwatch-agent.deb

https://s3.amazonaws.com/amazoncloudwatch-agent/ubuntu/amd64/latest/amazon-cloudwatch-agent.deb.sig

amd64

Windows

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

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

arm64

Amazon Linux 2

https://s3.amazonaws.com/amazoncloudwatch-agent/amazon_linux/arm64/latest/amazon-cloudwatch-agent.rpm

https://s3.amazonaws.com/amazoncloudwatch-agent/amazon_linux/arm64/latest/amazon-cloudwatch-agent.rpm.sig

arm64

Redhat

https://s3.amazonaws.com/amazoncloudwatch-agent/redhat/arm64/latest/amazon-cloudwatch-agent.rpm

https://s3.amazonaws.com/amazoncloudwatch-agent/redhat/arm64/latest/amazon-cloudwatch-agent.rpm.sig

arm64

Ubuntu

https://s3.amazonaws.com/amazoncloudwatch-agent/ubuntu/arm64/latest/amazon-cloudwatch-agent.deb

https://s3.amazonaws.com/amazoncloudwatch-agent/ubuntu/arm64/latest/amazon-cloudwatch-agent.deb.sig

To use the command line to install the CloudWatch agent on an Amazon EC2 instance

  1. Download the CloudWatch agent. For a Linux server, type the following. For download-link, use the appropriate download link from the previous table.

    wget download-link

    For a server running Windows Server, download the following file:

    https://s3.amazonaws.com/amazoncloudwatch-agent/windows/amd64/latest/amazon-cloudwatch-agent.msi
  2. After you have downloaded the package, you can optionally use a GPG signature file to verify the package signature. For more information, see Verify the Signature of the CloudWatch Agent Package.

  3. Install the package. If you downloaded an RPM package on a Linux server, change to the directory containing the package and type the following:

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

    If you downloaded a DEB package on a Linux server, change to the directory containing the package and type the following:

    sudo dpkg -i -E ./amazon-cloudwatch-agent.deb

    If you downloaded an MSI package on a server running Windows Server, change to the directory containing the package, and type the following:

    msiexec /i amazon-cloudwatch-agent.msi

    This command also works from within PowerShell. For more information about MSI command options, see Command-Line Options in the Microsoft Windows documentation.

(Optional) Modify the Common Configuration and Named Profile for CloudWatch Agent

The CloudWatch agent package you have downloaded includes a configuration file called common-config.toml. You can use this file to specify proxy, credential, and Region information. On a server running Linux, this file is in the /opt/aws/amazon-cloudwatch-agent/etc directory. On a server running Windows Server, this file is in the C:\ProgramData\Amazon\AmazonCloudWatchAgent directory.

The default common-config.toml is as follows:

When you install the CloudWatch agent on an Amazon EC2 instance, modify this file only to specify proxy settings or if the agent should send metrics to CloudWatch in a different Region than where the instance is located.

# This common-config is used to configure items used for both ssm and cloudwatch access ## Configuration for shared credential. ## Default credential strategy will be used if it is absent here: ## Instance role is used for EC2 case by default. ## AmazonCloudWatchAgent profile is used for onPremise case by default. # [credentials] # shared_credential_profile = "{profile_name}" # shared_credential_file= "{file_name}" ## Configuration for proxy. ## System-wide environment-variable will be read if it is absent here. ## i.e. HTTP_PROXY/http_proxy; HTTPS_PROXY/https_proxy; NO_PROXY/no_proxy ## Note: system-wide environment-variable is not accessible when using ssm run-command. ## Absent in both here and environment-variable means no proxy will be used. # [proxy] # http_proxy = "{http_url}" # https_proxy = "{https_url}" # no_proxy = "{domain}"

All lines are commented out initially. To set the credential profile or proxy settings, remove the # from that line and specify a value. You can edit this file manually, or by using the RunShellScript Run Command in Systems Manager:

  • proxy settings If your servers use HTTP or HTTPS proxies to contact AWS services, specify those proxies in the http_proxy and https_proxy fields. If there are URLs that should be excluded from proxying, specify them in the no_proxy field, separated by commas.

  • shared_credential_profile To have the CloudWatch agent send metrics to CloudWatch in the same Region where the instance is located, modify this line or attach an IAM role with the proper permissions to the instance. If you attach the IAM role, you don't need to use the aws configure command to create a named profile for the agent.

    Otherwise, you can use this line to specify the named profile that CloudWatch agent is to use in the AWS config file. If you do so, CloudWatch agent uses the Region settings in that named profile.

  • shared_credential_file Use this line to specify a path to a file containing credentials to use, if you don't want to use the default path.

After modifying common-config.toml, if you need to specify Region information for the CloudWatch agent, create a named profile for the CloudWatch agent in the AWS config file. When you create this profile, do so as the root or administrator.

Following is an example of the profile for the configuration file:

[AmazonCloudWatchAgent] region = us-west-1

To be able to send the CloudWatch data to a different Region, make sure that the IAM role that you attached to this instance has permissions to write the CloudWatch data in that Region.

Following is an example of using the aws configure command to create a named profile for the CloudWatch agent. This example assumes that you are using the default profile name of AmazonCloudWatchAgent.

To create the AmazonCloudWatchAgent profile for the CloudWatch agent

  • Type the following command and follow the prompts:

    sudo aws configure --profile AmazonCloudWatchAgent

Create the Agent Configuration File on Your First Instance

After you have downloaded the CloudWatch agent, you must create the configuration file before you start the agent on any servers. For more information, see Create the CloudWatch Agent Configuration File.

Start the CloudWatch Agent

To start the agent on the same server where you created the agent configuration file, follow these steps. To use this configuration file on other servers, see Installing CloudWatch Agent on Additional Instances Using Your Agent Configuration.

Start the CloudWatch Agent Using Run Command

Follow these steps to start the agent using Systems Manager Run Command.

To start the CloudWatch agent using Run Command

  1. Open the Systems Manager console at https://console.aws.amazon.com/systems-manager/.

  2. In the navigation pane, choose Run Command.

    -or-

    If the AWS Systems Manager home page opens, scroll down and choose Explore Run Command.

  3. Choose Run command.

  4. In the Command document list, choose AmazonCloudWatch-ManageAgent.

  5. In the Targets area, choose the instance where you installed the CloudWatch agent.

  6. In the Action list, choose configure.

  7. In the Optional Configuration Source list, choose ssm.

  8. In the Optional Configuration Location box, type the name of the agent configuration file that you created and saved to Systems Manager Parameter Store, as explained in Create the CloudWatch Agent Configuration File.

  9. In the Optional Restart list, choose yes to start the agent after you have finished these steps.

  10. Choose Run.

  11. Optionally, in the Targets and outputs areas, select the button next to an instance name and choose View output. Systems Manager should show that the agent was successfully started.

Start the CloudWatch Agent on an Amazon EC2 Instance Using the Command Line

Follow these steps to use the command line to install the CloudWatch agent on an Amazon EC2 instance.

To use the command line to start the CloudWatch agent on an Amazon EC2 instance

  • In this command, -a fetch-config causes the agent to load the latest version of the CloudWatch agent configuration file, and -s starts the agent.

    Linux: Type the following if you saved the configuration file in the Systems Manager Parameter Store:

    sudo /opt/aws/amazon-cloudwatch-agent/bin/amazon-cloudwatch-agent-ctl -a fetch-config -m ec2 -c ssm:configuration-parameter-store-name -s

    Linux: Type the following if you saved the configuration file on the local computer:

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

    Windows Server: If you saved the agent configuration file in Systems Manager Parameter Store, use the following command. From the PowerShell console, type the following:

    ./amazon-cloudwatch-agent-ctl.ps1 -a fetch-config -m ec2 -c ssm:configuration-parameter-store-name -s

    Windows Server: If you saved the agent configuration file on the local computer, use the following command. From the PowerShell console, type the following:

    ./amazon-cloudwatch-agent-ctl.ps1 -a fetch-config -m ec2 -c file:configuration-file-path -s