• October 22, 2026
• 10 min read

Amazon CloudWatch — Metrics: Core Concepts¶

Anatomy of a Metric¶

A metric is a time-ordered set of datapoints. It is uniquely defined by a namespace, a metric name and zero or more dimensions. Each datapoint adds a timestamp, a value (or a set of values) and an optional unit.

Metrics exist only in the Region where they were created, cannot be deleted, and expire on their own: a metric with no new datapoints for 15 months disappears, and datapoints older than 15 months are dropped on a rolling basis.

Dimensions and Dimension Combinations¶

flowchart TB
  NS["namespace<br/>QA/Orders"] --> NAME["metric name<br/>Latency"]
  NAME --> A["Service=api"]
  NAME --> B["Service=api, Env=test"]
  NAME --> C["Service=worker"]
  A --> DP1["datapoints: timestamp, value, unit"]
  B --> DP2["datapoints: timestamp, value, unit"]
  C --> DP3["datapoints: timestamp, value, unit"]

Each unique combination of dimensions is a separate metric, even with the same name. You can only read statistics for combinations you published.

• CloudWatch does not aggregate across dimensions for custom metrics. If you need a total, publish it as its own metric (no dimensions, or only Service), or sum several series with metric math.
• AWS services behave differently: for some (AWS/EC2) CloudWatch can aggregate across dimensions when you query without any.
• The metric math SEARCH function can fan out over many metrics in one expression.
• High cardinality is the main cost and quota trap. A request ID, user ID, order ID, pod name or timestamp as a dimension creates a new custom metric per value. Keep dimension values to a small, closed set (service, route template, status class, environment). Put identifiers in log fields instead.
• Several processes can publish to the same namespace, name and dimensions: CloudWatch treats them as one metric and aggregates their datapoints.

Units, Statistics and Percentiles¶

Datapoints with a unit are aggregated separately per unit. A query without Unit returns all of them, each with its unit; a query with a unit that matches nothing returns null results. CloudWatch never converts units.

Alarms also accept tm90, tc90, ts90, wm90, IQM and PR(n:m) as extended statistics.

Percentiles need raw datapoints:

• A custom metric supports percentiles when you publish raw values (single Value or Values/Counts).
• A statistic set supports them only if SampleCount is 1 and Min, Max, Sum are equal, or Min equals Max and Sum = Min × SampleCount.
• Percentiles are not available if any value of the metric is negative.
• Not every AWS metric supports them; the concepts page lists API Gateway, Application Load Balancer, EC2, ELB, Kinesis, Lambda and RDS, and the Bedrock guide uses p50 on AWS/Bedrock metrics.

Periods, Resolution, Retention and Rollup¶

A period is the length of time one statistic covers. For high-resolution metrics a period can be 1, 5, 10, 20, 30 seconds or any multiple of 60; for standard-resolution metrics it must be a multiple of 60. Aggregated datapoints are stamped with the start of their period: data from 19:00 to 20:00 is stamped 19:00. A value for the current period can still change while samples keep arriving.

Data is rolled up as it ages: after 15 days one-minute data is only retrievable with a 5-minute period, after 63 days with a 1-hour period. StartTime is rounded down accordingly (to the minute for data newer than 15 days, to a 5-minute clock interval between 15 and 63 days, to the hour beyond 63 days), and a GetMetricStatistics request with a start time older than 3 hours must use a period that is a multiple of 60, 300 or 3600 respectively or it returns no datapoints.

Delays and Missing Data¶

AWS services publish only while a resource is active, so "no data" is a normal state:

Choose an alarm period at least as long as the metric resolution (300 s for basic EC2 monitoring). If your own metric is intermittent, publish 0 for quiet periods so alarms and averages see them (03).

Vended Metrics for the Services in This Section¶

Notes that bite in tests and alarms:

• SQS and the "visible" metrics are approximate because of the distributed design. For a DLQ use ApproximateNumberOfMessagesVisible; NumberOfMessagesSent does not count messages moved there by redrive. ApproximateNumberOfMessagesNotVisible can briefly report non-zero on an empty queue, so alarm on several consecutive datapoints.
• SNS NumberOfNotificationsFailed counts differently per endpoint type: once per message for SQS, email, SMS and mobile push when delivery stops, and for every failed attempt (retries included) for HTTP/S.
• EC2 alarms with stop, terminate, reboot or recover actions should treat missing data as missing and fire only from ALARM.
• Bedrock publishes each metric both with and without ModelId; if a request fails before the model is known, only the series without the dimension counts it, so a per-model error alarm can undercount. Throttled requests are excluded from Invocations and from both error counts; how many throttles you see depends on SDK retry settings. Requests billed at a long-context rate also appear under ModelId + ContextWindow, as a subset of the ModelId series.
• ECS Container Insights needs setup per cluster, bills as custom metrics, and from 1 October 2026 does not bill RunningTaskCount.

Quotas That Matter to Test Code¶

All quotas are per account and Region; the Service Quotas console (--service-code monitoring) shows the current values. A parallel test suite that creates alarms shares the 3-per-second limit with everyone else in the account.

What You Pay For¶

Free tier highlights per month: 10 custom metrics, 10 standard-resolution alarm metrics, 3 dashboards and 1 million metric API requests (GetMetricData and similar read calls are always charged). Check the pricing page before budgeting; it changes.

Quick Rules¶

1. Dimensions: few, closed, low-cardinality. Identifiers belong in logs.
2. Publish raw values (Values/Counts) when you will ask for percentiles. A statistic set cannot answer them.
3. Always set Unit, and query with the same unit you published.
4. Use Maximum for depths and ages, Sum for counters, Average only for rates and utilisation.
5. Never read the current period as final. Query completed periods, or accept that the value moves.
6. Choose an alarm period at least as long as the metric resolution, and remember that standard EC2 metrics are 5 minutes.
7. Idle means no data. Decide TreatMissingData per metric; publish zeros for your own intermittent metrics.
8. Remember retention. One-minute data lives 15 days; a regression dashboard that looks back 30 days sees 5-minute data.
9. Do not delete-and-recreate metrics in tests. You cannot delete them; use a unique namespace or dimension value per run for isolation, and keep the number of those small.
10. Respect the quotas in CI: 3 alarm writes per second, 500 GetMetricData requests per second.

See also¶

• Amazon CloudWatch — Overview
• Amazon CloudWatch — boto3 in Python
• Amazon CloudWatch — Alarms & Dashboards
• Amazon SQS — Queues, Consumers & Testing
• Amazon SNS — Topics, Subscriptions & Fan-out
• Amazon EC2
• Amazon ECS — Containers on Fargate, Services & Testing
• Amazon Bedrock
• AWS Foundations — boto3, Credentials & Local Testing