How to Monitor Azure Cosmos DB Request Units and Throttling: Step-by-Step Guide

Azure Cosmos DB throttling happens when your workload consumes more Request Units than provisioned in a given second. The service returns 429 errors and your application retries automatically, but sustained throttling signals a provisioning or partitioning problem that directly impacts latency and cost. According to the Azure Cosmos DB capacity calculator documentation, a single point write consumes approximately 5 RUs, while a 1 KB document read consumes 1 RU, meaning even moderate workloads can quickly exhaust a small provisioned throughput allocation.

This tutorial covers how to monitor Request Unit consumption, detect throttling patterns, and identify hot partitions using Azure Monitor, diagnostic logs, and Kusto queries. By the end, you will know how to set up alerts that catch throttling early and understand what the metrics actually mean in production.

Prerequisites

Before you begin, ensure you have the following:

• An active Azure subscription with at least one Cosmos DB account deployed
• Contributor or Owner role on the Cosmos DB account to access metrics and configure diagnostics
• Azure Monitor or a Log Analytics workspace enabled for diagnostic log ingestion
• Basic familiarity with Azure Portal navigation and Kusto Query Language (KQL) for log queries
• Optional: Azure CLI or PowerShell installed if you prefer command line configuration

Step 1: Understand Request Units and Why They Matter

A Request Unit (RU) is the abstraction Cosmos DB uses to bill compute, memory, and IOPS as a single number. Every database operation, from a simple point read to a complex query with multiple filters, consumes a measurable number of RUs. You provision throughput in units of RU/s (Request Units per second), and Cosmos DB guarantees that throughput as long as your workload does not exceed it.

When you provision 400 RU/s on a container, you can consume up to 400 RUs in any given second. If your application attempts to use 500 RUs in one second, Cosmos DB returns a 429 status code (rate limited) on the requests that pushed consumption above 400. The Cosmos DB SDKs automatically retry these requests with exponential backoff, but the underlying issue, overconsumption, remains.

Throttling is not always a problem. A small percentage of 429 responses (1 to 5%) is normal and often a sign that you are efficiently using your provisioned capacity. Sustained throttling above 5%, however, indicates that your workload consistently exceeds what you provisioned, leading to increased latency, failed requests, and a poor user experience.

Understanding RU consumption patterns is the first step to reducing throttling. A hot partition, where one logical partition key consumes most of your RU/s, can cause throttling even when your total provisioned throughput is underutilized. Similarly, large queries, high volume writes, or indexing overhead from complex queries can spike RU consumption unexpectedly.

Step 2: Enable Azure Monitor Metrics and Diagnostic Logs

Azure Monitor is the primary tool for tracking Cosmos DB performance. Metrics are collected automatically, but diagnostic logs, which surface the details you need to troubleshoot throttling, require explicit configuration.

Navigate to your Cosmos DB account in the Azure Portal. In the left navigation, under Monitoring, select Diagnostic settings. Click Add diagnostic setting. Name the setting (for example, “CosmosDB-Diagnostics”). Under Logs, select the following categories: DataPlaneRequests, QueryRuntimeStatistics, PartitionKeyStatistics, and ControlPlaneRequests. Under Metrics, enable AllMetrics. Choose a destination: send logs to a Log Analytics workspace, an Azure Storage account, or stream to an Event Hub. For most teams, sending to a Log Analytics workspace is the best option because it enables KQL queries for deep analysis. Click Save.

After enabling diagnostics, logs begin flowing within 5 to 10 minutes. You can verify this by navigating to the Log Analytics workspace and running a simple KQL query:

AzureDiagnostics
| where ResourceProvider == "MICROSOFT.DOCUMENTDB"
| take 10

If results appear, diagnostics are working. If not, wait a few minutes and check again.

Step 3: Monitor Total RU Consumption Using Azure Monitor Metrics

Azure Monitor surfaces several key metrics that show how your Cosmos DB account is using its provisioned throughput. These metrics are available without enabling diagnostics, but they only show aggregate data. They do not tell you which partition, query, or operation caused a spike.

Navigate to your Cosmos DB account in the Azure Portal. Under Monitoring, select Metrics. In the Metrics pane, select your database and container as the scope. Add a metric: Total Request Units. This shows the sum of all RUs consumed across all requests in the selected time window. Add another metric: Normalized RU Consumption. This percentage metric shows how much of your provisioned RU/s you consumed in each second. A value of 100% means you used all provisioned capacity. A value over 100% is not possible because Cosmos DB throttles requests once you hit the limit.

