In this recipe, we use the built-in put-metric-data AWS CLI command to send our metric to CloudWatch.

We start by defining the metric name and namespace that the values will appear under. This is important because it defines how we will see the metric in the console and dashboards. Names should identify and describe the metric. They do not need to be unique, as the dimension(s) we add will take care of that (we will discuss this later). Namespaces are used to group similar metrics together, like a category. The built-in metrics appear under the namespace AWS/. For example, EC2 metrics appear under the AWS/EC2 namespace.

We then specify a dimension for the metric. A dimension is a way to uniquely identify similar metrics. In this case we are using the instance's ID to identify the metric, because the metric is unique to that instance, but we will likely have many instances of the MemoryUsagePercent metric (across many EC2 instances). We are obtaining the instance ID by querying (via the curl command) the instance metadata service, which is accessed over HTTP on the special IP address 169.254.169.254.

Next we specify a percent, because we know what kind of data we are dealing with. This argument can be leftoff if you don't know (or care), as CloudWatch attaches no significance to it (although some other applications may be able to use it, for example, for display).

Finally we specify the value to send. We work this value out dynamically from the output of the free command and use awk to convert it to a percentage of memory inuse.

Once the metric is being sent to CloudWatch, we can view it in the console. The easiest way is to select your specific metric and view it in the Metrics section of the CloudWatch console.