Azure Cosmos DB + Functions Cookbook — Shared throughput and new health logs

This new recipe aims at both, reducing your operational costs, and being able to monitor and analyze the health of your Azure Functions using the Azure Cosmos DB Trigger.


If you are currently using (or plan to use) the Cosmos DB Trigger, through the official documentation or any of my previous posts, you will notice that it requires a second collection to store the Leases (or state). Maintaining this second collection (even if it’s on the minimum 400 RU) translates to a cost.


Cosmos DB has a feature that allows you to provision throughput at the Database layer and share it with all the containers/collections within. This means that we could create a Database, provision Throughput, and share it among the collection we want to monitor AND the collection that holds the leases, effectively reducing operational costs.

Shared throughput databases can be created through the Azure Portal or programmatically through the SDKs.

Database throughput can be shared among both monitored and leases collection
Take note though that when using Shared throughput, the same principle of making sure your Leases collection is not being throttled applies. So make sure the shared throughput (whichever is the value) is good for your operational needs.


The new version of the Cosmos DB Trigger works seamlessly with collections contained in Databases with or without shared throughput, so you don’t need to do anything extra! (wasn’t that the easiest recipe ever?).


For dessert, we’ll have a nice plate of monitoring. Like we mentioned, the Trigger requires a Leases collection to store state (this enables dynamic scaling and start/stop/restart scenarios). Under the covers, the Trigger uses the Change Feed Processor library to maintain it, and in the past, troubleshooting any possible issue with the leases state was extremely hard.

The new version exposes the internal logs that show the current state and operations happening in the leases, and you can wire it up to your favorite log provider for Azure Functions!

The first step, is to enable the traces to be sent. Following the official Azure Functions documentation, you need to add the trigger explicitly to your host.json logging configuration like so:

Add the Host.Triggers.CosmosDB category

Once deployed, you will start seeing logs with the lease operations in your logs storage, like Azure Application Insights:

Expose the lease operations on Application Insights

This will help troubleshoot any scenario where your Trigger configuration might be yielding issues with the leases, and you can analyze the errors that might be happening.