Monitor Azure Cosmos DB data using Azure Monitor Log Analytics diagnostic settings

APPLIES TO: NoSQL MongoDB Cassandra Gremlin Table

Diagnostic settings in Azure are used to collect resource logs. Resources emit Azure resource Logs and provide rich, frequent data about the operation of that resource. These logs are captured per request and are referred to as "data plane logs." Some examples of the data plane operations include delete, insert, and readFeed. The content of these logs varies by resource type.

Platform metrics and the Activity logs are collected automatically, whereas you must create a diagnostic setting to collect resource logs or forward them outside of Azure Monitor. You can turn on diagnostic setting for Azure Cosmos DB accounts and send resource logs to the following sources:

• Azure Monitor Log Analytics workspaces
  • Data sent to Log Analytics can be written into Azure Diagnostics (legacy) or Resource-specific (preview) tables
• Event hub
• Storage Account

Note

We recommend creating the diagnostic setting in resource-specific mode (for all APIs except API for Table) following our instructions for creating diagnostics setting via REST API. This option provides additional cost-optimizations with an improved view for handling data.

Prerequisites

• An existing Azure Cosmos DB account.
  • If you have an Azure subscription, create a new account.
  • If you don't have an Azure subscription, create a free account before you begin.
  • Alternatively, you can try Azure Cosmos DB free before you commit.
• An existing Azure Monitor Log Analytics workspace.

Create diagnostic settings

Here, we walk through the process of creating diagnostic settings for your account.

Note

The metric to logs export as a category is not currently supported.

Azure portal

1. Sign in to the Azure portal.

2. Navigate to your existing Azure Cosmos DB account.

3. In the Monitoring section of the resource menu, select Diagnostic settings. Then, select the Add diagnostic setting option.

   

   Important

   You might see a prompt to "enable full-text query [...] for more detailed logging" if the full-text query feature is not enabled in your account. You can safely ignore this warning if you do not wish to enable this feature. For more information, see enable full-text query.

4. In the Diagnostic settings pane, name the setting example-setting and then select the QueryRuntimeStatistics category. Send the logs to a Log Analytics Workspace selecting your existing workspace. Finally, select Resource specific as the destination option.

   

Azure CLI

Use the az monitor diagnostic-settings create command to create a diagnostic setting with the Azure CLI. See the documentation for this command for descriptions of its parameters.

1. Ensure you logged in to the Azure CLI. For more information, see sign in with Azure CLI.

2. Use az monitor diagnostic-settings create to create the setting.

   az monitor diagnostic-settings create \
     --resource $(az cosmosdb show \
       --resource-group "<resource-group-name>" \
       --name "<account-name>" \
       --query "id" \
       --output "tsv" \
     ) \
     --workspace $(az monitor log-analytics workspace show \
       --resource-group "<resource-group-name>" \
       --name "<account-name>" \
       --query "id" \
       --output "tsv" \
     ) \
     --name "example-setting" \
     --export-to-resource-specific true \
     --logs '[
       {
         "category": "QueryRuntimeStatistics",
         "enabled": true
       }
     ]'
   

   Important

   This sample uses the --export-to-resource-specific argument to enable resource-specific tables.

3. Review the results of creating your new setting using az monitor diagnostics-settings show.

   az monitor diagnostic-settings show \
     --name "example-setting" \
     --resource $(az cosmosdb show \
       --resource-group "<resource-group-name>" \
       --name "<account-name>" \
       --query "id" \
       --output "tsv" \
     )
   

REST API

Use the Azure Monitor REST API for creating a diagnostic setting via the interactive console.

1. Ensure you logged in to the Azure CLI. For more information, see sign in with Azure CLI.

