Supervisión de datos de Azure Cosmos DB mediante la configuración de diagnóstico de Log Analytics de Azure Monitor

SE APLICA A: NoSQL MongoDB Cassandra Gremlin Table

La configuración de diagnóstico de Azure se usa para recopilar los registros de los recursos. Los recursos emiten registros de recursos de Azure y proporcionan datos abundantes y frecuentes sobre el funcionamiento de ese recurso. Estos registros se capturan por solicitud y también se denominan registros de plano de datos. Algunos ejemplos de las operaciones del plano de datos son Delete, Insert y ReadFeed. El contenido de estos registros varía según el tipo de recurso.

Para más información sobre la configuración de diagnóstico, consulte Configuración de diagnóstico en Azure Monitor.

Nota:

Se recomienda crear la configuración de diagnóstico en modo específico del recurso (para todas las API excepto la API para Tabla) siguiendo las instrucciones de la pestaña API de REST. Esta opción proporciona optimizaciones de costos adicionales con una vista mejorada para controlar los datos.

Requisitos previos

• Una cuenta existente de Azure Cosmos DB.
  • Si tiene una suscripción de Azure, cree una nueva cuenta.
  • Si no tiene una suscripción a Azure, cree una cuenta gratuita antes de empezar.
  • Como alternativa, puede probar Azure Cosmos DB gratis antes de confirmarlo.
• Un área de trabajo de Log Analytics de Azure Monitor existente.

Advertencia

Si necesita eliminar un recurso, renombrarlo, moverlo o migrarlo entre grupos de recursos o suscripciones, primero debe eliminar su configuración de diagnóstico. De lo contrario, si vuelve a crear este recurso, la configuración de diagnóstico del recurso eliminado podría incluirse con el nuevo recurso, en función de la configuración del recurso para cada recurso. Si la configuración de diagnóstico se incluye con el nuevo recurso, se reanuda la recopilación de registros de recursos tal y como se define en la configuración de diagnóstico y envía los datos de métrica y registro aplicables al destino configurado anteriormente.

Además, se recomienda eliminar la configuración de diagnóstico de un recurso que vaya a eliminar y no planear usarla de nuevo con el fin de mantener limpio el entorno.

Crear configuraciones de diagnóstico

Aquí se explica el proceso de creación de la configuración de diagnóstico para su cuenta.

Nota:

La métrica para la exportación de registros como categoría no se admite actualmente.

Azure Portal

1. Inicie sesión en Azure Portal.

2. Vaya a la cuenta de Azure Cosmos DB existente.

3. En la sección Supervisión del menú de recursos, seleccione Configuración de diagnóstico. A continuación, seleccione la opción Agregar configuración de diagnóstico.

   

   Importante

   Es posible que vea un mensaje para "habilitar la consulta de texto [...] para un registro más detallado" si la característica de consulta de texto completo no está habilitada en su cuenta. Puede omitir esta advertencia de forma segura si no desea habilitar esta característica. Para obtener más información, consulte Habilitar la consulta de texto.

4. En el panel Configuración de diagnóstico, asigne un nombre a la configuración de ejemplo y a continuación, seleccione la categoría QueryRuntimeStatistics. Active la casilla Enviar al área de trabajo de Log Analytics y seleccione el área de trabajo existente. Por último, seleccione Recursos específicos como opción de destino.

   

CLI de Azure

Use el comando az monitor diagnostic-settings create para crear una configuración de diagnóstico con la CLI de Azure. Consulte la documentación de este comando para las descripciones de sus parámetros.

1. Asegúrese de iniciar sesión en la CLI de Azure. Para obtener más información, consulte Inicio de sesión con la CLI de Azure.

2. Use az monitor diagnostic-settings create para crear el valor.

   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

   En este ejemplo se usa el argumento --export-to-resource-specific para habilitar tablas específicas del recurso.

3. Revise los resultados de la creación de la nueva configuración mediante 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 la API REST de Azure Monitor para crear una configuración de diagnóstico a través de la consola interactiva.

1. Asegúrese de iniciar sesión en la CLI de Azure. Para obtener más información, consulte Inicio de sesión con la CLI de Azure.

2. Cree la configuración de diagnóstico para el recurso de Azure Cosmos DB mediante una solicitud de PUT HTTP y 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

   En este ejemplo se establece la propiedad logAnalyticsDestinationType en Dedicated para habilitar tablas específicas de recursos.

3. Use az rest de nuevo con un verbo HTTP GET para obtener las propiedades de la configuración 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 una Plantilla de Bicep para crear la configuración de diagnóstico.

1. Asegúrese de iniciar sesión en la CLI de Azure. Para obtener más información, consulte Inicio de sesión con la CLI de Azure.

2. Cree un nuevo archivo llamado diagnosticSetting.bicep.

3. Escriba el siguiente contenido de plantilla de Bicep que implementa la configuración de diagnóstico para el recurso de 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

   En este ejemplo se establece la propiedad logAnalyticsDestinationType en Dedicated para habilitar tablas específicas de recursos.

4. Implemente la plantilla con 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>"
   

   Sugerencia

   Use el comando az bicep build para convertir la plantilla de Bicep en una plantilla de Azure Resource Manager.

Plantilla de ARM

Use una Plantilla de Azure Resource Manager para crear la configuración de diagnóstico.

1. Asegúrese de iniciar sesión en la CLI de Azure. Para obtener más información, consulte Inicio de sesión con la CLI de Azure.

2. Cree un nuevo archivo llamado diagnosticSetting.bicep.

3. Escriba el siguiente contenido de plantilla de Azure Resource Manager que implementa la configuración de diagnóstico para el recurso de 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

   En este ejemplo se establece la propiedad logAnalyticsDestinationType en Dedicated para habilitar tablas específicas de recursos.

4. Implemente la plantilla con 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>"
   

   Sugerencia

   Use el comando az bicep decompile para convertir la plantilla de Azure Resource Manager en una plantilla de Bicep.

Habilitación de la consulta de texto completo para registrar texto de consulta

Azure Cosmos DB proporciona un registro avanzado para una solución de problemas detallada. Al habilitar la consulta de texto completo, puedes ver la consulta desofuscada para todas las solicitudes dentro de la cuenta de Azure Cosmos DB. También concedes permiso para que Azure Cosmos DB acceda a estos datos y los presente en los registros.

Advertencia

La habilitación de esta característica puede dar lugar a costos de registro adicionales; para obtener más información sobre los precios, visite Precios de Azure Monitor. Se recomienda deshabilitar esta característica después de solucionar los problemas.

Azure Portal

1. En la página de la cuenta de Azure Cosmos DB existente, seleccione la opción Características en la sección Configuración del menú de recursos. A continuación, seleccione la característica Consulta de texto completo de diagnóstico.

   

2. En el cuadro de diálogo, seleccione Enable. Esta configuración se aplica en unos minutos. Todos los registros recién ingeridos ahora tienen el texto completo o PIICommand para cada solicitud.

   

CLI de Azure / API de REST/ Bicep /Plantilla de ARM

Use la CLI de Azure para habilitar la consulta de texto completo para la cuenta de Azure Cosmos DB.

1. Habilite la consulta de texto completo mediante az rest otra vez con un verbo HTTP PATCH y una carga 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. Espere unos minutos a que se complete la operación. Compruebe de nuevo el estado de la consulta de texto completo mediante az rest con 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}"
   

   La salida debe ser similar a la del ejemplo siguiente.

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

Contenido relacionado

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