Check Cosmos DB hot partitions before reducing throughput
On this page
A throughput cut can increase rate limiting, so check partition utilization and 429 responses before reducing RU/s. Hold the cut if multiple partition ranges stay at 100% utilization and more than 5% of requests return 429s. Review uneven demand with the workload owner before approving a reduction.
What you need first
- Tool
- Run the command in the existing Azure Monitor Log Analytics workspace receiving the Cosmos DB resource-specific logs. It needs the CDBPartitionKeyRUConsumption table.
- Access
- Ask an authorized Azure colleague to provide read-only log results and utilization and request metrics for your account, database, container, regions and review window if you cannot read them yourself.
- If you do not use that tool
- Give your Azure monitoring colleague the account resource ID, database, container, regions and review window. Ask for normalized utilization by partition range, the percentage of requests returning 429, and the ranked results from the query below.
Why this is worth a look
One busy partition can run out of throughput while others have room. Cosmos DB distributes provisioned throughput equally across partition key ranges, each mapped to a physical partition. Normalized RU Consumption shows the highest utilization across ranges in each one-minute interval, not a container average.
Logical partition-key logs show consumed request units (RU), not spare capacity. Use them to locate concentrated demand, not to decide how far to cut throughput.
Start with this query
KQLRun in the receiving Log Analytics workspace. Replace all three REPLACE_WITH values. Scope: one account and container, all logged regions, preceding hour. TotalRU is logged RU per row group; PeakSecondRU is the largest one-second RU total for that group, not provisioned capacity. PeakSecond is UTC.
CDBPartitionKeyRUConsumption
| where TimeGenerated >= ago(1h) and TimeGenerated <= now()
| where _ResourceId =~ "REPLACE_WITH_ACCOUNT_RESOURCE_ID"
| where DatabaseName == "REPLACE_WITH_DATABASE_NAME"
| where CollectionName == "REPLACE_WITH_CONTAINER_NAME"
| summarize SecondRU = sum(RequestCharge)
by PeakSecond = bin(TimeGenerated, 1s),
AccountName,
DatabaseName,
CollectionName,
RegionName,
PartitionKeyRangeId,
PartitionKey,
OperationName
| summarize TotalRU = sum(SecondRU), arg_max(SecondRU, PeakSecond)
by AccountName,
DatabaseName,
CollectionName,
RegionName,
PartitionKeyRangeId,
PartitionKey,
OperationName
| project AccountName,
DatabaseName,
CollectionName,
RegionName,
PartitionKeyRangeId,
PartitionKey,
OperationName,
TotalRU,
PeakSecondRU = SecondRU,
PeakSecond
| order by TotalRU descHow to confirm it
- 01
Compare utilization across partitions
Review Normalized RU Consumption for the preceding hour. Use Add filter for DatabaseName, CollectionName and Region, then Apply splitting by PartitionKeyRangeID. Flag ranges that stay higher than others. For a shared-throughput database, review database-level utilization; this metric does not provide per-container data.
- 02
Check rate limiting and latency
Open the Cosmos DB account's Insights > Requests > Total Requests by Status Code for API for NoSQL. Filter to the same database, container and hour; compare the percentage returning 429 and split by Operation Type. Use Gremlin Requests, Mongo Requests or Cassandra Requests for those APIs. Ask the workload owner whether end-to-end latency is acceptable.
- 03
Locate concentrated demand in existing logs
Run the query with your account resource ID, database and container, or request its results from your Azure monitoring colleague. Compare high TotalRU and PeakSecondRU rows with utilization in the matching region and partition range. Use PeakSecond to locate the corresponding second. If logs are unavailable, continue with metrics rather than treating missing results as low demand.
- 04
Decide whether to pause the cut
Pause the cut if multiple ranges are consistently at 100% and more than 5% of requests return 429s; Azure recommends increasing throughput in that case. Ask the workload owner to review persistently uneven utilization before approving a reduction. In production, 1–5% 429s with acceptable latency can be healthy. An isolated 100% spike alone does not require a change or establish that a cut is safe.
Before making changes
Do not approve a cut from one quiet hour; repeat the review for expected busy periods. The query assumes resource-specific partition-key RU logs already reach this workspace and covers only recorded requests. It calculates neither normalized utilization nor a 429 rate. Client libraries can retry 429 responses, so compare metrics with application latency rather than relying only on errors users see.