Monitore os dados do Azure Cosmos DB usando as configurações de diagnóstico do Log Analytics do Azure Monitor

APLICA-SE AO: NoSQL MongoDB Cassandra Gremlin Table

As configurações de diagnóstico no Azure são usadas para coletar logs de recursos. Os recursos emitem logs dos recursos do Azure e fornecem dados avançados e frequentes sobre a operação desse recurso. Esses logs são capturados por solicitação e também são chamados de logs do plano de dados. Entre alguns exemplos de operações do plano de dados estão excluir, inserir e readFeed. O conteúdo desses logs varia de acordo com o tipo de recurso.

Para saber mais sobre as configurações de diagnóstico, confira Configurações de diagnóstico no Azure Monitor.

Observação

Recomenda-se criar a configuração de diagnóstico no modo específico do recurso (para todas as APIs, exceto a API de Tabela) seguindo as instruções na guia API REST. Essa opção fornece otimizações de custo adicionais com uma exibição aprimorada para lidar com os dados.

Pré-requisitos

• Uma conta existente do Azure Cosmos DB.
  • Se você tiver uma assinatura do Azure, crie uma nova conta.
  • Se você não tiver uma assinatura do Azure, crie uma conta gratuita antes de começar.
  • Como alternativa, você pode experimentar o Azure Cosmos DB gratuitamente antes de confirmar.
• Um Workspace do Log Analytics do Azure Monitor existente.

Aviso

Se você precisar excluir um recurso, renomear ou mover um recurso, ou migrá-lo entre grupos de recursos ou assinaturas, primeiro exclua suas configurações de diagnóstico. Caso contrário, se você recriar esse recurso, as configurações de diagnóstico do recurso excluído poderão ser incluídas com o novo recurso, dependendo da configuração do recurso para cada recurso. Se as configurações de diagnóstico estiverem incluídas no novo recurso, isso retomará a coleção de logs de recursos conforme definido na configuração de diagnóstico e enviará a métrica aplicável e os dados de log para o destino configurado anteriormente.

Além disso, é uma boa prática excluir as configurações de diagnóstico de um recurso que você vai excluir e não planeja usar novamente para manter seu ambiente limpo.

Criar configurações de diagnóstico

Aqui, percorremos o processo de criação de configurações de diagnóstico para sua conta.

Observação

No momento, não há suporte para a métrica de exportação de registros como uma categoria.

Portal do Azure

1. Entre no portal do Azure.

2. Navegue até sua conta existente do Azure Cosmos DB.

3. Na seção Monitoramento do menu de recursos, selecione Configurações de Diagnóstico. Em seguida, selecione a opção Adicionar configuração de diagnóstico.

   

   Importante

   Talvez seja exibida uma solicitação para "habilitar a consulta de texto completo [...] para logs mais detalhados" se o recurso consulta de texto completo não estiver habilitado na sua conta. Você pode ignorar esse aviso com segurança se não quiser habilitar esse recurso. Para obter mais informações, consulte habilitar consulta de texto completo.

4. No painel Configurações de diagnóstico, nomeie a configuração como example-setting e, em seguida, selecione a categoria QueryRuntimeStatistics. Habilite a caixa de seleção Enviar para o Workspace do Log Analytics, selecionando seu workspace existente. Finalmente, selecione Recurso específico como a opção de destino.

   

CLI do Azure

Use o comando az monitor diagnostic-settings create para criar uma configuração de diagnóstico com a CLI do Azure. Confira a documentação desse comando para obter descrições de seus parâmetros.

1. Verifique se você fez logon na CLI do Azure. Para obter mais informações, consulte Entrar com a CLI do Azure.

2. Use az monitor diagnostic-settings create para criar a configuração.

   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
       }
     ]'
   

   Importante

   Este exemplo usa o argumento --export-to-resource-specific para habilitar tabelas específicas de recursos.

