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

This topic explains how to enable memory usage monitoring for new Amazon EC2 Windows instances deployed by Commander. See also Monitoring 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 is not 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 site.
  • 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 Installing SSM Agent in the AWS documentation.
  • 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.

Enabling 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.

See Monitoring Amazon EC2 in the AWS documentation for more information.

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

Enable memory usage monitoring

To configure memory usage monitoring, on the Infrastructure tab of the Component Blueprint page, enable the option Monitor Memory Usage for the service catalog entry. See Monitor Memory Usage(VM templates only) for more information.

Note:

  • 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.
memory usage monitoring for CloudWatch

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 above). See Adding 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:

Deployment Destination IAM

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.

See Optionally, enter the name of an IAM Role to assign to the deployed VM. The maximum number of characters is 255. Configuring the IAM role in the deployment destination rather than in the catalog blueprint makes sense if you deploy the same template (AMI) to multiple deployment destinations, or if you have a large number of catalog entries. If an IAM role is also configured in the catalog blueprint, the blueprint takes precedence. Administrators can override the IAM role during manual deployment. To learn more, see Managing Amazon Web Services with Commander. 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.

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.

Verifying 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