Set the time range to the last 24 hours and observe the pattern. If Normalized RU Consumption frequently spikes to 100%, you are hitting your provisioned limit. If it stays below 80%, you likely have headroom. If it hovers at 100% for sustained periods, throttling is occurring and you need to investigate further.

Use the Split By dropdown to break down RU consumption by partition key range ID. Each partition key range ID maps to one physical partition. If one partition consistently shows higher Normalized RU Consumption than others, you have a hot partition. This is a partitioning problem, not a provisioning problem, and scaling up RU/s will not fix it.

Step 4: Identify Throttled Requests in Metrics

Cosmos DB exposes a specific metric for throttling: Total Requests by Status Code. This metric counts how many requests returned each HTTP status code, including 429 (throttled).

In the Metrics pane, add the metric Total Requests by Status Code. Apply a filter: StatusCode equals 429. This shows the count of throttled requests over time. If you see zero throttled requests, throttling is not occurring. If you see a small number (1 to 5% of total requests), this is normal and expected. If throttled requests represent more than 5% of total traffic, or if you see sustained spikes in 429 responses, you have a problem.

Compare the throttled request count to the Normalized RU Consumption metric. If Normalized RU Consumption is at 100% and you see 429 responses, the workload is legitimately exceeding provisioned capacity. If Normalized RU Consumption is below 80% but you still see 429 responses, the throttling is likely due to a hot partition or a transient spike that Azure Monitor did not fully capture at the per-second resolution.

One important note: the Azure Monitor metrics show 429 responses even if your application never saw them. The Cosmos DB SDKs automatically retry throttled requests up to nine times before surfacing the error to your application. A 429 response in Azure Monitor does not necessarily mean your users experienced an error, but it does mean the underlying workload is consuming more RUs than provisioned.

Step 5: Use Diagnostic Logs to Find Hot Partitions and High RU Operations

Metrics show aggregate patterns, but diagnostic logs surface the specific operations, partition keys, and queries consuming the most RUs. This is where you find the root cause.

Navigate to your Log Analytics workspace. Under General, select Logs. Run the following KQL query to find the top 10 partition keys by total RU consumption:

AzureDiagnostics
| where ResourceProvider == "MICROSOFT.DOCUMENTDB"
| where Category == "DataPlaneRequests"
| where TimeGenerated > ago(1h)
| summarize TotalRUs = sum(todouble(requestCharge_s)) by partitionKey_s
| top 10 by TotalRUs desc

This query sums the request charge (RU consumption) for each partition key over the last hour. If one partition key consumes significantly more RUs than others, that is your hot partition. The partition key design is likely the root cause. For example, if you partitioned an IoT workload by date, all writes for a single day hit the same partition, creating a bottleneck.

To find individual high RU operations, run this query:

AzureDiagnostics
| where ResourceProvider == "MICROSOFT.DOCUMENTDB"
| where Category == "DataPlaneRequests"
| where TimeGenerated > ago(1h)
| where todouble(requestCharge_s) > 50
| project TimeGenerated, operationType_s, requestCharge_s, activityId_g, partitionKey_s
| order by requestCharge_s desc

This surfaces operations that consumed more than 50 RUs. Large queries, bulk writes, or operations with complex filters often show up here. Use the activityId_g field to correlate these high RU operations with your application logs.

To see which queries are slow or expensive, run this query using the QueryRuntimeStatistics log:

AzureDiagnostics
| where ResourceProvider == "MICROSOFT.DOCUMENTDB"
| where Category == "QueryRuntimeStatistics"
| where TimeGenerated > ago(1h)
| project TimeGenerated, querytext_s, requestCharge_s, partitionkeyrangeid_s
| order by requestCharge_s desc

This shows the actual query text, the RU cost, and the partition it hit. If you see a query consuming hundreds of RUs, optimize it by adding composite indexes, reducing the result set, or filtering on indexed properties.

Step 6: Set Up Alerts for Throttling and High RU Consumption

Once you understand what normal looks like, set up alerts to catch problems before they escalate.

Navigate to your Cosmos DB account in the Azure Portal. Under Monitoring, select Alerts. Click Create alert rule. Under Scope, confirm your Cosmos DB account is selected. Under Condition, click Add condition. Search for and select Normalized RU Consumption. Set the threshold logic: Whenever Normalized RU Consumption is greater than 90%, fire an alert. Under Aggregation, choose Average over a 5 minute window. This prevents false positives from momentary spikes.

