# DynamoDB ReadThrottleEvents alarm for a GSI

CloudWatch alarms · Updated 17 November 2026

**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.

## 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](https://cloudconsole.dev/alarms/dynamodb-readthrottleevents) will not see them.

| | Table alarm | GSI alarm |
|---|---|---|
| Dimensions | `TableName` | `TableName`, `GlobalSecondaryIndexName` |
| Affected calls | `GetItem`, `Query`, `Scan` on the table | `Query` and `Scan` with `IndexName` set |
| Typical cause | Table capacity, hot item | Index 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

| Setting | Value |
|---|---|
| Namespace | `AWS/DynamoDB` |
| Metric | `ReadThrottleEvents` |
| Dimensions | `TableName`, `GlobalSecondaryIndexName` |
| Statistic | `Sum` |
| Period | 60 seconds |
| Datapoints to alarm | 5 |
| Evaluation periods | 5 |
| Comparison operator | `GreaterThanThreshold` |
| Threshold | Depends on your situation: set per index from its history |

Per the CloudWatch [recommended alarms](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html) 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.

[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

- [Recommended alarms for AWS services (Amazon CloudWatch User Guide)](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html)
- [Troubleshooting throttling issues in Amazon DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/TroubleshootingThrottling.html)

## Related

- [CloudWatch alarm for DynamoDB ReadThrottleEvents (table)](https://cloudconsole.dev/alarms/dynamodb-readthrottleevents)
- [DynamoDB WriteThrottleEvents alarm for a global secondary index](https://cloudconsole.dev/alarms/dynamodb-gsi-writethrottleevents)
- [ProvisionedThroughputExceededException](https://cloudconsole.dev/errors/dynamodb-provisionedthroughputexceeded)
- [aws dynamodb query](https://cloudconsole.dev/cli/dynamodb-query)
- [aws dynamodb describe-table](https://cloudconsole.dev/cli/dynamodb-describe-table)
- [CloudWatch alarm for DynamoDB AccountProvisionedReadCapacityUtilization](https://cloudconsole.dev/alarms/dynamodb-accountprovisionedreadcapacityutilization)

---

Source: https://cloudconsole.dev/alarms/dynamodb-gsi-readthrottleevents

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