Monitore dados do Azure Cosmos DB usando configurações de diagnóstico no Azure

Artigo
02/17/2024

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 de 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.

As métricas de plataforma e o log de atividades são coletados automaticamente, porém, você precisa criar uma configuração de diagnóstico para coletar logs de recursos ou encaminhá-los para fora do Azure Monitor. Você pode ativar a configuração de diagnóstico para as contas do Azure Cosmos DB e enviar logs de recursos para as seguintes fontes:

Workspaces do Log Analytics
- Os dados enviados para o Log Analytics podem ser gravados em Diagnóstico do Azure (herdado) ou em tabelas específicas do Recurso (versão prévia)
Hub de Eventos
Conta de Armazenamento

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 de criação da configuração de diagnóstico por meio da 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.

Criar configurações de diagnóstico

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

Entre no portal do Azure.
Navegue até a conta do Azure Cosmos DB. Abra o painel Configurações de diagnóstico na seção Monitoramento e 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.

No painel Configurações de diagnóstico, preencha o formulário com suas categorias de preferência. Aqui está inclusa uma lista de categorias de log.

Categoria	API	Definição	Propriedades da chave
DataPlaneRequests	Recomendado para API para NoSQL	Registra solicitações de back-end como operações de plano de dados que são solicitações executadas para criar, atualizar, excluir ou recuperar dados dentro da conta.	`Requestcharge`, `statusCode`, `clientIPaddress`, `partitionID`, `resourceTokenPermissionIdresourceTokenPermissionMode`
MongoRequests	API para MongoDB	Registra as solicitações iniciadas pelo usuário por meio do front-end para realizar solicitações ao Azure Cosmos DB for MongoDB. Ao habilitar essa categoria, desabilite o DataPlaneRequests.	`Requestcharge`, `opCode`, `retryCount`, `piiCommandText`
CassandraRequests	API para Apache Cassandra	Registra as solicitações iniciadas pelo usuário por meio do front-end para realizar solicitações ao Azure Cosmos DB for Cassandra.	`operationName`, `requestCharge`, `piiCommandText`
GremlinRequests	API para Apache Gremlin	Registra as solicitações iniciadas pelo usuário por meio do front-end para realizar solicitações ao Azure Cosmos DB for Gremlin.	`operationName`, `requestCharge`, `piiCommandText`, `retriedDueToRateLimiting`
QueryRuntimeStatistics	API para NoSQL	Esta tabela detalha as operações de consulta executadas em uma conta da API de NoSQL. Por padrão, o texto da consulta e seus parâmetros são ofuscados para evitarem o registro de dados pessoais com o registro de consulta de texto completo disponível mediante solicitação.	`databasename`, `partitionkeyrangeid`, `querytext`
PartitionKeyStatistics	Todas as APIs	Registra as estatísticas de chaves de partição lógicas representando o tamanho de armazenamento (KB) estimado das chaves de partição. Essa tabela é útil ao solucionar problemas de distorções de armazenamento. Esse log PartitionKeyStatistics só será emitido se as seguintes condições forem verdadeiras: 1. Pelo menos 1% dos documentos na partição física têm a mesma chave de partição lógica. 2. De todas as chaves na partição física, o registro PartitionKeyStatistics captura as três principais chaves com maior tamanho de armazenamento. Se as condições anteriores não forem atendidas, os dados de estatísticas da chave de partição não estarão disponíveis. Não há problema se as condições acima não forem atendidas para sua conta, o que normalmente indica que você não tem distorção de armazenamento de partição lógica. Observação: o tamanho estimado das chaves de partição é calculado usando uma abordagem de amostragem que pressupõe que os documentos na partição física têm aproximadamente o mesmo tamanho. Se os dimensionamentos dos documentos não forem uniformes na partição física, o tamanho estimado da chave de partição poderá não ser preciso.	`subscriptionId`, `regionName`, `partitionKey`, `sizeKB`
PartitionKeyRUConsumption	API para NoSQL ou API para Apache Gremlin	Registra o consumo agregado de RU/s por segundo de chaves de partição. Esta tabela é útil para solucionar problemas de partições mais acessadas. Atualmente, o Azure Cosmos DB informa chaves de partição apenas para contas da API de NoSQL e para operações de leitura/gravação, consulta e de procedimento armazenado.	`subscriptionId`, `regionName`, `partitionKey`, `requestCharge`, `partitionKeyRangeId`
ControlPlaneRequests	Todas as APIs	Registra detalhes em operações do plano de controle, o que inclui: criar uma conta, adicionar ou remover uma região, atualizar configurações de replicação de conta etc.	`operationName`, `httpstatusCode`, `httpMethod`, `region`
TableApiRequests	API para Tabela	Registra as solicitações iniciadas pelo usuário por meio do front-end para realizar solicitações ao Azure Cosmos DB for Table.	`operationName`, `requestCharge`, `piiCommandText`

