Databases Azure Cosmos DB premium

Change feed processor

Change feed processor is a Cosmos DB SDK component that watches a container change feed and distributes batches of changes across one or more application hosts. In everyday Azure work, it helps teams scale event processing, maintain checkpoints in a lease container, and let business logic react to changed documents without each worker manually coordinating feed ranges. You usually see it around application workers, App Service instances, AKS pods, VM hosts, monitored containers, lease containers, SDK configuration, diagnostics, and event-processing runbooks.

Aliases
No aliases mapped yet
Difficulty
fundamentals
CLI mappings
15
Last verified
2026-05-12

Microsoft Learn

A database capability or setting in Azure Cosmos DB that helps teams store, query, scale, secure, and recover application data with clearer ownership, safety, and operational context. Microsoft Learn places it in Change feed processor in Azure Cosmos DB; operators confirm scope, configuration, dependencies, and production impact.

Microsoft Learn: Change feed processor in Azure Cosmos DB2026-05-12

Technical context

Technically, Change feed processor appears as a .NET or Java SDK processor built with a monitored container, lease container, processor name, instance name, delegate, and optional start settings. Engineers verify it through processor name, instance names, lease documents, monitored container, request charge, diagnostics, delegate errors, host lifecycle notifications, and preferred region settings. Important configuration includes lease prefix, poll interval, start time, feed mode, host scaling, global endpoint, preferred regions, retry behavior, and error-handling delegate. It connects to monitoring, identity, networking, automation, and cost records for consistent review.

Why it matters

Change feed processor matters because an incorrectly configured processor can create competing leases, miss older changes, retry poison batches forever, or checkpoint before asynchronous work finishes. The business impact is rarely abstract: users see slower systems, missing data, failed sign-ins, confusing reports, or unexpected cost when the setting is misunderstood. A solid glossary entry gives architects and operators the same language for design reviews, support handoffs, and audit evidence. It also helps teams decide what to check first, which metric or log proves the current state, who owns remediation, and when a change should be rolled back instead of patched live.

Where you see it

Signals, screens, and Azure surfaces where this term usually becomes operational.

Signal 01

In the Azure portal, Change feed processor appears near Cosmos DB processor configuration, where operators confirm scope, owner, diagnostics, access, and production state before release or incident response.

Signal 02

In CLI, ARM, SDK, REST, or Bicep output, Change feed processor appears as lease containers and worker IDs, giving teams repeatable release and audit evidence during deployments and incidents.

Signal 03

In logs, metrics, tickets, or reviews, Change feed processor appears beside lease balance, lag, retries, and handler errors, linking symptoms to security, reliability, cost, and performance decisions quickly.

When this becomes relevant

Specific situations where this term helps solve real Azure design, operations, migration, security, reliability, cost, or governance problems.

  • Decide how application data is stored, indexed, scaled, cached, and protected.
  • Troubleshoot connection failures, throughput pressure, indexing, backup, or regional availability.
  • Explain why one database capability changes cost, latency, consistency, or recovery behavior.
  • Prepare production changes with source, identity, network, and command context visible.

Real-world case studies

Different enterprise-style examples that show the term being used to hit measurable objectives.

Case study 01

Scaled loyalty event processor

Scenario, objectives, solution, measured impact, and takeaway.

Scenario

AdventureWorks Foods, a restaurant loyalty platform, needed to process Cosmos DB reward changes across many application workers.

Business/Technical Objectives
  • Process reward changes during lunch peaks
  • Distribute work across scalable hosts
  • Guarantee every change reaches the rewards API
  • Reduce manual checkpoint management
Solution Using Change feed processor

Developers used the Azure Cosmos DB change feed processor in the .NET SDK with a monitored rewards container and a dedicated lease container. Each App Service instance had a unique instance name and the same processor name, allowing leases to distribute across hosts. The delegate called the rewards API synchronously enough to avoid premature checkpointing, and failed items were written to an error queue. Azure Monitor tracked request charge, delegate exceptions, lag, and host lifecycle notifications. The team tested scale-out, host restart, and poison event scenarios before production launch. The runbook also captured dashboard links, owner contacts, rollback criteria, and monthly review steps so operators could verify the design without tribal knowledge during incidents or release windows. Evidence from each change was saved with the deployment record for audit, support, and future capacity planning.

Results & Business Impact
  • Lunch peak processing stayed below two minutes of lag
  • Manual checkpoint code was removed from the application
  • Failed reward updates were captured for replay
  • Host scale-out completed without duplicate lease ownership
Key Takeaway for Glossary Readers

The change feed processor gives scalable event processing when leases, host names, delegates, and error handling are disciplined.

Case study 02

Lease container recovery

Scenario, objectives, solution, measured impact, and takeaway.

Scenario

