Edit

How to configure logging and connectivity with the Azure Functions trigger for Azure Cosmos DB

  • Article

APPLIES TO: NoSQL

This article describes advanced configuration options you can set when using the Azure Functions trigger for Azure Cosmos DB.

Enabling trigger specific logs

The Azure Functions trigger for Azure Cosmos DB uses the Change Feed Processor Library internally, and the library generates a set of health logs that can be used to monitor internal operations for troubleshooting purposes.

The health logs describe how the Azure Functions trigger for Azure Cosmos DB behaves when attempting operations during load-balancing, initialization, and processing scenarios.

Enabling logging

To enable logging when using Azure Functions trigger for Azure Cosmos DB, locate the host.json file in your Azure Functions project or Azure Functions App and configure the level of required logging. Enable the traces for Host.Triggers.CosmosDB as shown in the following sample:

{
  "version": "2.0",
  "logging": {
    "fileLoggingMode": "debugOnly",
    "logLevel": {
      "Host.Triggers.CosmosDB": "Warning"
    }
  }
}

After the Azure Function is deployed with the updated configuration, you'll see the Azure Functions trigger for Azure Cosmos DB logs as part of your traces. You can view the logs in your configured logging provider under the Category Host.Triggers.CosmosDB.

Which type of logs are emitted?

Once enabled, there are four levels of log events that will be emitted:

  • Error:

    • When there's an unknown or critical error on the Change Feed processing that is affecting the correct trigger functionality.

  • Warning:

    • When your Function user code had an unhandled exception - There's a gap in your Function code and the Function isn't resilient to errors or a serialization error (for C# Functions, the raw json can't be deserialized to the selected C# type).
    • When there are transient connectivity issues preventing the trigger from interacting with the Azure Cosmos DB account. The trigger will retry these transient connectivity errors but if they extend for a long period of time, there could be a network problem. You can enable Debug level traces to obtain the Diagnostics from the underlying Azure Cosmos DB SDK.

  • Information:

    • When a lease is taken to another instance - During initialization and when the Function scales, the leases can be rebalanced to another instance. If you customized the acquire or expiration intervals, it can also indicate that the values might be inappropriate (the expiration interval is lower than renewal).

  • Debug:

    • When a lease is acquired by an instance - The current instance will start processing the Change Feed for the lease.
    • When a lease is released by an instance - The current instance has stopped processing the Change Feed for the lease.
    • When new changes are delivered from the trigger to your Function code - Helps debug situations when your Function code might be having errors and you aren't sure if you're receiving changes or not.
    • For traces that are Warning and Error, adds the Diagnostics information from the underlying Azure Cosmos DB SDK for troubleshooting purposes.

You can also refer to the source code to see the full details.

Query the logs

Run the following query to query the logs generated by the Azure Functions trigger for Azure Cosmos DB in Azure Application Insights' Analytics:

traces
| where customDimensions.Category == "Host.Triggers.CosmosDB"

Configuring the connection policy

There are two connection modes - Direct mode and Gateway mode. To learn more about these connection modes, see the connection modes article. By default, Gateway is used to establish all connections on the Azure Functions trigger for Azure Cosmos DB. However, it might not be the best option for performance-driven scenarios.

Changing the connection mode and protocol

There are two key configuration settings available to configure the client connection policy – the connection mode and the connection protocol. You can change the default connection mode and protocol used by the Azure Functions trigger for Azure Cosmos DB and all the Azure Cosmos DB bindings). To change the default settings, you need to locate the host.json file in your Azure Functions project or Azure Functions App and add the following extra setting:

{
  "cosmosDB": {
    "connectionMode": "Direct",
    "protocol": "Tcp"
  }
}

Where connectionMode must have the desired connection mode (Direct or Gateway) and protocol the desired connection protocol (Tcp for Direct mode or Https for Gateway mode).

If your Azure Functions project is working with Azure Functions V1 runtime, the configuration has a slight name difference, you should use documentDB instead of cosmosDB:

{
  "documentDB": {
    "connectionMode": "Direct",
    "protocol": "Tcp"
  }
}

Customizing the user agent

The Azure Functions trigger for Azure Cosmos DB performs requests to the service that will be reflected on your monitoring. You can customize the user agent used for the requests from an Azure Function by changing the userAgentSuffix in the host.json extra settings:

{
  "cosmosDB": {
    "userAgentSuffix": "MyUniqueIdentifier"
  }
}

Note

When hosting your function app in a Consumption plan, each instance has a limit in the amount of Socket Connections that it can maintain. When working with Direct / TCP mode, by design more connections are created and can hit the Consumption plan limit, in which case you can either use Gateway mode or instead host your function app in either a Premium plan or a Dedicated (App Service) plan.

Next steps