Deprecated: Collect metrics using the CloudWatch monitoring scripts - Amazon Elastic Compute Cloud
Supported systemsRequired permissionsInstall required packagesInstall monitoring scriptsmon-put-instance-data.plmon-get-instance-stats.pl View your custom metrics in the consoleTroubleshoot
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Deprecated: Collect metrics using the CloudWatch monitoring scripts

Important

The CloudWatch monitoring scripts are deprecated. We provide information about the monitoring scripts for customers who have not yet migrated from the deprecated monitoring scripts to the CloudWatch agent.

We recommend that you use the CloudWatch agent to collect metrics and logs. For more information, see Collect metrics and logs from Amazon EC2 instances and on-premises servers with the CloudWatch agent in the Amazon CloudWatch User Guide.

The monitoring scripts demonstrate how to produce and consume custom metrics for Amazon CloudWatch. These sample Perl scripts comprise a fully functional example that reports memory, swap, and disk space utilization metrics for a Linux instance.

Standard Amazon CloudWatch usage charges for custom metrics apply to your use of these scripts. For more information, see the Amazon CloudWatch pricing page.

Supported systems

The monitoring scripts were tested on instances using the following systems. Using the monitoring scripts on any other operating system is unsupported.

  • Amazon Linux 2

  • Amazon Linux AMI 2014.09.2 and later

  • Red Hat Enterprise Linux 6.9 and 7.4

  • SUSE Linux Enterprise Server 12

  • Ubuntu Server 14.04 and 16.04

Required permissions

Ensure that the scripts have permission to call the following actions by associating an IAM role with your instance:

  • cloudwatch:PutMetricData

  • cloudwatch:GetMetricStatistics

  • cloudwatch:ListMetrics

  • ec2:DescribeTags

For more information, see Work with IAM roles.

Install required packages

With some versions of Linux, you must install additional Perl modules before you can use the monitoring scripts.

To install the required packages on Amazon Linux 2 and Amazon Linux AMI

  1. Log on to your instance. For more information, see Connect to your Linux instance.

  2. At a command prompt, install packages as follows:

    sudo yum install -y perl-Switch perl-DateTime perl-Sys-Syslog perl-LWP-Protocol-https perl-Digest-SHA.x86_64
To install the required packages on Ubuntu

  1. Log on to your instance. For more information, see Connect to your Linux instance.

  2. At a command prompt, install packages as follows:

    sudo apt-get update
sudo apt-get install unzip
sudo apt-get install libwww-perl libdatetime-perl
To install the required packages on Red Hat Enterprise Linux 7

  1. Log on to your instance. For more information, see Connect to your Linux instance.

  2. At a command prompt, install packages as follows:

    sudo yum install perl-Switch perl-DateTime perl-Sys-Syslog perl-LWP-Protocol-https perl-Digest-SHA --enablerepo="rhui-REGION-rhel-server-optional" -y 
sudo yum install zip unzip
To install the required packages on Red Hat Enterprise Linux 6.9

  1. Log on to your instance. For more information, see Connect to your Linux instance.

  2. At a command prompt, install packages as follows:

    sudo yum install perl-DateTime perl-CPAN perl-Net-SSLeay perl-IO-Socket-SSL perl-Digest-SHA gcc -y
sudo yum install zip unzip

  3. Run CPAN as an elevated user:

    sudo cpan

    Press ENTER through the prompts until you see the following prompt:

    cpan[1]>

  4. At the CPAN prompt, run each of the below commands: run one command and it installs, and when you return to the CPAN prompt, run the next command. Press ENTER like before when prompted to continue through the process: 

    cpan[1]> install YAML 
cpan[2]> install LWP::Protocol::https 
cpan[3]> install Sys::Syslog 
cpan[4]> install Switch
To install the required packages on SUSE

  1. Log on to your instance. For more information, see Connect to your Linux instance.

  2. On servers running SUSE Linux Enterprise Server 12, you might need to download the perl-Switch package. You can download and install this package using the following commands:

    wget http://download.opensuse.org/repositories/devel:/languages:/perl/SLE_12_SP3/noarch/perl-Switch-2.17-32.1.noarch.rpm
sudo rpm -i perl-Switch-2.17-32.1.noarch.rpm

  3. Install the required packages as follows:

    sudo zypper install perl-Switch perl-DateTime
sudo zypper install –y "perl(LWP::Protocol::https)"

Install monitoring scripts

The following steps show you how to download, uncompress, and configure the CloudWatch monitoring scripts on an EC2 Linux instance.

To download, install, and configure the monitoring scripts

  1. At a command prompt, move to a folder where you want to store the monitoring scripts and run the following command to download them:

    curl https://aws-cloudwatch.s3.amazonaws.com/downloads/CloudWatchMonitoringScripts-1.2.2.zip -O

  2. Run the following commands to install the monitoring scripts you downloaded:

    unzip CloudWatchMonitoringScripts-1.2.2.zip && \