Depois de escolher os Detalhes de categorias, envie seus logs para o destino preferencial. Se você estiver enviando logs para um Workspace do Log Analytics, escolha Específico do recurso como a tabela de destino.

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.

Observação

No caso da API de NoSQL, recomenda-se definir a propriedade export-to-resource-specific como true.

Crie variáveis shell para subscriptionId, diagnosticSettingName, workspaceName e resourceGroupName.

# Variable for subscription id
subscriptionId="<subscription-id>"

# Variable for resource group name
resourceGroupName="<resource-group-name>"

# Variable for workspace name
workspaceName="<workspace-name>"

# Variable for diagnostic setting name
diagnosticSettingName="<diagnostic-setting-name>"

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

az monitor diagnostic-settings create \
    --resource "/subscriptions/$subscriptionId/resourceGroups/$resourceGroupName/providers/Microsoft.DocumentDb/databaseAccounts/" \
    --name $diagnosticSettingName \
    --export-to-resource-specific true \
    --logs '[{"category": "QueryRuntimeStatistics","categoryGroup": null,"enabled": true,"retentionPolicy": {"enabled": false,"days": 0}}]' \
    --workspace "/subscriptions/$subscriptionId/resourcegroups/$resourceGroupName/providers/microsoft.operationalinsights/workspaces/$workspaceName"

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

Observação

Recomendamos definir a propriedade logAnalyticsDestinationType como Dedicada para habilitar tabelas específicas do recurso.

Criar uma solicitação PUT HTTP.

PUT
https://management.azure.com/{resource-id}/providers/microsoft.insights/diagnosticSettings/service?api-version={api-version}

Use estes cabeçalhos com a solicitação.

Parâmetros/Cabeçalhos	Valor/Descrição
name	O nome da configuração de diagnóstico.
resourceUri	URI de sub-recursos do Microsoft Insights para a conta do Azure Cosmos DB.
api-version	`2017-05-01-preview`
Content-Type	`application/json`

Observação

O URI para o sub-recurso do Microsoft Insights está neste formato: subscriptions/{SUBSCRIPTION_ID}/resourceGroups/{RESOURCE_GROUP}/providers/Microsoft.DocumentDb/databaseAccounts/{ACCOUNT_NAME}/providers/microsoft.insights/diagnosticSettings/{DIAGNOSTIC_SETTING_NAME}. Para obter mais informações sobre URIs de recurso do Azure Cosmos DB, consulte sintaxe de URI de recurso para a API REST do Azure Cosmos DB.

Defina o corpo da solicitação para esse conteúdo JSON.

{
    "id": "/subscriptions/{SUBSCRIPTION_ID}/resourceGroups/{RESOURCE_GROUP}/providers/Microsoft.DocumentDb/databaseAccounts/{ACCOUNT_NAME}/providers/microsoft.insights/diagnosticSettings/{DIAGNOSTIC_SETTING_NAME}",
    "type": "Microsoft.Insights/diagnosticSettings",
    "name": "name",
    "location": null,
    "kind": null,
    "tags": null,
    "properties": {
        "storageAccountId": null,
        "serviceBusRuleId": null,
        "workspaceId": "/subscriptions/{SUBSCRIPTION_ID}/resourcegroups/{RESOURCE_GROUP}/providers/microsoft.operationalinsights/workspaces/{WORKSPACE_NAME}",
        "eventHubAuthorizationRuleId": null,
        "eventHubName": null,
        "logs": [
            {
                "category": "DataPlaneRequests",
                "categoryGroup": null,
                "enabled": true,
                "retentionPolicy": {
                    "enabled": false,
                    "days": 0
                }
            },
            {
                "category": "QueryRuntimeStatistics",
                "categoryGroup": null,
                "enabled": true,
                "retentionPolicy": {
                    "enabled": false,
                    "days": 0
                }
            },
            {
                "category": "PartitionKeyStatistics",
                "categoryGroup": null,
                "enabled": true,
                "retentionPolicy": {
                    "enabled": false,
                    "days": 0
                }
            },
            {
                "category": "PartitionKeyRUConsumption",
                "categoryGroup": null,
                "enabled": true,
                "retentionPolicy": {
                    "enabled": false,
                    "days": 0
                }
            },
            {
                "category": "ControlPlaneRequests",
                "categoryGroup": null,
                "enabled": true,
                "retentionPolicy": {
                    "enabled": false,
                    "days": 0
                }
            }
        ],
        "logAnalyticsDestinationType": "Dedicated"
    },
    "identity": null
}

