Solución de problemas al usar el SDK de Python de Azure Cosmos DB con la API para cuentas NoSQL

En este artículo se tratan problemas comunes, soluciones alternativas, pasos de diagnóstico y herramientas al usar el SDK de Python de Azure Cosmos DB con cuentas de Azure Cosmos DB para NoSQL. El SDK de Python de Azure Cosmos DB proporciona una representación lógica del lado cliente para acceder a Azure Cosmos DB para NoSQL. En este artículo se describen herramientas y enfoques para ayudarle si surge algún problema.

Comience con esta lista:

• Eche un vistazo a la sección Problemas y soluciones de este artículo.
• Examine el SDK de Python en el repositorio central de Azure Cosmos DB, que está disponible de código abierto en GitHub. Tiene una sección de problemas que se supervisa activamente. Compruebe si encuentra algún problema similar con una solución alternativa ya registrada. Una sugerencia útil es filtrar los problemas por la *Cosmos* etiqueta .
• Revise las sugerencias de rendimiento para el SDK de Python de Azure Cosmos DB y siga los procedimientos sugeridos.
• Lea el resto de este artículo si no encontró una solución. A continuación, abra un problema de GitHub. Si hay una opción para agregar etiquetas al problema de GitHub, agregue una *Cosmos* etiqueta.

Registro y captura de los diagnósticos

Esta biblioteca usa la biblioteca de registro estándar para registrar diagnósticos. La información básica sobre las sesiones HTTP (direcciones URL, encabezados, etc.) se registra en el nivel INFO.

El registro detallado de nivel de DEPURACIÓN, incluidos los cuerpos de solicitud/respuesta y los encabezados sin censurar, se puede habilitar en un cliente con el logging_enable argumento:

import sys
import logging
from azure.cosmos import CosmosClient

# Create a logger for the 'azure' SDK
logger = logging.getLogger('azure')
logger.setLevel(logging.DEBUG)

# Configure a console output
handler = logging.StreamHandler(stream=sys.stdout)
logger.addHandler(handler)

# This client will log detailed information about its HTTP sessions, at DEBUG level
client = CosmosClient(URL, credential=KEY, logging_enable=True)

Igualmente, logging_enable puede habilitar el registro detallado de una sola operación, aunque no esté habilitado para el cliente:

database = client.create_database(DATABASE_NAME, logging_enable=True)

Como alternativa, puede registrar usando el CosmosHttpLoggingPolicy, que se extiende desde el núcleo HttpLoggingPolicy de Azure, pasando su registrador al argumento logger. De forma predeterminada, usará el comportamiento de HttpLoggingPolicy. Pasar el argumento enable_diagnostics_logging habilitará CosmosHttpLoggingPolicy y proporcionará información adicional en la respuesta, pertinente para depurar problemas de Cosmos.

import logging
from azure.cosmos import CosmosClient

#Create a logger for the 'azure' SDK
logger = logging.getLogger('azure')
logger.setLevel(logging.DEBUG)

# Configure a file output
handler = logging.FileHandler(filename="azure")
logger.addHandler(handler)

# This client will log diagnostic information from the HTTP session by using the CosmosHttpLoggingPolicy.
# Since we passed in the logger to the client, it will log information on every request.
client = CosmosClient(URL, credential=KEY, logger=logger, enable_diagnostics_logging=True)

Del mismo modo, el registro se puede habilitar para una sola operación pasando un gestor de registro a la solicitud única. Sin embargo, si desea usar el CosmosHttpLoggingPolicy para obtener información adicional, el argumento enable_diagnostics_logging debe pasarse en el constructor del cliente.

# This example enables the `CosmosHttpLoggingPolicy` and uses it with the `logger` passed in to the `create_database` request.
client = CosmosClient(URL, credential=KEY, enable_diagnostics_logging=True)
database = client.create_database(DATABASE_NAME, logger=logger)

Diseño de reintentos

Consulte nuestra guía para diseñar aplicaciones resistentes con los SDK de Azure Cosmos DB para instrucciones sobre cómo diseñar aplicaciones resistentes y saber cuál es la semántica de reintentos del SDK.