Proseware Health Devices, a medical device platform, needed to recover a stuck change feed processor after a network migration.

Business/Technical Objectives
  • Restore processing within one hour
  • Avoid losing device alert events
  • Prove whether leases or networking caused the issue
  • Prevent recurrence during future migrations
Solution Using Change feed processor

Operations inspected the lease container, host logs, Cosmos DB diagnostics, and private endpoint changes for the processor deployment. They found processors had been reconfigured with a regional endpoint during the network migration, creating a separate lease scope. Engineers restored the global endpoint, validated preferred region settings, and restarted hosts with unique instance names. The team compared unprocessed changes against downstream alert records and replayed missing work through the delegate with idempotent writes. A deployment guard now blocks regional Cosmos DB endpoints in processor configuration. The rollout plan included before-and-after measurements, escalation contacts, exception rules, and a control review with finance, security, and application owners. That evidence made the improvement repeatable and gave support teams a clear baseline when later incidents raised similar symptoms.

Results & Business Impact
  • Processing recovered in 37 minutes
  • No device alert was permanently lost
  • The root cause was documented with lease and endpoint evidence
  • Future endpoint drift is blocked in CI
Key Takeaway for Glossary Readers

Change feed processor reliability depends on endpoint, lease, and host configuration as much as on application code.

Case study 03

Analytics fan-out deployment

Scenario, objectives, solution, measured impact, and takeaway.

Scenario

Tailspin Games, an online gaming studio, needed multiple processors for player inventory updates, fraud signals, and live dashboards.

Business/Technical Objectives
  • Fan out changes to three business workflows
  • Keep each workflow independently scalable
  • Avoid processors stealing each other’s leases
  • Monitor processor lag per workflow
Solution Using Change feed processor

Architects created separate change feed processor deployment units for inventory, fraud, and dashboard workflows. Each used the same monitored player container but a different processor name, lease prefix, and lease container configuration. AKS hosted the workers, with each pod configured with a unique instance name. Delegates wrote to separate downstream systems using idempotent keys and recorded request charge and diagnostics. Azure Monitor dashboards showed lag, failures, and host distribution for each deployment unit. Load tests confirmed that dashboard bursts did not slow fraud processing. Release evidence included configuration snapshots, CLI output, representative metrics, and ticket notes, giving operations a durable baseline for training, audits, and later optimization work. The team also defined when to scale back, rotate credentials, or open a vendor support case.

Results & Business Impact
  • Three workflows processed the same source changes independently
  • Fraud processor lag stayed below 45 seconds during events
  • Dashboard scale-out no longer affected inventory processing
  • On-call teams gained per-workflow lease and lag visibility
Key Takeaway for Glossary Readers

Separate change feed processor deployment units let one Cosmos DB change stream support many workflows without shared-state confusion.

Why use Azure CLI for this?

Use CLI, REST, SDK, or scripted queries for Change feed processor because operators need precise container, lease, throughput, and host evidence before scaling or repairing change feed processors and to avoid portal-only evidence during reviews.

CLI use cases

  • Inspect lease container growth and host ownership during a processor outage.
  • Capture monitored and lease container settings before scaling processors.
  • Verify global endpoint and preferred-region settings after a regional failover test.

Before you run CLI

  • Confirm the active tenant, subscription, resource group, workspace, account, or region before running commands.
  • Use least-privileged access and avoid storing secrets, prompts, certificates, tokens, or personal data in command output.
  • Know whether the command is read-only, mutating, cost-impacting, security-impacting, or destructive before production use.

What output tells you

  • Output confirms whether the live Azure configuration exists at the expected scope and matches the approved design.
  • Returned IDs, settings, metrics, timestamps, or logs help separate configuration drift from application behavior.
  • Differences between expected and actual state create evidence for rollback, escalation, audit, or owner follow-up.

Mapped Azure CLI commands

Azure Cosmos DB operations

direct
az cosmosdb list --resource-group <resource-group>
az cosmosdbdiscoverDatabases
az cosmosdb show --name <account-name> --resource-group <resource-group>
az cosmosdbdiscoverDatabases
az cosmosdb create --name <account-name> --resource-group <resource-group>
az cosmosdbprovisionDatabases
az cosmosdb sql database list --account-name <account-name> --resource-group <resource-group>
az cosmosdb sql databasediscoverDatabases
az cosmosdb delete --name <account-name> --resource-group <resource-group>
az cosmosdbremoveDatabases

Cosmos operations

