| « PreviousNext » | |
   | Did this page help you? Yes | No | Tell us about it... |
Amazon CloudWatch Monitoring Scripts for Windows
The Amazon CloudWatch Monitoring Scripts for Windows are sample PowerShell scripts that demonstrate how to produce and consume Amazon CloudWatch custom metrics. The scripts comprise a fully functional example that reports memory, page file, and disk space utilization metrics for an Amazon Elastic Compute Cloud (Amazon EC2) Windows instance.
You can download Amazon CloudWatch Monitoring Scripts for Microsoft Windows Server from the Amazon Web Services (AWS) sample code library. The AmazonCloudWatchMonitoringWindows.zip package contains these files:
mon-put-metrics-mem.ps1 —Collects system metrics on an Amazon EC2 Windows instance (memory, page file utilization) and sends them to Amazon CloudWatch.
mon-put-metrics-disk.ps1 —Collects system metrics on an Amazon EC2 instance (disk space utilization) and sends them to Amazon CloudWatch.
mon-put-metrics-perfmon.ps1 —Collects PerfMon counters on an Amazon EC2 instance and sends them to Amazon CloudWatch.
mon-get-instance-stats.ps1—Queries Amazon CloudWatch and displays the most recent utilization statistics for the EC2 instance on which this script is executed.
awscreds.conf—File template for AWS 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.
These monitoring scripts are intended for use with Amazon EC2 instances running Microsoft Windows Server. The scripts have been tested on the following Amazon Machine Images (AMIs) for both 32-bit and 64-bit versions:
Windows Server 2003 R2
Windows Server 2008
Windows Server 2008 R2
Getting Started
The following steps demonstrate how to download, un-compress, and configure the Amazon CloudWatch Monitoring Scripts on an Amazon EC2 Windows instance.
To download, install, and configure the script
Connect to your Amazon EC2 Windows instance. For information about how to connect to Amazon EC2 Windows instances, see Connecting to Windows Instances in the Amazon EC2 User Guide.
Download and install the AWS SDK for .NET onto the EC2 instance that you want to monitor.
Download the .zip file containing the Amazon CloudWatch Monitoring Scripts for Microsoft Windows Server onto the EC2 instance and unzip it in a location of your preference.
Update the awscreds.conf file that you downloaded earlier. The content of this file should use the following format:
AWSAccessKeyId=YourAccessKeyIDAWSSecretKey=YourSecretAccessKeyNote
This step is optional if you have already created a file for credentials. You can use an existing file by specifying its location on the command line when you call the scripts. Alternatively, you can set the environment variable
AWS_CREDENTIAL_FILEto point to the file with your AWS credentials.For instructions on how to access your credentials, use the following procedure.
To view your AWS access credentials
Go to the Amazon Web Services website at http://aws.amazon.com.
Click My Account/Console, and then click Security Credentials.
Under Your Account, click Security Credentials.
In the spaces provided, type your user name and password, and then click Sign in using our secure server.
Under Access Credentials, on the Access Keys tab, your access key ID is displayed. To view your secret key, under Secret Access Key, click Show.
As a best practice, do not use the root credentials. Instead you should create an Identity and Access Management (IAM) user with a policy that restricts the user to only Amazon CloudWatch operations. For more information, see Controlling User Access to Your AWS Account
Using the Scripts
mon-put-metrics-mem.ps1
This script collects memory and pagefile 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 |
|---|---|
|
|
Collects and sends the MemoryUtilization metrics in percentages. This option reports only memory allocated by applications and the operating system, and excludes memory in cache and buffers. |
|
|
Collects and sends the MemoryUsed metrics, reported in megabytes. This option reports only memory allocated by applications and the operating system, and excludes memory in cache and buffers. |
|
|
Collects and sends the MemoryAvailable metrics, reported in megabytes. This option reports memory available for use by applications and the operating system. |
|
|
Collects and sends PageUtilization metrics, reported in percentages. Page utilization is reported for each page file in a windows instance. |
|
|
Collects and sends PageUsed metrics, reported in megabytes. |
|
|
Reports available space in page file for all disks. |
|
|
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. |
|
|
Provides the location of the file containing AWS credentials.
This parameter cannot be used with the |
|
|
Specifies the AWS access key ID to use to identify the caller. Must be
used together with the |
|
|
Specifies the AWS secret access key to use to sign the request to
Amazon CloudWatch. Must be used together with the |
|
|
Performs a test run of the script that collects the metrics but does not actually call Amazon CloudWatch to report the data. This option also checks that credentials are provided. |
|
|
Use this option when calling the script from task scheduler. When this option is used, all diagnostic output is suppressed, but error messages are sent to the log file. |
|
|
Displays detailed information about what the script is doing. |
|
|
Displays usage information. |
|
|
Displays the version number of the script. |
|
|
Logfile is used to log error message. Use this along with –from_scheduler option. If no value is specified for logfile then a default file is created with the same as the script with .log extension. |
Examples
The following examples assume that you have already updated the awscreds.conf file with valid AWS credentials.
If you are not using the awscreds.conf file, provide credentials
using the -aws_access_id and -aws_secret_key
arguments.
To collect all available memory metrics using an inline access ID and secret key and send the data to Amazon CloudWatch
Run the following command:
.\mon-put-metrics-mem.ps1 -aws_access_id ThisIsMyAccessKey -aws_secret_key ThisIsMySecretKey -mem_util -mem_avail -page_avail -page_used -page_util -memory_units Megabytes
mon-put-metrics-disk.ps1
This script collects 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 |
|---|---|
|
|
Collects and sends the DiskSpaceUtilization metric for the selected disks. The metric is reported in percentages. |
|
|
Collects and sends DiskSpaceUsed metric for the selected disks. The metric is reported by default in gigabytes. |
|
|
Collects and sends the DiskSpaceAvailable metric for the selected disks. The metric is reported in gigabytes. |
|
|
Specifies units in which to report memory usage. If not specified, memory is reported in gigabytes. UNITS may be one of the following: bytes, kilobytes, megabytes, gigabytes. |
|
|
Selects the drive letter on which to report. To report metric on c and d drive use the following option |
|
|
Provides the location of the file containing AWS credentials. This parameter cannot be used with the |
|
|
Specifies the AWS access key ID to use to identify the caller. Must be used together with the |
|
|
Specifies the AWS secret access key to use to sign the request to
Amazon CloudWatch. Must be used together with the |
|
|
Performs a test run of the script that collects the metrics but does not actually call Amazon CloudWatch to report the data. This option also checks that credentials are provided. |
|
|
Use this option when calling the script from task scheduler. When this option is used, all diagnostic output is suppressed, but error messages are sent to the log file. |
|
|
Displays detailed information about what the script is doing. |
|
|
Displays usage information. |
|
|
Displays the version number of the script. |
|
|
Logfile is used to log error message. Use this along with |
Examples
To collect all available disk metrics using an inline access ID and secret key and send the data to Amazon CloudWatch
Run the following command:
.\mon-put-metrics-disk.ps1 -aws_access_id ThisIsMyAccessKey -aws_secret_key ThisIsMySecretKey -disk_space_util -disk_space_avail -disk_space_units Gigabytes
mon-put-metrics-perfmon.ps1
This script collects PerfMon counters on the current system. It then makes a remote call to Amazon CloudWatch to report the collected data as custom metrics.
Options
| Name | Description |
|---|---|
|
|
Reports current processor queue counter. |
|
|
Reports memory pages/input memory counter. |
|
|
Provides the location of the file containing AWS credentials. This parameter cannot be used with the |
|
|
Specifies the AWS access key ID to use to identify the caller. Must be used together with the |
|
|
Specifies the AWS secret access key to use to sign the request to
Amazon CloudWatch. Must be used together with the |
|
|
Performs a test run of the script that collects the metrics but does not actually call Amazon CloudWatch to report the data. This option also checks that credentials are provided. |
|
|
Use this option when calling the script from task scheduler. When this option is used, all diagnostic output is suppressed, but error messages are sent to the log file. |
|
|
Displays detailed information about what the script is doing. |
|
|
Displays usage information. |
|
|
Displays the version number of the script. |
|
|
Logfile is used to log error message. Use this along with |
Examples
To collect preset PerfMon counters in script using an inline access ID and secret key and send the data to Amazon CloudWatch
Run the following command:
.\mon-put-metrics-perfmon.ps1 -aws_access_id ThisIsMyAccessKey -aws_secret_key ThisIsMySecretKey -pages_input -processor_queue
To collect preset PerfMon counters in script using a credential file and send the data to Amazon CloudWatch
Run the following command:
.\mon-put-metrics-perfmon.ps1 -aws_credential_file C:\awscreds.conf -pages_input -processor_queue
To collect preset PerfMon counters in script using credentials stored in an environment variable and send the data to Amazon CloudWatch
Run the following command:
.\mon-put-metrics-perfmon.ps1 -pages_input -processor_queue
To add more counters to be pushed to Amazon CloudWatch
Open the script in a text editor such as Notepad, and then on line 72, locate the following commented section:
### Add More counters here. #$Counters.Add('\Memory\Cache Bytes','Bytes') #$Counters.Add('\\localhost\physicaldisk(0 c:)\% disk time','Percent')Note
The first parameter (e.g., $Counters.Add) is the PerfMon counter. The second parameter (e.g., ('\Memory\Cache Bytes','Bytes')) is the unit of data that counter provides.
Edit the script and add your own PerfMon counters to the script as shown above. After you have added custom PerfMon counters to the script, you can run the script without any parameters other than credential information.
Note
You can only add PerfMon counters to the script on your computer. You can use the
Get-Countercommand to test PerfMon counters. For more information, see Get-Counter on the Microsoft TechNet website.
mon-get-instance-stats.ps1
This script queries Amazon CloudWatch for statistics on memory, page file, 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 executed.
Options
| Name | Description |
|---|---|
|
|
Specifies the number of recent hours to report on, as represented by N where N is an integer. |
|
|
Provides the location of the file containing AWS credentials. This parameter cannot be used with the |
|
|
Specifies the AWS access key ID to use to identify the caller. Must be used together with the |
|
|
Specifies the AWS secret access key to use to sign the request to
Amazon CloudWatch. Must be used together with the |
|
|
Displays detailed information about what the script is doing. |
|
|
Displays usage information. |
|
|
Displays the version number of the script. |
Examples
To get utilization statistics for the last 12 hours using an inline access ID and secret key and send the data to Amazon CloudWatch
Run the following command:
.\ mon-get-instance-stats.ps1 -aws_access_id ThisIsMyAccessKey -aws_secret_key ThisIsMySecretKey -recent_hours 12
To get utilization statistics for the last 12 hours using a credential file and send the data to Amazon CloudWatch
Run the following command:
.\mon-get-instance-stats.ps1 -aws_credential_file C:\awscreds.conf -recent_hours 12
To get utilization statistics for the last 12 hours using credentials stored in an environment variable and send the data to Amazon CloudWatch
Run the following command:
.\mon-get-instance-stats.ps1 -recent_hours 12
The returned response will be similar to the following example output:
Assembly Loaded Instance Metrics for last 12 hours. CPU Utilization Average: 4.69 % Maximum: 10.47 % Minimum: 1.16 % Memory Utilization Average: 14.45 % Maximum: 14.77 % Minimum: 14.38 % pagefileUtilization(c:\pagefile.sys) Average: 0.00 % Maximum: 0.00 % Minimum: 0.00 % Volume Utilization C: Average: 17.28 % Maximum: 17.28 % Minimum: 17.28 % Volume Utilization D: Average: 1.41 % Maximum: 1.41 % Minimum: 1.41 % pagefileUtilization(f:\pagefile.sys) Average: 0.00 % Maximum: 0.00 % Minimum: 0.00 % pagefileUtilization(f:\pagefile.sys) Average: 0 Maximum: 0 Minimum: 0 pagefileUtilization(f:\pagefile.sys) Average: 0 Maximum: 0 Minimum: 0
Set Up Task Scheduler to Send Metrics Reports to Amazon CloudWatch
You can use Windows Task Scheduler to send metrics reports periodically to Amazon CloudWatch.
To set up task scheduler to send metrics reports to Amazon CloudWatch
On your Windows Server instance, click Start, click Administrative Tools, and then click Task Scheduler.
On the Action menu, click Create Task.
In the Create Task dialog box, on the General tab, in the Name box, type a name for the task, and then select Run whether user is logged on or not.
On the Triggers tab, click New.
In the New Trigger dialog box, under Settings, select One time.
Under Advanced settings, select Repeat task every and select 5 minutes from the drop-down menu.
In the for a duration of drop-down menu, select Indefinitely, and then click OK.
Note
These settings create a trigger that will launch the script every 5 minutes indefinitely. To modify this task to run for set number of days using the Expire check box.
On the Actions tab, click New.
In the Action drop-down menu, select Start a program.
Under Settings, in the Program/script box, type Powershell.exe.
In the Add arguments (optional) box, type
-command "C:\scripts\mon-put-metrics-disk.ps1 -disk_drive C:,d -disk_space_util -disk_space_units gigabytes -from_scheduler -logfile C:\mylogfile.log", and then click OK.On the Create Task dialog box, click OK.
If you selected a user account to run this task, Task Scheduler will prompt you for user credentials. Enter the user name and password for the account that will run the task, and then click OK.
Note
If the PerfMon counters you are using don't require administrator privileges, you can run this task using a system account instead of an administrator account. In the Create Task dialog box, on the General tab, click Change User or Group, and then select a system account.
