Amazon CloudWatch Agent

Installation

The Amazon CloudWatch Agent enables you to collect memory utilization metrics from Amazon EC2 instances across operating systems. Follow the instructions to install the CloudWatch Agent.

For Linux instances, Compute Software looks for the mem_used_percent metric in the CWAgent namespace. On Windows instances, Compute Software looks for the Memory % Committed Bytes In Use metric in the CWAgent namespace. The metric reported must have exactly one dimension with the InstanceId dimension name. The dimension combinations are important because CloudWatch treats each unique combination of dimensions as a separate metric, even if the metrics have the same metric name (see Dimension combinations). The memory metric location is entirely customizable via Properties.

Example Configuration

The below CloudWatch Agent configuration is the smallest configuration necessary to report Linux memory utilization to CloudWatch.

{
  "metrics": {
    "metrics_collected": {
      "mem": {
        "measurement": [
          "used_percent"
        ],
        "resources": [
          "*"
        ]
      }
    },
   "append_dimensions": {
     "InstanceId": "${aws:InstanceId}"
   }
  }
}

If you are already using the CloudWatch agent to report metrics, you may have additional keys in the append_dimensions field. To continue reporting your existing metrics and add a new metric with just the InstanceId dimension, you must utilize the aggregation_dimensions field. For example, the below configuration would report memory utilization with the dimension name sets ["InstanceId", "AutoScalingGroupName"] and ["InstanceId"].

{
  "metrics": {
    "metrics_collected": {
      "mem": {
        "measurement": [
          "used_percent"
        ],
        "resources": [
          "*"
        ]
      }
    },
   "append_dimensions": {
     "InstanceId": "${aws:InstanceId}",
     "AutoScalingGroupName": "${aws:AutoScalingGroupName}"
   },
   "aggregation_dimensions": [
      [
        "InstanceId"
      ]
    ]
  }
}

Verify Memory Utilization

After you have installed and configured the CloudWatch agent, you should verify that the memory utilization metric is reporting data in the expected format. To do so, we will query the CloudWatch GetMetricData API using the AWS CLI.

1. Create a file name metric-data-queries.json and set its content to the following, replacing <InstanceId> with your instance's ID.

[
    {
        "Id": "mem_used_percent",
        "MetricStat": {
            "Metric": {
                "Namespace": "CWAgent",
                "MetricName": "mem_used_percent",
                "Dimensions": [
                    {
                        "Name": "InstanceId",
                        "Value": "<InstanceId>"
                    }
                ]
            },
            "Period": 60,
            "Stat": "Maximum"
        },
        "ReturnData": true
    }
]

2. Run the get-metric-data command with the --start-time and --end-time flags set to a time period during which you expect metric data to have been reported.

aws cloudwatch get-metric-data --metric-data-queries file://./metric-data-queries.json --start-time 2021-01-01T00:00:00Z --end-time 2021-01-01T01:00:00Z

3. If successful, you should expect to see output that looks like the below JSON.

{
    "MetricDataResults": [
        {
            "Id": "mem_used_percent",
            "Label": "mem_used_percent",
            "Timestamps": [
                "2021-01-01T00:00:00+00:00",
                "2021-01-01T00:05:00+00:00",
                "2021-01-01T00:10:00+00:00",
                "2021-01-01T00:15:00+00:00",
                "2021-01-01T00:20:00+00:00",
                "2021-01-01T00:25:00+00:00",
                "2021-01-01T00:30:00+00:00",
                "2021-01-01T00:35:00+00:00",
                "2021-01-01T00:40:00+00:00",
                "2021-01-01T00:45:00+00:00",
                "2021-01-01T00:50:00+00:00",
                "2021-01-01T00:55:00+00:00"
            ],
            "Values": [
                58.34467925347139,
                62.02883126613197,
                70.3957777104287,
                0.9119415164393407,
                55.887334700738315,
                80.22495918625438,
                74.73951873550325,
                73.34780183105414,
                34.47844972169113,
                7.361982552019574,
                52.82619051827625,
                47.18128322139935
            ],
            "StatusCode": "Complete"
        }
    ],
    "Messages": []
}