2. Create the diagnostic setting for your Azure Cosmos DB resource using an HTTP PUT request and az rest.

   diagnosticSettingName="example-setting"
   
   resourceId=$(az cosmosdb show \
     --resource-group "<resource-group-name>" \
     --name "<account-name>" \
     --query "id" \
     --output "tsv" \
   )
   
   workspaceId=$(az monitor log-analytics workspace show \
     --resource-group "<resource-group-name>" \
     --name "<account-name>" \
     --query "id" \
     --output "tsv" \
   )
   
   az rest \
     --method "PUT" \
     --url "$resourceId/providers/Microsoft.Insights/diagnosticSettings/$diagnosticSettingName" \
     --url-parameters "api-version=2021-05-01-preview" \
     --body '{
       "properties": {
         "workspaceId": "'"$workspaceId"'",
         "logs": [
           {
             "category": "QueryRuntimeStatistics",
             "enabled": true
           }
         ],
         "logAnalyticsDestinationType": "Dedicated"
       }
     }'
   

   Important

   This sample sets the logAnalyticsDestinationType property to Dedicated to enable resource-specific tables.

3. Use az rest again with an HTTP GET verb to get the properties of the diagnostic setting.

   diagnosticSettingName="example-setting"
   
   resourceId=$(az cosmosdb show \
     --resource-group "<resource-group-name>" \
     --name "<account-name>" \
     --query "id" \
     --output "tsv" \
   )
   
   az rest \
     --method "GET" \
     --url "$resourceId/providers/Microsoft.Insights/diagnosticSettings/$diagnosticSettingName" \
     --url-parameters "api-version=2021-05-01-preview"
   

Bicep

Use an Bicep template to create the diagnostic setting.

1. Ensure you logged in to the Azure CLI. For more information, see sign in with Azure CLI.

2. Create a new file named diagnosticSetting.bicep.

3. Enter the following Bicep template content that deploys the diagnostic setting for your Azure Cosmos DB resource.

   @description('The name of the diagnostic setting to create.')
   param diagnosticSettingName string = 'example-setting'
   
   @description('The name of the Azure Cosmos DB account to monitor.')
   param azureCosmosDbAccountName string
   
   @description('The name of the Azure Monitor Log Analytics workspace to use.')
   param logAnalyticsWorkspaceName string
   
   resource azureCosmosDbAccount 'Microsoft.DocumentDB/databaseAccounts@2021-06-15' existing = {
     name: azureCosmosDbAccountName
   }
   
   resource logAnalyticsWorkspace 'Microsoft.OperationalInsights/workspaces@2023-09-01' existing = {
     name: logAnalyticsWorkspaceName
   }
   
   resource diagnosticSetting 'Microsoft.Insights/diagnosticSettings@2021-05-01-preview' = {
     name: diagnosticSettingName
     scope: azureCosmosDbAccount
     properties: {
       workspaceId: logAnalyticsWorkspace.id
       logAnalyticsDestinationType: 'Dedicated'
       logs: [
         {
           category: 'QueryRuntimeStatistics'
           enabled: true
         }
       ]
     }
   }    
   

   Important

   This sample sets the logAnalyticsDestinationType property to Dedicated to enable resource-specific tables.

4. Deploy the template using az deployment group create.

   az deployment group create \
       --resource-group "<resource-group-name>" \
       --template-file diagnosticSetting.bicep \
       --parameters \
         azureCosmosDbAccountName="<azure-cosmos-db-account-name>" \
         logAnalyticsWorkspaceName="<log-analytics-workspace-name>"
   

   Tip

   Use the az bicep build command to convert the Bicep template to an Azure Resource Manager template.

ARM Template

Use an Azure Resource Manager template to create the diagnostic setting.

1. Ensure you logged in to the Azure CLI. For more information, see sign in with Azure CLI.

2. Create a new file named diagnosticSetting.bicep.