direct
az cosmosdb show --name <account> --resource-group <resource-group>
az cosmosdbdiscoverDatabases
az cosmosdb create --name <account> --resource-group <resource-group> --locations regionName=<region>
az cosmosdbprovisionDatabases
az cosmosdb update --name <account> --resource-group <resource-group> --enable-automatic-failover true
az cosmosdbconfigureDatabases
az cosmosdb keys list --name <account> --resource-group <resource-group>
az cosmosdb keysdiscoverDatabases
az cosmosdb sql database list --account-name <account> --resource-group <resource-group>
az cosmosdb sql databasediscoverDatabases
az cosmosdb sql database create --account-name <account> --resource-group <resource-group> --name <database>
az cosmosdb sql databaseprovisionDatabases
az cosmosdb sql container list --account-name <account> --resource-group <resource-group> --database-name <database>
az cosmosdb sql containerdiscoverDatabases
az cosmosdb sql container create --account-name <account> --resource-group <resource-group> --database-name <database> --name <container> --partition-key-path <path>
az cosmosdb sql containerprovisionDatabases
az cosmosdb sql container throughput show --account-name <account> --resource-group <resource-group> --database-name <database> --name <container>
az cosmosdb sql container throughputdiscoverDatabases
az cosmosdb sql container throughput update --account-name <account> --resource-group <resource-group> --database-name <database> --name <container> --throughput <ru>
az cosmosdb sql container throughputconfigureDatabases

Architecture context

The change feed processor is the operational coordination layer for Cosmos DB change feed workloads. It lets multiple application instances share feed processing by using a lease container, processor name, host instance identity, checkpoints, and partition ownership. Architects care about it because scale-out behavior, failover, replay, and duplicate handling are controlled as much by the processor design as by the Cosmos DB container itself. Reviews should confirm the lease container has suitable throughput, the monitored container and lease container are separated intentionally, handlers are idempotent, checkpoints happen after durable work, and host logs expose lag or errors. In Azure DevOps, deployment slots or rolling updates must avoid accidentally running competing processors with different names.

Security

Security for Change feed processor starts with understanding which identities, secrets, certificates, endpoints, data stores, or management-plane permissions it touches. Review who can view, change, or use it, and confirm that production access follows least privilege. Check whether private networking, firewall rules, RBAC, key vault storage, managed identity, audit logs, and data classification apply. Operators should avoid exposing tokens, connection strings, prompts, certificate material, or cost-sensitive business metadata in troubleshooting output. A secure design also documents emergency access, rotation responsibilities, and evidence retention so an incident response team can prove the current configuration without inventing access during an outage. Security reviewers should confirm least privilege, private access paths, and audit retention before approving production use.

Cost

Cost for Change feed processor comes from the resources, transactions, data movement, retention, compute, capacity, tokens, or operational labor it influences. Some costs are direct meters, while others appear as extra storage, higher throughput, duplicate processing, export jobs, monitoring ingestion, or engineering time. Review budgets, cost allocation, tags, usage metrics, and SKU limits before scaling or enabling new behavior. The safest approach is to define the owner, expected usage pattern, and alert thresholds up front. That way finance conversations use evidence instead of opinions after the bill arrives. Finance and engineering teams should agree which metric proves usage and which scope owns remediation.

Reliability

Reliability for Change feed processor depends on whether the design behaves predictably during scale events, regional incidents, expired credentials, throttling, schema changes, or downstream failures. Identify the dependency chain, expected failure mode, and recovery target before production use. Monitor the signals that show backlog, lag, retries, health state, capacity saturation, authentication failures, or stale data. Test restore, rotation, failover, replay, or rollback paths where they apply. Operators need a runbook that separates platform configuration problems from application defects and says which evidence is required before escalating to networking, identity, database, or product teams. Runbooks should state the first observable symptom, safe rollback path, and owner escalation route.

Performance

Performance for Change feed processor is about how quickly and consistently the related workload can complete useful work. Measure the right signals: latency, throughput, backlog, request units, token volume, CPU, memory, bytes scanned, file counts, retries, or throttled operations depending on the service. Avoid tuning one setting in isolation when partitions, replicas, keys, network paths, identity calls, downstream services, or client behavior may be the real bottleneck. Performance reviews should compare expected workload shape with live metrics and include a safe test plan before increasing capacity or changing production configuration. Load tests should compare expected throughput, latency, queue depth, and saturation signals against live limits.

Operations

Operationally, Change feed processor needs ownership, naming, tagging, change records, and repeatable verification. Teams should know where it appears in the portal, which commands or queries prove state, which dashboards show health, and which settings are safe to change during business hours. Keep examples, approvals, and rollback notes with the service runbook rather than in personal notes. For production changes, capture current configuration before and after the work, including resource IDs, region, owner, timestamp, and related deployment. Good operations turn the term into a checklist that first responders can follow under pressure. Operational evidence should include timestamps, resource IDs, owner names, and links to the approved change record.

Common mistakes

  • Using regional endpoints and accidentally creating independent lease scopes.
  • Returning from asynchronous delegates before all downstream work is safely complete.
  • Scaling worker count beyond useful lease distribution without checking throughput and lag.