Supervisión de datos de Azure Cosmos DB mediante la configuración de diagnóstico en Azure

Artículo
02/16/2024

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.

Las métricas de la plataforma y el registro de actividad se recopilan automáticamente, mientras que debe crear una configuración de diagnóstico para recopilar registros de recursos o reenviarlos fuera de Azure Monitor. Puede activar la configuración de diagnóstico para las cuentas de Azure Cosmos DB y enviar registros de recursos a los siguientes orígenes:

Áreas de trabajo de Log Analytics
- Los datos enviados a Log Analytics se pueden escribir en tablas de Azure Diagnostics (heredadas) o específicas del recurso (versión preliminar) .
Centro de eventos
Cuenta de almacenamiento

Nota

Se recomienda crear la configuración de diagnóstico en modo específico del recurso (para todas las API excepto la API para Table) de acuerdo con nuestras instrucciones para crear la configuración de diagnóstico a través de la 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.

Crear configuraciones de diagnóstico

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

Inicie sesión en Azure Portal.
Vaya a la cuenta de Azure Cosmos DB. Abra el panel Configuración de diagnóstico en la sección de supervisión y, después, 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.

En el panel Configuración de diagnóstico, rellene el formulario con las categorías que prefiera. Aquí se incluye una lista de categorías de registro.

Categoría	API	Definición	Propiedades clave
DataPlaneRequests	Recomendado para API para NoSQL	Registra las solicitudes de back-end como operaciones del plano de datos, que son solicitudes ejecutadas para crear, actualizar, eliminar o recuperar datos dentro de la cuenta.	`Requestcharge`, `statusCode`, `clientIPaddress`, `partitionID`, `resourceTokenPermissionId`, `resourceTokenPermissionMode`
MongoRequests	API para MongoDB	Registra las solicitudes iniciadas por el usuario desde el servidor front-end con el fin de atender solicitudes de Azure Cosmos DB for MongoDB. Al habilitar esta categoría, asegúrese de deshabilitar DataPlaneRequests.	`Requestcharge`, `opCode`, `retryCount`, `piiCommandText`
CassandraRequests	API para Apache Cassandra	Registra las solicitudes iniciadas por el usuario desde el servidor front-end con el fin de atender solicitudes de Azure Cosmos DB for Cassandra.	`operationName`, `requestCharge`, `piiCommandText`
GremlinRequests	API para Apache Gremlin	Registra las solicitudes iniciadas por el usuario desde el servidor front-end con el fin de atender solicitudes de Azure Cosmos DB for Gremlin.	`operationName`, `requestCharge`, `piiCommandText`, `retriedDueToRateLimiting`
QueryRuntimeStatistics	API para NoSQL	En esta tabla se detallan las operaciones de consulta ejecutadas en una cuenta de la API para NoSQL. De forma predeterminada, el texto de la consulta y sus parámetros se ofuscan para evitar el registro de datos personales con el registro de consultas de texto completo disponible por solicitud.	`databasename`, `partitionkeyrangeid`, `querytext`
PartitionKeyStatistics	Todas las API	Registra las estadísticas de las claves de partición lógicas mediante la representación del tamaño de almacenamiento estimado (KB) de las claves de partición. Esta tabla es útil al solucionar problemas de sesgos de almacenamiento. El registro PartitionKeyStatistics solo se emite si se cumplen las condiciones siguientes: 1. Al menos el 1 % de los documentos de la partición física tienen la misma clave de partición lógica. 2. De todas las claves en la partición física, el registro de PartitionKeyStatistics captura las tres claves principales con el mayor tamaño de almacenamiento. Si no se cumplen las condiciones anteriores, los datos estadísticos de las claves de partición no están disponibles. No importa si su cuenta no cumple las condiciones anteriores; esto suele indicar que no tiene asimetría de almacenamiento de las particiones lógicas. Nota: El tamaño estimado de las claves de partición se calcula mediante un enfoque de muestreo que da por hecho que los documentos de la partición física tienen aproximadamente el mismo tamaño. Si los tamaños de los documentos no son uniformes en la partición física, es posible que el tamaño estimado de las claves de partición no sea preciso.	`subscriptionId`, `regionName`, `partitionKey`, `sizeKB`
PartitionKeyRUConsumption	API para NoSQL o API para Apache Gremlin	Registra el consumo agregado de RU por segundo de las claves de partición. Esta tabla es útil para solucionar problemas de particiones activas. Actualmente, Azure Cosmos DB solo informa de las claves de partición para las cuentas de la API para NoSQL y para las operaciones de lectura o escritura, consulta y procedimientos almacenados.	`subscriptionId`, `regionName`, `partitionKey`, `requestCharge`, `partitionKeyRangeId`
ControlPlaneRequests	Todas las API	Registra detalles sobre las operaciones del panel de control, tales como la creación de una cuenta, la adición o eliminación de una región, la actualización de la configuración de replicación de la cuenta, etc.	`operationName`, `httpstatusCode`, `httpMethod`, `region`
TableApiRequests	API para Table	Registra las solicitudes iniciadas por el usuario desde el servidor front-end con el fin de atender solicitudes de Azure Cosmos DB for Table.	`operationName`, `requestCharge`, `piiCommandText`

