# aws cloudwatch put-metric-data

AWS CLI commands · Updated 16 November 2026

**Short answer:** aws cloudwatch put-metric-data --namespace MyApp --metric-name QueueLag --value 42 --unit Seconds --dimensions Environment=prod publishes one datapoint to a custom metric. The metric appears within a few minutes and can then be graphed and alarmed on like any AWS metric; every unique name and dimension combination is billed as a separate custom metric.

## What the command does

Custom metrics let you alarm on anything you can measure: backlog size from a cron job, the age of the latest backup, disk usage reported by a script, business events. The CLI offers two styles: single-datapoint options (`--metric-name`, `--value`, `--unit`, `--dimensions`, `--timestamp`) and `--metric-data`, which takes a JSON list for batches.

## Syntax

```
aws cloudwatch put-metric-data --namespace MyApp \
  --metric-name BackupAgeHours --value 3.5 --unit None \
  [--dimensions Database=orders,Environment=prod] \
  [--timestamp 2026-11-16T09:00:00Z] \
  [--storage-resolution 1]

aws cloudwatch put-metric-data --namespace MyApp --metric-data file://metrics.json
```

In the single-datapoint form, `--dimensions` uses `Name=Value` pairs separated by commas.

## Worked examples

**Report a queue backlog from a cron job** every minute:

```
LAG=$(psql -tAc "select extract(epoch from now() - min(created_at)) from jobs where done = false")
aws cloudwatch put-metric-data --namespace MyApp --metric-name JobBacklogSeconds \
  --value "${LAG:-0}" --unit Seconds --dimensions Environment=prod
```

**A heartbeat** for a job that should run nightly, paired with an alarm that treats missing data as breaching:

```
aws cloudwatch put-metric-data --namespace MyApp --metric-name NightlyExportSucceeded \
  --value 1 --unit Count
```

**Several metrics in one call**, with `metrics.json`:

```
[
  { "MetricName": "OrdersPlaced", "Value": 118, "Unit": "Count",
    "Dimensions": [{ "Name": "Environment", "Value": "prod" }] },
  { "MetricName": "CheckoutLatency", "Unit": "Milliseconds",
    "Values": [120, 135, 410], "Counts": [50, 30, 2],
    "Dimensions": [{ "Name": "Environment", "Value": "prod" }] }
]
```

**Pre-aggregated statistics** instead of raw values:

```
aws cloudwatch put-metric-data --namespace MyApp --metric-name RequestLatency --unit Milliseconds \
  --statistic-values Sum=15230,Minimum=12,Maximum=980,SampleCount=200
```

**Confirm it arrived** (it can take up to 15 minutes to be listed):

```
aws cloudwatch list-metrics --namespace MyApp --metric-name JobBacklogSeconds
```

## Options that matter

| Option | Notes |
|---|---|
| `--namespace` | Your own name, such as `MyApp`. Names starting with `AWS/` are reserved. |
| `--unit` | Keep it consistent; datapoints with different units are treated as different series in statistics. |
| `--storage-resolution 1` | High-resolution (per-second) storage, needed for 10 or 30-second alarm periods. Costs more. |
| `--timestamp` | Defaults to now. Points far in the past or future are rejected. |
| `--dimensions` | Each distinct combination creates a new billed metric. |

## Gotchas

- **Cardinality costs money.** Putting user IDs, request IDs or other unbounded values into dimensions creates thousands of custom metrics. For high-cardinality data, use the embedded metric format in logs or Logs Insights.
- **One call per datapoint does not scale.** Batch with `--metric-data`, or publish from code with the SDK, rather than looping the CLI thousands of times.
- **Values are numbers only**; very large or very small values outside CloudWatch's accepted range are rejected.
- **Permissions.** The caller needs `cloudwatch:PutMetricData`; you can restrict it to a namespace with the `cloudwatch:namespace` condition key.

## Questions

### How do I create a custom CloudWatch metric?

There is no separate create step. The first put-metric-data call for a new namespace, name and dimensions creates the metric.

### How long until a custom metric appears in CloudWatch?

Datapoints can be read with get-metric-statistics soon after publishing, but a brand-new metric can take up to 15 minutes to show up in list-metrics.

### How do I alarm on a custom metric?

Use put-metric-alarm with your namespace, metric name and exactly the same dimensions you publish with.

## When this happens away from your desk

Custom metrics are often what turns a silent failure into an alert on your phone. CloudConsole, a phone app for AWS, is built to show alarms on custom and AWS metrics alike.

[About the CloudConsole app](https://cloudconsole.dev/aws-console-app) · [Download on the App Store](https://apps.apple.com/app/cloudconsole-for-aws/id6835419710)

## Sources

- [AWS CLI Command Reference: cloudwatch put-metric-data](https://docs.aws.amazon.com/cli/latest/reference/cloudwatch/put-metric-data.html)
- [PutMetricData API reference](https://docs.aws.amazon.com/AmazonCloudWatch/latest/APIReference/API_PutMetricData.html)
- [Amazon CloudWatch User Guide](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/WhatIsCloudWatch.html)

## Related

- [aws cloudwatch put-metric-alarm](https://cloudconsole.dev/cli/cloudwatch-put-metric-alarm)
- [aws cloudwatch list-metrics](https://cloudconsole.dev/cli/cloudwatch-list-metrics)
- [aws cloudwatch get-metric-statistics](https://cloudconsole.dev/cli/cloudwatch-get-metric-statistics)
- [aws logs put-metric-filter](https://cloudconsole.dev/cli/logs-put-metric-filter)
- [How to create a CloudWatch alarm for CPU utilization](https://cloudconsole.dev/how-to/create-cloudwatch-cpu-alarm)
- [aws cloudwatch describe-alarm-history](https://cloudconsole.dev/cli/cloudwatch-describe-alarm-history)

---

Source: https://cloudconsole.dev/cli/cloudwatch-put-metric-data

CloudConsole is an independent iPhone and Android app for Amazon Web Services by Cloudconcur Ltd. It is not affiliated with Amazon Web Services.