Problemas comunes y soluciones alternativas

Sugerencias generales

Para obtener el mejor rendimiento:

• Asegúrese de que la aplicación se ejecuta en la misma región que la cuenta de Azure Cosmos DB.
• Compruebe el uso de cpu en el host donde se ejecuta la aplicación. Si el uso de CPU es del 50 % o más, ejecute la aplicación en un host con una configuración superior. O bien, puede distribuir la carga en más máquinas.
  • Si ejecuta la aplicación en Azure Kubernetes Service, puede usar Azure Monitor para supervisar el uso de la CPU.

Comprobación de las métricas del portal

La comprobación de las métricas del portal le ayudarán a determinar si hay un problema por parte del cliente o si hay un problema con el servicio. Por ejemplo, si las métricas contienen una alta tasa de solicitudes de velocidad limitada (código de estado HTTP 429), lo que significa que la solicitud se ha limitado, consulte la sección Tasa de solicitudes demasiado grande.

Regulación de velocidad de conexión

La limitación de la conexión puede producirse debido a un [límite de conexión en un equipo host] o al agotamiento de puertos [SNAT (PAT) de Azure].

Límite de conexión en un equipo host

Algunos sistemas Linux, como Red Hat, tienen un límite superior en el número total de archivos abiertos. Los sockets en Linux se implementan como archivos, por lo que este número limita también el número total de conexiones. Ejecute el siguiente comando.

ulimit -a

El número máximo permitido de archivos abiertos, que se identifican como "nofile", debe ser al menos el doble del tamaño del grupo de conexiones. Para más información, consulte las sugerencias de rendimiento del SDK de Python de Azure Cosmos DB.

Agotamiento de puertos SNAT (PAT) de Azure

Si la aplicación se implementa en Azure Virtual Machines sin una dirección IP pública, de forma predeterminada, los puertos SNAT de Azure establecen conexiones a cualquier punto de conexión fuera de la máquina virtual. El número de conexiones permitidas desde la máquina virtual hasta el punto de conexión de Azure Cosmos DB está limitado por la configuración de Azure SNAT.

Los puertos SNAT de Azure solo se usan cuando la máquina virtual tiene una dirección IP privada y un proceso de la máquina virtual intenta conectarse a una dirección IP pública. Hay dos soluciones alternativas para evitar la limitación de SNAT de Azure:

• Agregue el punto de conexión de servicio de Azure Cosmos DB a la subred de la red virtual de Azure Virtual Machines. Para obtener más información, consulte puntos de conexión de servicio de red virtual de Azure.

  Cuando se habilita el punto de conexión de servicio, las solicitudes ya no se envían desde una dirección IP pública a Azure Cosmos DB. En su lugar, se envían la red virtual y la identidad de la subred. Este cambio puede producir caídas de firewall si solo se permiten direcciones IP públicas. Si usa un firewall, cuando se habilite el punto de conexión de servicio, agregue una subred al firewall mediante las ACL de Virtual Network.

• Asigne una dirección IP pública a la máquina virtual de Azure.

No se puede acceder al servicio: firewall

azure.core.exceptions.ServiceRequestError: indica que el SDK no puede acceder al servicio. Siga el límite de conexión en un equipo host.

Error al conectarse al emulador de Azure Cosmos DB

El certificado HTTPS del emulador de Azure Cosmos DB está autofirmado. Para que el SDK de Python funcione con el emulador, importe el certificado del emulador. Para más información, consulte Exportación de certificados del emulador de Azure Cosmos DB.

Proxy HTTP

Si usa un Proxy HTTP, asegúrese de que pueda admitir el número de conexiones configuradas en el SDK de ConnectionPolicy. En caso contrario, se encontrará con problemas de conexión.

Problemas de consulta comunes

Las métricas de consulta le ayudarán a determinar dónde está dedicando más tiempo la consulta. En las métricas de consulta, puede ver la cantidad que se dedica al back-end en comparación con el cliente. Obtenga más información en la guía de rendimiento de consultas.

Pasos siguientes

• Más información sobre las directrices de rendimiento para el SDK de Python
• Más información sobre los procedimientos recomendados para el SDK de Python