How to Create Custom Metric in AWS CloudWatch

To create a custom metric in AWS CloudWatch, you send your metric data using the PutMetricData API call. This lets you define your own metric name, namespace, and values that CloudWatch will store and display.

Syntax

The PutMetricData API call requires specifying a Namespace, a list of MetricData objects, each with a MetricName, Value, and optional Dimensions. The namespace groups your metrics, and dimensions add extra labels.

bash

aws cloudwatch put-metric-data --namespace "YourNamespace" --metric-data MetricName=YourMetricName,Value=123,Dimensions=[{Name=DimensionName,Value=DimensionValue}]

Example

This example shows how to send a custom metric named PageLoadTime with a value of 1.23 seconds under the namespace MyApp/Metrics using AWS CLI.

bash

aws cloudwatch put-metric-data --namespace "MyApp/Metrics" --metric-data MetricName=PageLoadTime,Value=1.23,Dimensions=[{Name=Page,Value=HomePage}]

Common Pitfalls

• Not using a unique Namespace can mix your metrics with others, making them hard to find.
• Forgetting to specify Dimensions limits filtering and grouping options.
• Sending data with incorrect Value types (must be numeric) causes errors.
• Not having correct AWS permissions for PutMetricData will block metric creation.

bash

aws cloudwatch put-metric-data --namespace "MyApp" --metric-data MetricName=Errors,Value=high
# Wrong: value must be numeric

aws cloudwatch put-metric-data --namespace "MyApp" --metric-data MetricName=Errors,Value=5
# Correct: numeric value

Quick Reference

Parameter	Description
Namespace	A container for your metrics, e.g., 'MyApp/Metrics'
MetricName	Name of your custom metric, e.g., 'PageLoadTime'
Value	Numeric value representing the metric data point
Dimensions	Optional key-value pairs to label metrics, e.g., 'Page=HomePage'
Timestamp	Optional time of the metric data point; defaults to current time

Key Takeaways

Use the PutMetricData API to send custom metrics to CloudWatch.

Always specify a unique Namespace to organize your metrics.

Include Dimensions to enable filtering and grouping of metrics.

Ensure metric values are numeric and permissions allow metric publishing.

Use AWS CLI or SDKs to automate custom metric creation.