Monitor Memory Metrics for EC2 Windows Instances

While Amazon CloudWatch provides CPU, network and disk usage metrics for Amazon EC2 instances, it doesn't provide memory usage metrics by default. Commander provides the ability to monitor memory usage through the use of custom CloudWatch scripts. When memory usage metrics are enabled for an instance:

VM owners can monitor memory usage
Commander can issue memory rightsizing recommendations for the VM
Commander also detects and uses memory metrics for EC2 instances deployed in the AWS console.

This topic explains how to enable memory usage monitoring for new Amazon EC2 Windows instances deployed by Commander. See also Monitor Memory Metrics for EC2 Linux Instances.

Supported Windows versions

Commander supports memory metrics for the following Windows versions:

Windows 2016 Base
Windows 2012 R2
Windows 2012 Base
Windows 2008 Base
Windows 2003 R2

Windows 2016 Nano isn't supported, because it has no CloudWatch plug-in.

Prerequisites

PowerShell v1.0 or higher: Commander runs a PowerShell script to monitor memory metrics, so PowerShell v1.0 or higher must be installed on the deployed Windows instance. You can download PowerShell from the Microsoft Download Center.
SSM Agent: The Commander script requires any version of SSM Agent to be installed on the EC2 instance. SSM Agent is installed by default on Windows Server 2016 instances and instances created from Windows Server 2003-2012 R2 AMIs published in November 2016 or higher. If you created your own AMI and it doesn't include SSM Agent, see Working with SSM Agent on EC2 instances for Windows Server.
User data: User data execution must be enabled for the source AMI. In other words, the EC2UserDataPlugin field must be set to True in the <amazon_install_dir>/EC2Config/Settings/Config.xml file. If the source AMI was not configured to allow user data execution, you must enable it on the deployed VM. See Troubleshooting below.

Enable memory usage monitoring for new VMs: Overview

When you enable memory usage monitoring for a new VM, during provisioning, Commander installs and runs a PowerShell script as AWS user data. The script is merged with any other user data configured for the new VM.

The PowerShell script which is run by Commander as user data during provisioning is stored in the following location on the Commander server:

<Commander_install_dir>\tomcat\common\classes\aws-windows-memory-metrics.ps1

The PowerShell script creates a new Simple Service Manager (SSM) Document called auto-enable-cloudwatch-Commander and associates it with the new instance. The SSM Document defines what information is sent to CloudWatch. The VM sends memory usage statistics to AWS every 15 minutes.

SSM Documents are region-specific. The PowerShell script automatically determines the region for the source AMI and replaces a string in the script with the proper region.

The two AWS memory metrics and their Commander equivalents are:

AWS memory metric	Commander equivalent	Description
MemoryUsed	Memory Consumed (MB)	Reports only memory allocated by applications and the operating system, and excludes memory in cache and buffers.
MemoryUtilization	Memory Used (%)	Reports only memory allocated by applications and the operating system, and excludes memory in cache and buffers.

For more information, see Monitoring Amazon EC2.

To enable memory usage monitoring for new VMs, the following conditions must be met:

Memory usage monitoring must be enabled. See Enable memory usage monitoring below.
The deployed VM must have credentials that allow reading and writing CloudWatch data. See Assign credentials with CloudWatch permissions below.

Enable memory usage monitoring

To configure memory usage monitoring, enable the Monitor Memory Usage option for the service catalog entry. You can find this option on the Infrastructure tab of the Component Blueprint page, as shown below.

For more information, see Monitor Memory Usage(VM templates only).

You can also enable memory usage monitoring during manual deployment.
If you're using your own custom script to enable memory usage monitoring, you must disable memory usage monitoring in the service catalog blueprint.

Assign credentials with CloudWatch permissions

The deployed VM must have credentials that allow reading and writing CloudWatch data.

Assigning an IAM role is the recommended method, to avoid the need for placing plain-text credentials in a script.

There are two ways to assign an IAM role during the Commander provisioning process:

Assign the IAM role to the service catalog blueprint (see the image in the section above). See Add AWS Services to the Catalog for more information.
Assign the IAM role to the deployment destination. This option makes sense if you deploy the same template (AMI) to multiple deployment destinations, or if you have a large number of catalog entries. You can find the IAM Role option on the Resources & Security page of the Automated Deployment Placement wizard, as shown below.

Important: Commander doesn't validate IAM role names, so ensure that role names entered in Commander match those in AWS. IAM role names are not case-sensitive.

For more information, see Configure Automated Deployment for Approved Service Requests.

If an IAM role is configured in both the deployment destination and the blueprint, the blueprint takes precedence.

Provisioning won't fail if you don't assign an IAM role through one of these methods, because it's possible to assign credentials through a script.

Troubleshooting

If user data execution was not allowed on the source AMI, the PowerShell monitoring script won't run during deployment, and memory metrics monitoring won't occur. You can enable user data execution after deployment, for example, by using Windows Sysprep to enable user data execution; see the Amazon EC2 documentation for more details.

Verify script execution

To verify script execution and view script output, you can view the output log in the following location on the deployed VM:

<amazon_install_dir>\Ec2ConfigService\Logs