3. Enter the following Azure Resource Manager template content that deploys the diagnostic setting for your Azure Cosmos DB resource.

   {
     "$schema": "<https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#>",
     "contentVersion": "1.0.0.0",
     "parameters": {
       "diagnosticSettingName": {
         "type": "string",
         "defaultValue": "example-setting",
         "metadata": {
           "description": "The name of the diagnostic setting to create."
         }
       },
       "azureCosmosDbAccountName": {
         "type": "string",
         "metadata": {
           "description": "The name of the Azure Cosmos DB account to monitor."
         }
       },
       "logAnalyticsWorkspaceName": {
         "type": "string",
         "metadata": {
           "description": "The name of the Azure Monitor Log Analytics workspace to use."
         }
       }
     },
     "resources": [
       {
         "type": "Microsoft.Insights/diagnosticSettings",
         "apiVersion": "2021-05-01-preview",
         "scope": "[format('Microsoft.DocumentDB/databaseAccounts/{0}', parameters('azureCosmosDbAccountName'))]",
         "name": "[parameters('diagnosticSettingName')]",
         "properties": {
           "workspaceId": "[resourceId('Microsoft.OperationalInsights/workspaces', parameters('logAnalyticsWorkspaceName'))]",
           "logAnalyticsDestinationType": "Dedicated",
           "logs": [
             {
               "category": "QueryRuntimeStatistics",
               "enabled": true
             }
           ]
         }
       }
     ]
   }
   

   Important

   This sample sets the logAnalyticsDestinationType property to Dedicated to enable resource-specific tables.

4. Deploy the template using az deployment group create.

   az deployment group create \
       --resource-group "<resource-group-name>" \
       --template-file azuredeploy.json \
       --parameters \
         azureCosmosDbAccountName="<azure-cosmos-db-account-name>" \
         logAnalyticsWorkspaceName="<log-analytics-workspace-name>"
   

   Tip

   Use the az bicep decompile command to convert the Azure Resource Manager template to a Bicep template.

Enable full-text query for logging query text

Azure Cosmos DB provides advanced logging for detailed troubleshooting. By enabling full-text query, you're able to view the deobfuscated query for all requests within your Azure Cosmos DB account. You also give permission for Azure Cosmos DB to access and surface this data in your logs.

Warning

Enabling this feature may result in additional logging costs, for pricing details visit Azure Monitor pricing. It is recommended to disable this feature after troubleshooting.

Azure portal

1. On the existing Azure Cosmos DB account page, select the Features option within the Settings section of the resource menu. Then, select the Diagnostics full-text query feature.

   

2. In the dialog, select Enable. This setting is applied within a few minutes. All newly ingested logs now have the full-text or PIICommand text for each request.

   

Azure CLI / REST API / Bicep / ARM Template

Use the Azure CLI to enable full-text query for your Azure Cosmos DB account.

1. Enable full-text query using az rest again with an HTTP PATCH verb and a JSON payload.

   az rest \
     --method "PATCH" \
     --url $(az cosmosdb show \
       --resource-group "<resource-group-name>" \
       --name "<account-name>" \
       --query "id" \
       --output "tsv" \
     ) \
     --url-parameters "api-version=2021-05-01-preview" \
     --body '{
       "properties": {
         "diagnosticLogSettings": {
           "enableFullTextQuery": "True"
         }
       }
     }'
   

2. Wait a few minutes for the operation to complete. Check the status of full-text query by using az rest again with HTTP GET.

   az rest \
     --method "GET" \
     --url $(az cosmosdb show \
       --resource-group "<resource-group-name>" \
       --name "<account-name>" \
       --query "id" \
       --output "tsv" \
     ) \
     --url-parameters "api-version=2021-05-01-preview" \
     --query "{accountName:name,fullTextQueryEnabled:properties.diagnosticLogSettings.enableFullTextQuery}"
   

   The output should be similar to this example.

   {
     "accountName": "<account-name>",
     "fullTextQueryEnabled": "True"
   }
   

Related content

• Diagnostic queries in API for NoSQL
• Diagnostic queries in API for MongoDB
• Diagnostic queries in API for Apache Cassandra