rm CloudWatchMonitoringScripts-1.2.2.zip && \
cd aws-scripts-mon

The package for the monitoring scripts contains the following files:

  • CloudWatchClient.pm – Shared Perl module that simplifies calling Amazon CloudWatch from other scripts.

  • mon-put-instance-data.pl – Collects system metrics on an Amazon EC2 instance (memory, swap, disk space utilization) and sends them to Amazon CloudWatch.

  • mon-get-instance-stats.pl – Queries Amazon CloudWatch and displays the most recent utilization statistics for the EC2 instance on which this script is run.

  • awscreds.template – File template for Amazon credentials that stores your access key ID and secret access key.

  • LICENSE.txt – Text file containing the Apache 2.0 license.

  • NOTICE.txt – Copyright notice.

mon-put-instance-data.pl

This script collects memory, swap, and disk space utilization data on the current system. It then makes a remote call to Amazon CloudWatch to report the collected data as custom metrics.

Options
Name Description

--mem-util

Collects and sends the MemoryUtilization metrics in percentages. This metric counts memory allocated by applications and the operating system as used, and also includes cache and buffer memory as used if you specify the --mem-used-incl-cache-buff option.

--mem-used

Collects and sends the MemoryUsed metrics, reported in megabytes. This metric counts memory allocated by applications and the operating system as used, and also includes cache and buffer memory as used if you specify the --mem-used-incl-cache-buff option.

--mem-used-incl-cache-buff

If you include this option, memory currently used for cache and buffers is counted as "used" when the metrics are reported for --mem-util, --mem-used, and --mem-avail.

--mem-avail

Collects and sends the MemoryAvailable metrics, reported in megabytes. This metric counts memory allocated by applications and the operating system as used, and also includes cache and buffer memory as used if you specify the --mem-used-incl-cache-buff option.

--swap-util

Collects and sends SwapUtilization metrics, reported in percentages.

--swap-used

Collects and sends SwapUsed metrics, reported in megabytes.

--disk-path=PATH

Selects the disk on which to report.

PATH can specify a mount point or any file located on a mount point for the filesystem that needs to be reported. For selecting multiple disks, specify a --disk-path=PATH for each one of them.

To select a disk for the filesystems mounted on / and /home, use the following parameters:

--disk-path=/ --disk-path=/home

--disk-space-util

Collects and sends the DiskSpaceUtilization metric for the selected disks. The metric is reported in percentages.

Note that the disk utilization metrics calculated by this script differ from the values calculated by the df -k -l command. If you find the values from df -k -l more useful, you can change the calculations in the script.

--disk-space-used

Collects and sends the DiskSpaceUsed metric for the selected disks. The metric is reported by default in gigabytes.

Due to reserved disk space in Linux operating systems, disk space used and disk space available might not accurately add up to the amount of total disk space.

--disk-space-avail

Collects and sends the DiskSpaceAvailable metric for the selected disks. The metric is reported in gigabytes.

Due to reserved disk space in the Linux operating systems, disk space used and disk space available might not accurately add up to the amount of total disk space.

--memory-units=UNITS

Specifies units in which to report memory usage. If not specified, memory is reported in megabytes. UNITS may be one of the following: bytes, kilobytes, megabytes, gigabytes.

--disk-space-units=UNITS

Specifies units in which to report disk space usage. If not specified, disk space is reported in gigabytes. UNITS may be one of the following: bytes, kilobytes, megabytes, gigabytes.

--aws-credential- file=PATH

Provides the location of the file containing Amazon credentials.

This parameter cannot be used with the --aws-access-key-id and --aws-secret-key parameters.

--aws-access-key-id=VALUE

Specifies the Amazon access key ID to use to identify the caller. Must be used together with the --aws-secret-key option. Do not use this option with the --aws-credential-file parameter.

--aws-secret-key=VALUE

Specifies the Amazon secret access key to use to sign the request to CloudWatch. Must be used together with the --aws-access-key-id option. Do not use this option with --aws-credential-file parameter.

--aws-iam-role=VALUE

Specifies the IAM role used to provide Amazon credentials. The value =VALUE is required. If no credentials are specified, the default IAM role associated with the EC2 instance is applied. Only one IAM role can be used. If no IAM roles are found, or if more than one IAM role is found, the script will return an error.

Do not use this option with the --aws-credential-file, --aws-access-key-id, or --aws-secret-key parameters.

--aggregated[=only]

Adds aggregated metrics for instance type, AMI ID, and overall for the Region. The value =only is optional; if specified, the script reports only aggregated metrics.

--auto-scaling[=only]

Adds aggregated metrics for the Auto Scaling group. The value =only is optional; if specified, the script reports only Auto Scaling metrics. The IAM policy associated with the IAM user or role using the scripts need to have permissions to call the EC2 action DescribeTags.

