CloudConsole

DynamoDB ReadThrottleEvents alarm for a GSI

Updated 17 November 2026 · How we write and check guides

Short answer

This version of the read-throttle alarm watches a single global secondary index, using the TableName and GlobalSecondaryIndexName dimensions. AWS recommends alarming on the Sum when it is above your chosen threshold for 5 of 5 one-minute periods. Index read throttling only affects Query and Scan calls that target the index, not reads on the base table.

Chart of the ReadThrottleEvents alarm: Sum per 1-minute period, ALARM when 5 of 5 datapoints are > 10
How the recommended alarm evaluates, with AWS's settings from this page and the page's example threshold. The metric values are illustrative.

How GSI read throttling differs from table throttling

A global secondary index is stored and scaled separately from its table. On a provisioned table, every GSI has its own read capacity, its own auto scaling policy and its own partitions. Its read throttles are therefore reported under its own dimensions, and the table-level alarm will not see them.

Table alarmGSI alarm
DimensionsTableNameTableName, GlobalSecondaryIndexName
Affected callsGetItem, Query, Scan on the tableQuery and Scan with IndexName set
Typical causeTable capacity, hot itemIndex under-provisioned, low-cardinality index key

Index keys are often chosen for query convenience, like status or country, and have far fewer distinct values than the table key. That concentrates reads on a few partitions, so GSIs develop hot partitions more readily than their tables.

Recommended alarm settings

SettingValue
NamespaceAWS/DynamoDB
MetricReadThrottleEvents
DimensionsTableName, GlobalSecondaryIndexName
StatisticSum
Period60 seconds
Datapoints to alarm5
Evaluation periods5
Comparison operatorGreaterThanThreshold
ThresholdDepends on your situation: set per index from its history

Per the CloudWatch recommended alarms list. You need one alarm per index you care about.

Choosing a threshold for an index

Look at the index on its own. Compare ReadThrottleEvents with ConsumedReadCapacityUnits for the same table and index over two weeks. A read-heavy index serving a dashboard may show predictable throttling when the dashboard refreshes; set the threshold just above that pattern, or better, give the index capacity for it. An index that rarely throttles can use a single-digit threshold. Use notBreaching for missing data.

If an index exists mainly for occasional admin lookups, consider whether it needs an alarm at all; throttling there may be acceptable, and the effort is better spent on the indexes behind user-facing screens.

Create it

# Example threshold of 10 per minute
aws cloudwatch put-metric-alarm \
  --alarm-name orders-by-status-read-throttles \
  --namespace AWS/DynamoDB \
  --metric-name ReadThrottleEvents \
  --dimensions Name=TableName,Value=orders Name=GlobalSecondaryIndexName,Value=status-index \
  --statistic Sum \
  --period 60 \
  --evaluation-periods 5 \
  --datapoints-to-alarm 5 \
  --threshold 10 \
  --comparison-operator GreaterThanThreshold \
  --treat-missing-data notBreaching \
  --alarm-actions arn:aws:sns:eu-west-2:123456789012:ops-alerts \
  --region eu-west-2

When it fires

  1. Check the index's capacity rather than the table's:
    aws dynamodb describe-table --table-name orders \
      --query "Table.GlobalSecondaryIndexes[?IndexName=='status-index'].ProvisionedThroughput"
  2. Look for a hot index key. Contributor Insights can be enabled per index (add --index-name status-index to update-contributor-insights) to show which key values are throttled most.
  3. Reduce expensive index reads. A Scan on an index, or a Query on a very popular key value with no Limit, reads far more than it returns. Narrow the key condition or add a sort-key condition.
  4. Redesign low-cardinality keys with write sharding (appending a random suffix and querying the shards in parallel) if one value carries most of the traffic.

Questions

Does GSI read throttling affect the base table?

No. Only queries and scans against the index are throttled; reads on the table itself continue normally. Write throttling on a GSI is different and does affect the table.

Why is my GSI throttling when the table is not?

The index has its own capacity and partitions. It may be under-provisioned, or its partition key may have few distinct values, creating a hot partition.

Can I see which index keys are hot?

Yes. Enable CloudWatch Contributor Insights for the index to see the most accessed and most throttled keys.

When this happens away from your desk

Index throttling often hits one screen or report rather than the whole app, so users report it before metrics are checked. CloudConsole, a phone app for AWS, is built to show index-level alarms with the index's own capacity on a phone.

Did it start after a deploy? What changed? on the app’s alarm screen lists the deploys and configuration changes from the hour before the alarm fired.

About the app → · Download on the App Store

Sources