aws cloudwatch put-metric-data: Emit Custom Metrics

aws cloudwatch put-metric-data publishes custom metric values (and dimensions) to a namespace, letting a pipeline record deploy frequency, build duration, or success/failure counts.

Track DORA-style metrics straight from CI: emit a data point per deploy. put-metric-data is the write path; the dimension and namespace conventions decide whether the data is usable later.

What it does

aws cloudwatch put-metric-data writes one or more data points under --namespace. You pass either the simple --metric-name/--value/--dimensions/--unit form or a richer --metric-data JSON for multiple points. Custom namespaces must not start with "AWS/" (reserved).

Common usage

Terminal

aws cloudwatch put-metric-data \
  --namespace CI/Deploys \
  --metric-name DeployCount \
  --value 1 \
  --unit Count \
  --dimensions Service=my-service,Stage=prod
# Record build duration
aws cloudwatch put-metric-data --namespace CI/Builds \
  --metric-name DurationSeconds --value "$SECONDS" --unit Seconds \
  --dimensions Pipeline=main

Options

Flag	What it does
--namespace <name>	Metric namespace (cannot start with AWS/)
--metric-name <name>	Metric name (simple form)
--value <number>	Single data point value
--unit <unit>	Count, Seconds, Bytes, Percent, etc.
--dimensions Name=Value,..	Up to 30 dimensions per metric
--metric-data <json>	Multiple data points / timestamps at once

In CI

Keep dimension sets stable and low-cardinality: a metric is uniquely identified by name plus its exact dimension combination, so adding a per-run dimension creates a brand-new metric each time and fragments your data. New custom metrics can take a minute to appear in the console; do not treat a delayed graph as a failed write. Custom metrics are billed per metric, so avoid high-cardinality dimensions.

Common errors in CI

"An error occurred (InvalidParameterValue) when calling the PutMetricData operation: The value AWS/CI is not a valid namespace" means you used the reserved AWS/ prefix. "ValidationError: The parameter MetricData.member.1.Value must be ..." means a non-numeric --value. "AccessDenied" means missing cloudwatch:PutMetricData. "Throttling: Rate exceeded" can occur if a fan-out job emits very frequently; batch with --metric-data.