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

APLICA-SE A: NoSQL MongoDB Cassandra Gremlin Tabela

As definições de diagnóstico no Azure são utilizadas para recolher registos de recursos. Os recursos emitem Logs de Recursos do Azure e fornecem dados ricos e frequentes sobre a operação desse recurso. Esses logs são capturados por solicitação e também são chamados de logs de plano de dados. Alguns exemplos das operações do plano de dados incluem excluir, inserir e readFeed. O conteúdo destes registos varia consoante o tipo de recurso.

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

Nota

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

Pré-requisitos

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

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 para o 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 forem incluídas com o novo recurso, isso retomará a coleta 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 as definições de diagnóstico

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

Nota

A métrica para a exportação de logs como uma categoria não é suportada no momento.

Portal do Azure

1. Inicie sessão 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

   Você pode ver um prompt para "ativar consulta de texto completo [...] para registo mais detalhado" se a funcionalidade de consulta de texto completo não estiver ativada na sua conta. Pode ignorar este aviso com segurança se não pretender ativar esta funcionalidade. Para obter mais informações, consulte habilitar consulta de texto completo.

4. No painel Configurações de diagnóstico , nomeie a configuração como exemplo e selecione a categoria QueryRuntimeStatistics . Habilite a caixa de seleção Enviar para o espaço de trabalho do Log Analytics, selecionando seu espaço de trabalho existente. Por fim, selecione Específico do recurso como a opção de destino.

   

CLI do Azure

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

1. Certifique-se de que iniciou sessão 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 --export-to-resource-specific argumento para habilitar tabelas específicas de recursos.

3. Analise os resultados da criação da nova configuração usando az monitor diagnostics-settings showo .

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

API REST

Use a API REST do Azure Monitor para criar uma configuração de diagnóstico por meio do console interativo.

1. Certifique-se de que iniciou sessão 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

   Este exemplo define a logAnalyticsDestinationType propriedade como Dedicated para habilitar tabelas específicas de recursos.

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

1. Certifique-se de que iniciou sessão na CLI do Azure. Para obter mais informações, consulte Entrar com a CLI do Azure.

2. Crie um novo ficheiro com o nome 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

   Este exemplo define a logAnalyticsDestinationType propriedade como Dedicated para habilitar tabelas específicas de recursos.

4. Implante o modelo usando az deployment group createo .

   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>"
   

   Gorjeta

   Use o az bicep build comando para converter o modelo 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. Certifique-se de que iniciou sessão na CLI do Azure. Para obter mais informações, consulte Entrar com a CLI do Azure.

2. Crie um novo ficheiro com o nome diagnosticSetting.bicep.

3. Insira o seguinte conteúdo de modelo do Azure Resource Manager que implanta a configuração de diagnóstico para 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

   Este exemplo define a logAnalyticsDestinationType propriedade como Dedicated para habilitar tabelas específicas de recursos.

4. Implante o modelo usando az deployment group createo .

   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>"
   

   Gorjeta

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

Habilitar consulta de texto completo para registrar texto de consulta

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

Aviso

Habilitar esse recurso pode resultar em custos adicionais de log, para obter detalhes de preços, visite os preços do Azure Monitor. Recomenda-se desativar esse recurso após a solução de problemas.

Portal do Azure

1. Na página de 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 de consulta de texto completo Diagnóstico.

   

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

   

Azure CLI / REST API / Bicep / Modelo 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 uma carga JSON útil.

   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údos relacionados

• 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