Under Actions, create or select an action group. An action group defines who gets notified (email, SMS, webhook, etc.) and how. Add your team’s email or Slack webhook. Under Alert rule details, name the rule “Cosmos DB High RU Consumption” and set severity to Warning (Sev 2). Click Create alert rule.

Repeat the process to create an alert for throttled requests. Use the metric Total Requests by Status Code, filter for StatusCode equals 429, and set the threshold to greater than 10 requests over a 5 minute window. Name it “Cosmos DB Throttling Detected” and set severity to Error (Sev 1).

These alerts give you early warning before sustained throttling impacts users. Adjust thresholds based on your workload. A workload with natural traffic spikes may need a higher threshold to avoid alert fatigue.

Step 7: Optimize Throughput Provisioning Based on Monitoring Data

After monitoring RU consumption and throttling patterns for at least a week, you can make informed decisions about provisioning.

If Normalized RU Consumption rarely exceeds 60%, you are overprovisioned. Reduce manual throughput or lower the maximum RU/s on autoscale to cut costs. If Normalized RU Consumption frequently hits 100% and you see throttling above 5%, increase provisioned throughput. Start with a 20% increase and monitor for another week. If throttling persists, investigate partition key design. Scaling RU/s will not fix a hot partition problem.

If you use manual throughput, consider switching to autoscale. Autoscale adjusts RU/s dynamically between a minimum and maximum based on actual demand. You only pay for what you use, averaged over an hour. This is ideal for workloads with unpredictable or spiky traffic. For example, an e-commerce site with daily traffic spikes at noon and 6 PM benefits from autoscale because it scales up during peak hours and scales down overnight, reducing cost without manual intervention.

If diagnostic logs show one partition consuming most RUs, redesign your partition key. A good partition key distributes requests evenly across partitions. For an IoT workload partitioned by date, consider a composite key like deviceId or a synthetic key that combines deviceId and date. For a multitenant workload partitioned by tenantId, consider splitting the largest tenant into its own dedicated container with a more granular partition key like userId.

For advanced cost control, consider monitoring tools that integrate with Cosmos DB metrics and surface actionable recommendations. Platforms like Azure monitoring tools centralize metrics from Cosmos DB, App Service, AKS, and other Azure resources, making it easier to correlate Cosmos DB throttling with upstream traffic patterns.

Troubleshooting Common Issues

Throttling occurs but Normalized RU Consumption is below 80%

This is almost always a hot partition problem. One physical partition is hitting 100% RU consumption while others remain idle. Use the diagnostic log query in Step 5 to identify the partition key consuming the most RUs. Redesign your partition key to distribute load more evenly.

High RU consumption on read-heavy workloads

Reads consume RUs based on document size and indexing policy. Large documents, cross-partition queries, and queries without indexed filters all increase RU costs. Run the QueryRuntimeStatistics log query from Step 5 to find expensive queries. Add composite indexes for common query patterns and reduce the number of properties returned using projection.

429 errors appear in Azure Monitor but not in application logs

The Cosmos DB SDKs automatically retry throttled requests. By default, they retry up to nine times with exponential backoff. Your application only sees the 429 error if all retries fail. The 429 responses in Azure Monitor are real, they indicate the workload exceeded provisioned RU/s, but the SDK absorbed the impact. Sustained 429s in Azure Monitor still mean you need to address the root cause, even if users have not reported errors yet.

Provisioned throughput increased but throttling persists

If you have a hot partition, scaling RU/s will not help. Cosmos DB distributes provisioned throughput evenly across physical partitions. A single partition can only use its share of the total RU/s, regardless of how much you provision at the account or database level. Identify the hot partition using diagnostic logs and redesign your partition key.

Autoscale does not scale up fast enough during traffic spikes

Autoscale scales based on observed demand over a 5 to 10 second window. If your traffic spikes faster than autoscale can respond, you will see brief throttling. This is expected behavior. If throttling during spikes is unacceptable, set a higher autoscale maximum or use manual throughput with a buffer above your peak observed RU/s.

Monitoring RU consumption and throttling is not a one time setup. Workload patterns change, data grows, and partition key designs that worked for 1 million documents may fail at 10 million. Review Cosmos DB metrics and diagnostic logs monthly to catch trends before they become incidents.

Disclaimer: Pricing and resource limits in Azure Cosmos DB can change over time. Always verify the latest information directly with Azure documentation before making provisioning decisions.

Frequently Asked Questions