Diagnosing Azure Cosmos DB Change Feed Processor Lag

The problem and the useful takeaway

Your Cosmos DB Change Feed processor is returning stale data, and Azure Monitor shows the estimated lag climbing past your alert threshold—commonly five minutes. Scaling up request units (RUs) is the first instinct, but it often fails when the real issue is a hot partition or a slow consumer. This guide walks through a diagnostic order: confirm lag, check for throttling, inspect partition distribution, then profile consumer processing time. Apply the fix that matches the measured cause.

Recognizable condition

You are likely dealing with Change Feed lag when one or more of the following are true:

• The Azure Monitor metric Change Feed Estimated Lag is rising and stays above your configured threshold, for example five minutes.
• Downstream consumers, such as materialized views, caches, or analytics stores, show data that is minutes or hours behind the source container.
• The Change Feed processor host logs lease renewal warnings or reports that it is falling behind on a specific partition range.

Cause and diagnostic table

Observed signal	Likely cause	How to confirm
Estimated lag increasing; HTTP 429 rate greater than zero	Source container throttled by insufficient RUs	Azure Monitor: Total Request Units and HTTP 429 metrics
Lag concentrated on one partition range; uneven storage or RU use	Partition key hotspot	Data Explorer partition metrics or SDK partition key range statistics
Low throttling; processing time per batch exceeds lease renewal interval	Slow or blocking consumer logic	Application logs or distributed traces around Change Feed processing

Ordered checks

1. Confirm lag and throttling in Azure Monitor

Open the Cosmos DB account in the Azure portal, select Metrics, and add these metrics:

• Change Feed Estimated Lag for the affected container and feed.
• Total Request Units and HTTP 429 (Too Many Requests) for the same container.

Where: Azure portal > your Cosmos DB account > Metrics. Permissions: Monitoring Reader or a role that can read metrics. Expected check: lag is trending upward and the 429 rate is above zero during the lag window. Risk: none; this is read-only.

2. Inspect partition key distribution

If throttling is present, determine whether it is account-wide or concentrated on one logical partition. In Data Explorer, view the container’s Metrics tab for storage and RU consumption per partition key range, or query partition statistics through the SDK.

Where: Azure portal > Data Explorer > your container > Metrics, or your application environment with the Cosmos DB SDK. Permissions: Read access to the Cosmos DB account. Expected check: one partition holds a disproportionate share of storage or RU usage. Risk: none; read-only.

3. Profile consumer processing time

Measure how long the consumer takes to process a single Change Feed batch and compare it to the lease renewal interval. If processing is slower than the interval, leases may not renew promptly and the processor appears stalled.

Where: Application logs or tracing backend. Permissions: Access to application logs. Expected check: average batch processing time exceeds the configured lease renewal interval. Risk: none; read-only.

Fixes tied to findings

If the source container is throttled

Increase provisioned throughput or switch to autoscale, but only after confirming the hotspot check did not reveal a single dominant partition. Throughput is shared across physical partitions, so a hot logical partition can still be throttled even when total account RUs appear sufficient.

Example configuration: raise a manually provisioned container from 4,000 to 8,000 RU/s, or enable autoscale with a maximum of 8,000 RU/s.

az cosmosdb sql container throughput update --account-name  --resource-group  --database-name  --container-name  --throughput 8000

Where: local terminal or Azure Cloud Shell with the Azure CLI installed. Permissions: Microsoft.DocumentDB/databaseAccounts/write, typically through the Contributor role on the Cosmos DB account. Expected check: after the change, Total Request Units consumption drops below the new limit, HTTP 429 falls to zero, and Change Feed Estimated Lag trends downward within a few minutes. Risk: higher hourly cost; if a partition hotspot exists, the additional RUs may not reduce lag.

If a partition key hotspot is confirmed

Raising RUs alone will not fix a hot logical partition. Options include choosing a new partition key with more even write distribution and migrating data to a new container, or spreading writes across existing keys. Partition key migration is a state-changing operation: build the new container, validate the Change Feed on it, then switch the consumer and decommission the old container. Keep the old container available until the new feed is stable so you can point the processor back if migration validation fails.

If consumer processing is slow

Optimize the handler: remove blocking calls, parallelize independent work inside a batch where safe, and reduce the amount of downstream work per Change Feed item. You can also add consumer instances, up to the number of partitions, so lease ownership is spread across more hosts. Do not disable lease renewal or drastically extend the feed polling interval to hide lag; that weakens the processor’s recovery and exactly-once behavior.

Escalation criteria

Open a support ticket or engage the platform team when:

• Estimated lag remains high after RU increases, HTTP 429 is zero, and no partition hotspot exists.
• The lease container itself is throttled, which can stall all processor hosts.
• Consumer processing time is under the lease interval but lag still grows, suggesting a feed-level or service-side issue.

Limitations and how to verify the result

Change Feed Estimated Lag is approximate and can have reporting latency. Treat a downward trend over multiple minutes as more meaningful than a single data point. After applying a fix, confirm the result by checking that:

• Change Feed Estimated Lag stays below your threshold for at least one full processing cycle.
• HTTP 429 returns to zero and remains there during peak write traffic.
• Downstream data freshness matches the source within your acceptable window.

If lag returns when traffic increases, revisit the partition distribution check; the workload may have outgrown the current partition key design.