Aqui, use um modelo do ARM (Azure Resource Manager) para criar uma configuração de diagnóstico.

Observação

Defina a propriedade logAnalyticsDestinationType como Dedicada para habilitar tabelas específicas de recursos.

Crie o arquivo de modelo JSON a seguir para implantar configurações de diagnóstico para o recurso do Azure Cosmos DB.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "settingName": {
      "type": "string",
      "metadata": {
        "description": "The name of the diagnostic setting."
      }
    },
    "dbName": {
      "type": "string",
      "metadata": {
        "description": "The name of the database."
      }
    },
    "workspaceId": {
      "type": "string",
      "metadata": {
        "description": "The resource Id of the workspace."
      }
    },
    "storageAccountId": {
      "type": "string",
      "metadata": {
        "description": "The resource Id of the storage account."
      }
    },
    "eventHubAuthorizationRuleId": {
      "type": "string",
      "metadata": {
        "description": "The resource Id of the event hub authorization rule."
      }
    },
    "eventHubName": {
      "type": "string",
      "metadata": {
        "description": "The name of the event hub."
      }
    }
  },
  "resources": [
    {
      "type": "Microsoft.Insights/diagnosticSettings",
      "apiVersion": "2021-05-01-preview",
      "scope": "[format('Microsoft.DocumentDB/databaseAccounts/{0}', parameters('dbName'))]",
      "name": "[parameters('settingName')]",
      "properties": {
        "workspaceId": "[parameters('workspaceId')]",
        "storageAccountId": "[parameters('storageAccountId')]",
        "eventHubAuthorizationRuleId": "[parameters('eventHubAuthorizationRuleId')]",
        "eventHubName": "[parameters('eventHubName')]",
        "logAnalyticsDestinationType": "[parameters('logAnalyticsDestinationType')]",
        "logs": [
          {
            "category": "DataPlaneRequests",
            "categoryGroup": null,
            "enabled": true,
            "retentionPolicy": {
              "days": 0,
              "enabled": false
            }
          },
          {
            "category": "MongoRequests",
            "categoryGroup": null,
            "enabled": false,
            "retentionPolicy": {
              "days": 0,
              "enabled": false
            }
          },
          {
            "category": "QueryRuntimeStatistics",
            "categoryGroup": null,
            "enabled": true,
            "retentionPolicy": {
              "days": 0,
              "enabled": false
            }
          },
          {
            "category": "PartitionKeyStatistics",
            "categoryGroup": null,
            "enabled": true,
            "retentionPolicy": {
              "days": 0,
              "enabled": false
            }
          },
          {
            "category": "PartitionKeyRUConsumption",
            "categoryGroup": null,
            "enabled": true,
            "retentionPolicy": {
              "days": 0,
              "enabled": false
            }
          },
          {
            "category": "ControlPlaneRequests",
            "categoryGroup": null,
            "enabled": true,
            "retentionPolicy": {
              "days": 0,
              "enabled": false
            }
          },
          {
            "category": "CassandraRequests",
            "categoryGroup": null,
            "enabled": false,
            "retentionPolicy": {
              "days": 0,
              "enabled": false
            }
          },
          {
            "category": "GremlinRequests",
            "categoryGroup": null,
            "enabled": false,
            "retentionPolicy": {
              "days": 0,
              "enabled": false
            }
          },
          {
            "category": "TableApiRequests",
            "categoryGroup": null,
            "enabled": false,
            "retentionPolicy": {
              "days": 0,
              "enabled": false
            }
          }
        ],
        "metrics": [
          {
            "timeGrain": null,
            "enabled": false,
            "retentionPolicy": {
              "days": 0,
              "enabled": false
            },
            "category": "Requests"
          }
        ]
      }
    }
  ]
}