Una vez que seleccione los detalles de las categorías, envíe los registros al destino que prefiera. Si va a enviar los registros a un Área de trabajo de Log Analytics, asegúrese de seleccionar Específico del recurso como tabla de destino.

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.

Nota:

Si usa la API para NoSQL, se recomienda establecer la propiedad export-to-resource-specific en true.

Cree variables de shell para subscriptionId, diagnosticSettingName, workspaceName y 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 crear el valor.

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

Nota:

Se recomienda establecer la propiedad logAnalyticsDestinationType en Dedicated para habilitar tablas específicas de recursos.

Creación de una solicitud PUT HTTP.

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

Use estos encabezados con la solicitud.

Parámetros y encabezados	Valor y descripción
name	El nombre de la configuración de diagnóstico.
resourceUri	URI del subrecurso de Microsoft Insights para la cuenta de Azure Cosmos DB.
api-version	`2017-05-01-preview`
Content-Type	`application/json`

Nota

El URI del subrecurso de Microsoft Insights tiene este formato: subscriptions/{SUBSCRIPTION_ID}/resourceGroups/{RESOURCE_GROUP}/providers/Microsoft.DocumentDb/databaseAccounts/{ACCOUNT_NAME}/providers/microsoft.insights/diagnosticSettings/{DIAGNOSTIC_SETTING_NAME}. Para más información sobre los URI de recursos de Azure Cosmos DB, consulte sintaxis de URI de recursos para la API de REST de Azure Cosmos DB.

Establezca el cuerpo de la solicitud en esta carga 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
}

Aquí use una plantilla de Azure Resource Manager (ARM) para crear una configuración de diagnóstico.

Nota:

Establezca la propiedad logAnalyticsDestinationType en Dedicated para habilitar tablas específicas del recurso.

Cree el siguiente archivo de plantilla JSON para implementar 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": {
    "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"
          }
        ]
      }
    }
  ]
}

Cree el siguiente archivo de parámetros JSON con la configuración adecuada para el recurso de 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"
    }
  }
}

Implemente la plantilla con az deployment group create.

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

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

Nota

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

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

Para habilitar esta característica, vaya a la página Features de la cuenta de Azure Cosmos DB.
Seleccione Enable. Esta configuración se aplica en unos minutos. Todos los registros recién ingeridos tienen el texto completo o PIICommand para cada solicitud.

Asegúrese de que ha iniciado sesión en la CLI de Azure. Para obtener más información, consulte Inicio de sesión con la CLI de Azure. Opcionalmente, asegúrese de que ha configurado la suscripción activa para la CLI. Para obtener más información, consulte Cambio de la suscripción activa de la CLI de Azure.

Cree variables de shell para accountName y resourceGroupName.

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

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

Obtenga el identificador único de la cuenta existente mediante az show.

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

Almacene el identificador único en una variable de shell denominada $uri.

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

Consulta el recurso mediante la API de REST y az rest con un verbo HTTP GET para verificar si la consulta de texto completo ya está 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}}"

Si la consulta de texto completo no está habilitada, el resultado sería similar a este ejemplo.

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

Si la consulta de texto completo aún no está habilitada, habilítela usando az rest de nuevo con un verbo PATCH HTTP y una carga JSON.
```
az rest \
    --method PATCH \
    --uri "https://management.azure.com/$uri/?api-version=2021-05-01-preview" \
    --body '{"properties": {"diagnosticLogSettings": {"enableFullTextQuery": "True"}}}'
```
Nota

Si usas la CLI de Azure en un símbolo del sistema de PowerShell, deberá evitar las comillas dobles mediante el uso de un carácter de barra diagonal inversa (\).

Espere unos minutos a que se complete la operación. Compruebe el estado de la consulta de texto completo con az rest otra vez.

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

La salida debe ser similar a la del ejemplo siguiente.

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

Consultar datos

Para obtener información sobre cómo consultar mediante estas características recién habilitadas, consulte:

Pasos siguientes

Referencia de datos de supervisión de Azure Cosmos DB

Supervisión de datos de Azure Cosmos DB mediante la configuración de diagnóstico en Azure

Requisitos previos

Crear configuraciones de diagnóstico

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

Consultar datos

Pasos siguientes

Recursos adicionales