How do I push custom metrics to CloudWatch?

Short description

By default, AWS services automatically publish data points to CloudWatch. However, if you want to monitor the performance of your resources that aren't natively supported by AWS services, then you can use one of the following methods to publish custom metrics to CloudWatch:

• Use the CloudWatch agent
• Use the CloudWatch API
• Embed metrics within your CloudWatch Logs

Important: Custom metrics are charged based on their storage and API use.

Resolution

Use the CloudWatch agent to push custom metrics

The CloudWatch agent collects system-level metrics and sends them to CloudWatch as custom metrics. You can use the agent on Linux or Windows servers and Amazon Elastic Compute Cloud (Amazon EC2) instances or on-premises servers.

Configure metrics in the agent configuration file

To define the metrics you want to collect, add a metric block to the agent configuration file. The agent then pushes those metrics to CloudWatch.

For Linux, see the list of supported metrics. The following example shows how to configure disk metrics:

"disk": 
    {
        "measurement": [
          
          "used_percent"
        ],
        "resources": [
          
          "*"
        ],
        "drop_device": 
        true
      }

For Windows, you can reference any counter available in the Windows Performance Monitor within the agent configuration file. The following example shows you how to configure Processor counters:

"Processor": {
        "measurement": [
          {"name": "% Idle Time", "rename": "CPU_IDLE", "unit": "Percent"},
          "% Interrupt Time",
          "% User Time",
          "% Processor Time"
        ],
        "resources": [
          "*"
        ],
        "append_dimensions": {
          "d1": "win_foo",
          "d2": "win_bar"
        }
      }

Use StatsD or collectD to push custom application metrics

To retrieve custom metrics from your applications or services, use the StatsD and collectd protocols. The agent collects these metrics and forwards them to CloudWatch. StatsD is supported on both Linux and Windows servers. collectd is supported only on Linux servers.

To use these protocols, complete the following steps:

1. Install the CloudWatch agent.
2. Assign a role to the EC2 instance with CloudWatch permissions.
3. Create the CloudWatch agent configuration file.
4. Start the agent.

Use PutMetricData API to push single or multiple custom metrics

If your use case doesn't support the CloudWatch agent, then use the PutMetricData API to push custom metrics to CloudWatch.

Push a single custom metric

To push a single custom metric, retrieve the value locally and pass it to the API. For example, run the following command to push the number of connections on a specific port:

total_conn=$(netstat -an | grep PORT | wc -l) 
aws cloudwatch put-metric-data   --namespace "totalconn"   --metric-name <port> --dimensions Instance=INSTANCE-ID --value $  total_conn

Note: Replace PORT and INSTANCE-ID with your values.

Push multiple custom metrics

To push multiple metrics in a single API call, run the following put-metric-data command and pass a JSON file with the --metric-data-parameter:

aws cloudwatch put-metric-data --namespace "Usage Metrics" --metric-data file://metric.json

In this example, metric.json contains the following metrics:

[
  {
    "MetricName": "DiskMetric",
    "Value": <value_derived_by_some_calculation>,
    "Unit": "Count"
  },
  {
    "MetricName": "MemoryMetric",
    
    "Value": <value_derived_by_some_calculation>,
    "Unit": "Count"
  }
]

To reduce costs and avoid throttling on the PutMetricData API, push multiple metrics in a single API call. CloudWatch charges custom metrics based on the number of API calls and storage. The PutMetricData API has the following quotas per request:

• You can include up to 1,000 different metrics in a single API call.
• If you use the Values and Counts method, then you can publish up to 150 values per metric per request.
• You can use up to 30 dimensions per metric.
• Each PutMetricData request is limited to 1 MB for HTTP POST requests.

Use CloudWatch Logs to generate custom metrics

To generate custom metrics based on your log data, use one of the following methods:

Embed metrics in CloudWatch Logs

You can embed metric data into your log data. CloudWatch automatically pulls the embedded data to asynchronously generate custom metrics. You can also use this method to generate metric data from resources, such as AWS Lambda or Amazon Elastic Container Service (Amazon ECS). You don't require additional configuration to embed metric data.

The logs are in a JSON format and must have the root node _aws that contains CloudWatchMetrics.

Example log in JSON format:

{
  "_aws": {
    "Timestamp": 1725618677000,
    "CloudWatchMetrics": [
      {
        "Namespace": "custom-metric",
        "Dimensions": [["dimensionValue"]],
        "Metrics": [
          {
            "Name": "time",
            "Unit": "Milliseconds",
            "StorageResolution": 60
          }
        ]
      }
    ]
  },
  "dimensionValue": "value",
  "time": 100
}

For more information, see Embedding metrics within logs.

Use filters to create custom metrics from log events

To generate custom metrics based on the data present in your log events, use filters to create metrics from log events.