Context
Request units measure the resources consumed by Cosmos DB operations. Provisioned throughput supplies a budget over time, but that budget is distributed across physical partitions. A hot logical partition can overload its physical range while other ranges remain quiet. Aggregate account consumption can therefore look comfortable during user-visible throttling.
Prerequisites are the account API, database, container, throughput mode and an incident window. This workflow targets provisioned throughput for the API for NoSQL. Gather SDK diagnostics and end-to-end latency, because SDK retries can hide individual 429 responses from application error counters.
1. Measure the user-visible effect
Compare successful requests, 429 responses, retry delays and application latency for the affected container. A small amount of internally retried throttling is not automatically an incident. Determine whether retries breach the business request deadline or consume excessive worker capacity.
Separate data throughput errors from metadata-related or other 429 categories using the actual response details. Increasing container throughput is not a universal correction for every response carrying that status. Retain operation types, request charges and correlation identifiers without logging sensitive document contents.
2. Split normalized RU by partition range
In Insights, inspect normalized RU consumption by PartitionKeyRangeId for the same interval. Compare the busiest ranges with the rest rather than using only a maximum line. Consistently uneven ranges suggest a distribution problem. Pressure across many ranges points toward a broader capacity or query-cost issue.
Use supported diagnostic information to identify the logical keys and operations consuming the most request units. Distinguish a single highly active tenant from a cross-partition query or an inefficient index-dependent access pattern. The physical range identifier is not itself the business partition key, so preserve that distinction in the investigation notes.
3. Correct the demand pattern
For expensive queries, inspect filters, query shape and indexing before changing the data model. For one hot key, consider workload scheduling, bounded concurrency or an architecture that distributes that tenant's activity more deliberately. A partition-key redesign usually requires a migration plan with application changes, not a quick configuration toggle.
If legitimate pressure is spread broadly, evaluate throughput changes within the approved cost boundary. Test the same request mix and burst pattern rather than a uniform synthetic load. Keep retry limits aligned with application deadlines so a capacity change does not merely conceal unacceptable latency.
Diagnostic checkpoints
| Evidence | Likely explanation | Next check |
|---|---|---|
| One range repeatedly busiest | Hot key distribution | Logical key demand |
| Many ranges saturated | Broad demand or costly queries | RU by operation |
| Portal 429s, no app errors | SDK retries succeed | End-to-end retry latency |
| Low request count, high RU | Expensive access pattern | Query diagnostics |
Illustrative scenario
A hypothetical multitenant container partitions by tenant ID. One large tenant begins a bulk import while smaller tenants remain quiet. Raising account-wide expectations from the average load misses the concentrated key. Operators first inspect that tenant's concurrency and access pattern before evaluating migration or capacity options. The scenario is illustrative and includes no invented utilization results.
Verification and partition SOP
Accept a correction only after representative operations complete within their deadlines and the expected key distribution is understood. Compare request charges and range-level pressure with the baseline. Include the busiest tenant or batch in validation; an average tenant test is insufficient.
Maintain partition-key assumptions and large-tenant exceptions in the architecture SOP. Monitor per-range normalized consumption alongside latency and retry volume. Review distribution before onboarding unusually large tenants or introducing date-based bulk workloads that concentrate writes under a small set of keys.
Explore Clouvenix cloud architecture for implementation and operational handover.