3. Analise os resultados da criação da sua nova configuração usando 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 a API REST do Azure Monitor para criar uma configuração de diagnóstico por meio do console interativo.

1. Verifique se você fez logon na CLI do Azure. Para obter mais informações, consulte Entrar com a CLI do Azure.

2. Crie a configuração de diagnóstico para seu recurso do Azure Cosmos DB usando uma solicitação HTTP PUT e 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"
       }
     }'
   

   Importante

   Esse exemplo define a propriedade logAnalyticsDestinationType como Dedicated para habilitar tabelas específicas do recurso.

3. Use az rest novamente com um verbo HTTP GET para obter as propriedades da configuração de diagnóstico.

   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 um modelo do Bicep para criar a configuração de diagnóstico.

1. Verifique se você fez logon na CLI do Azure. Para obter mais informações, consulte Entrar com a CLI do Azure.

2. Crie um arquivo chamado diagnosticSetting.bicep.

3. Insira o seguinte conteúdo do modelo Bicep que implanta a configuração de diagnóstico para seu recurso do Azure Cosmos DB.

   @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
         }
       ]
     }
   }    
   

   Importante

   Esse exemplo define a propriedade logAnalyticsDestinationType como Dedicated para habilitar tabelas específicas do recurso.

4. Implante o modelo usando 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>"
   

   Dica

   Use o comando az bicep build para converter o modelo do Bicep em um modelo do Azure Resource Manager.

Modelo do ARM

Use um modelo do Azure Resource Manager para criar a configuração de diagnóstico.

1. Verifique se você fez logon na CLI do Azure. Para obter mais informações, consulte Entrar com a CLI do Azure.

2. Crie um arquivo chamado diagnosticSetting.bicep.

3. Insira o seguinte conteúdo do modelo do Azure Resource Manager que implanta a configuração de diagnóstico para o seu recurso do Azure Cosmos DB.

   {
     "$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
             }
           ]
         }
       }
     ]
   }
   

   Importante

   Esse exemplo define a propriedade logAnalyticsDestinationType como Dedicated para habilitar tabelas específicas do recurso.

4. Implante o modelo usando 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>"
   

   Dica

   Use o comando az bicep decompile para converter o modelo do Azure Resource Manager em um modelo do Bicep.

Habilitar a consulta de texto completo para registrar o texto da consulta

O Azure Cosmos DB oferece registro em log avançado para solução de problemas detalhada. Ao habilitar a consulta de texto completo, você pode exibir a consulta desofuscada para todas as solicitações na sua conta do Azure Cosmos DB. Você também dá permissão para que o Azure Cosmos DB acesse e exiba esses dados em seus logs.

Aviso

A habilitação desse recurso pode resultar em custos de log adicionais, para detalhes de preços, visite Preços do Azure Monitor. É recomendável desabilitar esse recurso após a solução de problemas.

Portal do Azure

1. Na página da conta existente do Azure Cosmos DB, selecione a opção Recursos na seção Configurações do menu de recursos. Em seguida, selecione o recurso Consulta de texto completo de diagnósticos.

   

2. Na caixa de diálogo, selecione Enable. Essa configuração será aplicada em alguns minutos. Todos os logs recém-ingeridos agora têm o texto completo ou o texto PIICommand de cada solicitação.

   

CLI do Azure / API REST / Bicep / Modelo do ARM

Use a CLI do Azure para habilitar a consulta de texto completo para sua conta do Azure Cosmos DB.

1. Habilite a consulta de texto completo usando az rest novamente com um verbo HTTP PATCH e um payload JSON.

   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. Aguarde alguns minutos até que a operação seja concluída. Verifique o status da consulta de texto completo usando az rest novamente com 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}"
   

   A saída deve ser semelhante a este exemplo.

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

Conteúdo relacionado

• Consultas de diagnóstico na API para NoSQL
• Consultas de diagnóstico na API para MongoDB
• Consultas de diagnóstico na API para Apache Cassandra