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

SE APLICA A: NoSQL

• SDK de Python
• SDK de Java v4
• SDK sincrónico para Java v2
• .NET

Importante

En este artículo se describe la solución de problemas solo para el SDK de Python de Azure Cosmos DB. Consulte el Léame, las notas de la versión, el Paquete (PyPI), el Paquete (Conda) y las sugerencias de rendimiento del SDK de Python de Azure Cosmos DB para obtener más información.

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 for NoSQL. El SDK de Python de Azure Cosmos DB proporciona la representación lógica del lado cliente para acceder a Azure Cosmos DB for 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 comunes y soluciones alternativas de este artículo.
• Consulte el SDK de Python en el repositorio central de Azure Cosmos DB, que está disponible como 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 etiqueta *Cosmos*.
• Revise las sugerencias de rendimiento del SDK de Python de Azure Cosmos DB y siga los procedimientos sugeridos.
• Lea el resto de este artículo y, si no encuentra una solución, registre un problema de GitHub. Si hay una opción para agregar etiquetas al problema de GitHub, agregue la etiqueta *Cosmos*.

Registro y captura de los diagnósticos

Importante

Se recomienda usar la versión más reciente del SDK de Python. Puede comprobar el historial de versiones aquí

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 de información.

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

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 mediante CosmosHttpLoggingPolicy, que se extiende desde el núcleo de Azure HttpLoggingPolicy, pasando el registrador al argumento logger. De forma predeterminada, usará el comportamiento de HttpLoggingPolicy. Pasar el argumento enable_diagnostics_logging habilitará CosmosHttpLoggingPolicy y tendrá 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 registrador a la solicitud singular. Sin embargo, si desea usar CosmosHttpLoggingPolicy para obtener información adicional, el argumento enable_diagnostics_logging debe pasarse en el constructor de 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 está ejecutando en la misma región que la cuenta de Azure Cosmos DB.
• Compruebe el uso de la CPU en el host donde se ejecuta la aplicación. Si el uso de CPU es de un 50 por ciento o más, ejecute la aplicación en un host con una configuración mayor. O bien, distribuya 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 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.

Limitación de la 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 conexiones en una máquina host

Algunos sistemas Linux, como Red Hat, tienen un límite máximo para el número total de archivos abiertos. En Linux, los sockets se implementan como archivos, por lo que este número también limita 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 al menos doblar el tamaño del grupo de conexiones. Para más información, consulte Sugerencias de rendimiento del SDK de Python de Azure Cosmos DB.

Agotamiento de puertos SNAT (PAT) de Azure

Si la aplicación está implementada en Azure Virtual Machines sin una dirección IP pública, los puertos SNAT de Azure se usan de manera predeterminada para establecer conexiones con 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 se usan solo cuando la máquina virtual tiene una dirección IP privada y un proceso de la máquina virtual intenta conectarse con una dirección IP pública. Hay dos soluciones alternativas para evitar la limitación de Azure SNAT:

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

• Asignar 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 conectar con el servicio. Consulte las indicaciones de Límite de conexiones en una máquina host.

Error al conectarse al emulador de Azure Cosmos DB

El certificado HTTPS del emulador de Azure Cosmos DB es un certificado 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 los 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

• Aprenda sobre las instrucciones de rendimiento del SDK de Python
• Obtenga información sobre los procedimientos recomendados para el SDK de Python