--verify

Performs a test run of the script that collects the metrics, prepares a complete HTTP request, but does not actually call CloudWatch to report the data. This option also checks that credentials are provided. When run in verbose mode, this option outputs the metrics that will be sent to CloudWatch.

--from-cron

Use this option when calling the script from cron. When this option is used, all diagnostic output is suppressed, but error messages are sent to the local system log of the user.

--verbose

Displays detailed information about what the script is doing.

--help

Displays usage information.

--version

Displays the version number of the script.

Examples

The following examples assume that you provided an IAM role or awscreds.conf file. Otherwise, you must provide credentials using the --aws-access-key-id and --aws-secret-key parameters for these commands.

The following example performs a simple test run without posting data to CloudWatch.

./mon-put-instance-data.pl --mem-util --verify --verbose

The following example collects all available memory metrics and sends them to CloudWatch, counting cache and buffer memory as used

./mon-put-instance-data.pl --mem-used-incl-cache-buff --mem-util --mem-used --mem-avail

The following example collects aggregated metrics for an Auto Scaling group and sends them to Amazon CloudWatch without reporting individual instance metrics.

./mon-put-instance-data.pl --mem-util --mem-used --mem-avail --auto-scaling=only

The following example collects aggregated metrics for instance type, AMI ID and region, and sends them to Amazon CloudWatch without reporting individual instance metrics

./mon-put-instance-data.pl --mem-util --mem-used --mem-avail --aggregated=only

To set a cron schedule for metrics reported to CloudWatch, start editing the crontab using the crontab -e command. Add the following command to report memory and disk space utilization to CloudWatch every five minutes:

*/5 * * * * ~/aws-scripts-mon/mon-put-instance-data.pl --mem-used-incl-cache-buff --mem-util --disk-space-util --disk-path=/ --from-cron

If the script encounters an error, it writes the error message in the system log.

mon-get-instance-stats.pl

This script queries CloudWatch for statistics on memory, swap, and disk space metrics within the time interval provided using the number of most recent hours. This data is provided for the Amazon EC2 instance on which this script is run.

Options
Name Description

--recent-hours=N

Specifies the number of recent hours to report on, as represented by N where N is an integer.

--aws-credential-file=PATH

Provides the location of the file containing Amazon credentials.

--aws-access-key-id=VALUE

Specifies the Amazon access key ID to use to identify the caller. Must be used together with the --aws-secret-key option. Do not use this option with the --aws-credential-file option.

--aws-secret-key=VALUE

Specifies the Amazon secret access key to use to sign the request to CloudWatch. Must be used together with the --aws-access-key-id option. Do not use this option with --aws-credential-file option.

--aws-iam-role=VALUE

Specifies the IAM role used to provide Amazon credentials. The value =VALUE is required. If no credentials are specified, the default IAM role associated with the EC2 instance is applied. Only one IAM role can be used. If no IAM roles are found, or if more than one IAM role is found, the script will return an error.

Do not use this option with the --aws-credential-file, --aws-access-key-id, or --aws-secret-key parameters.

--verify

Performs a test run of the script. This option also checks that credentials are provided.

--verbose

Displays detailed information about what the script is doing.

--help

Displays usage information.

--version

Displays the version number of the script.

Example

To get utilization statistics for the last 12 hours, run the following command:

./mon-get-instance-stats.pl --recent-hours=12

The following is an example response:

Instance metric statistics for the last 12 hours.

CPU Utilization
    Average: 1.06%, Minimum: 0.00%, Maximum: 15.22%

Memory Utilization
    Average: 6.84%, Minimum: 6.82%, Maximum: 6.89%

Swap Utilization
    Average: N/A, Minimum: N/A, Maximum: N/A

Disk Space Utilization on /dev/xvda1 mounted as /
    Average: 9.69%, Minimum: 9.69%, Maximum: 9.69%

View your custom metrics in the console

After you successfully run the mon-put-instance-data.pl script, you can view your custom metrics in the Amazon CloudWatch console.

To view custom metrics

  1. Run mon-put-instance-data.pl as described previously.

  2. Open the CloudWatch console at https://console.amazonaws.cn/cloudwatch/.

  3. Choose View Metrics.

  4. For Viewing, your custom metrics posted by the script are displayed with the prefix System/Linux.

Troubleshoot

The CloudWatchClient.pm module caches instance metadata locally. If you create an AMI from an instance where you have run the monitoring scripts, any instances launched from the AMI within the cache TTL (default: six hours, 24 hours for Auto Scaling groups) emit metrics using the instance ID of the original instance. After the cache TTL time period passes, the script retrieves fresh data and the monitoring scripts use the instance ID of the current instance. To immediately correct this, remove the cached data using the following command:

rm /var/tmp/aws-mon/instance-id