Crie o arquivo de parâmetro JSON a seguir com as configurações apropriadas para o recurso do Azure Cosmos DB.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "settingName": {
      "value": "{DIAGNOSTIC_SETTING_NAME}"
    },
    "dbName": {
      "value": "{ACCOUNT_NAME}"
    },
    "workspaceId": {
      "value": "/subscriptions/{SUBSCRIPTION_ID}/resourcegroups/{RESOURCE_GROUP}/providers/microsoft.operationalinsights/workspaces/{WORKSPACE_NAME}"
    },
    "storageAccountId": {
      "value": "/subscriptions/{SUBSCRIPTION_ID}/resourceGroups/{RESOURCE_GROUP}/providers/Microsoft.Storage/storageAccounts/{STORAGE_ACCOUNT_NAME}"
    },
    "eventHubAuthorizationRuleId": {
      "value": "/subscriptions/{SUBSCRIPTION_ID}/resourcegroups{RESOURCE_GROUP}/providers/Microsoft.EventHub/namespaces/{EVENTHUB_NAMESPACE}/authorizationrules/{EVENTHUB_POLICY_NAME}"
    },
    "eventHubName": {
      "value": "{EVENTHUB_NAME}"
    },
    "logAnalyticsDestinationType": {
      "value": "Dedicated"
    }
  }
}

Implante o modelo usando az deployment group create.

az deployment group create \
    --resource-group <resource-group-name> \
    --template-file <path-to-template>.json \
    --parameters @<parameters-file-name>.json

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

Observação

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.

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.

Azure portal
Modelo da CLI do Azure/API REST/ARM

Para habilitar esse recurso, acesse a página Features na conta do Azure Cosmos DB.
Selecione Enable. Essa configuração será aplicada em alguns minutos. Todos os logs recém ingeridos têm o texto completo ou o texto PIICommand para cada solicitação.

Verifique se você está conectado à CLI do Azure. Para obter mais informações, consulte Entrar com a CLI do Azure. Opcionalmente, verifique se você configurou a assinatura ativa para sua CLI. Para saber mais, confira Alterar a assinatura ativa da CLI do Azure.

Crie variáveis shell para accountName e resourceGroupName.

# Variable for resource group name
resourceGroupName="<resource-group-name>"

# Variable for account name
accountName="<account-name>"

Obtenha o identificador exclusivo para sua conta existente usando az show.

az cosmosdb show \
    --resource-group $resourceGroupName \
    --name $accountName \
    --query id

Armazene o identificador exclusivo em uma variável shell nomeada como $uri.

uri=$(
    az cosmosdb show \
        --resource-group $resourceGroupName \
        --name $accountName \
        --query id \
        --output tsv
)

Consulte o recurso usando a API REST e az rest com um verbo HTTP GET para verificar se a consulta de texto completo já foi habilitada.

az rest \
    --method GET \
    --uri "https://management.azure.com/$uri/?api-version=2021-05-01-preview" \
    --query "{accountName:name,fullTextQuery:{state:properties.diagnosticLogSettings.enableFullTextQuery}}"

Se a consulta de texto completo não estiver habilitada, a saída será semelhante a este exemplo.

{
  "accountName": "<account-name>",
  "fullTextQuery": {
    "state": "None"
  }
}

Se a consulta de texto completo ainda não estiver habilitada, habilite-a usando az rest novamente com um verbo PATCH HTTP e um conteúdo JSON.
```
az rest \
    --method PATCH \
    --uri "https://management.azure.com/$uri/?api-version=2021-05-01-preview" \
    --body '{"properties": {"diagnosticLogSettings": {"enableFullTextQuery": "True"}}}'
```
Observação

Se você estiver usando a CLI do Azure em um prompt do PowerShell, precisará escapar das aspas duplas usando um caractere de barra invertida (\).

Aguarde alguns minutos até que a operação seja concluída. Verifique o status da consulta de texto completo usando az rest novamente.

az rest \
    --method GET \
    --uri "https://management.azure.com/$uri/?api-version=2021-05-01-preview" \
    --query "{accountName:name,fullTextQuery:{state:properties.diagnosticLogSettings.enableFullTextQuery}}"

A saída deve ser semelhante a este exemplo.

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

Consultar dados

Para saber como consultar usando esses recursos recém-habilitados, confira:

Próximas etapas

Monitoramento da referência de dados do Azure Cosmos DB

Monitore dados do Azure Cosmos DB usando configurações de diagnóstico no Azure

Pré-requisitos

Criar configurações de diagnóstico

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

Consultar dados

Próximas etapas

Recursos adicionais