Résoudre les problèmes liés à l’utilisation du Kit de développement logiciel (SDK) Python Azure Cosmos DB avec l’API pour les comptes NoSQL

Cet article traite des problèmes courants, des solutions de contournement, des étapes de diagnostic et des outils lorsque vous utilisez le Kit de développement logiciel (SDK) Python Azure Cosmos DB avec des comptes Azure Cosmos DB pour NoSQL. Le SDK Python Azure Cosmos DB fournit une représentation logique côté client pour accéder à Azure Cosmos DB pour NoSQL. Cet article décrit les outils et les approches qui peuvent vous aider si vous rencontrez des problèmes.

Commencez par cette liste :

• Jetez un coup d’œil à la section Problèmes courants et solutions de contournement dans cet article.
• Examinez le Kit de développement logiciel (SDK) Python dans le référentiel central Azure Cosmos DB, qui est disponible open source sur GitHub. Il comporte une section de problèmes qui est activement surveillée. Vérifiez si un problème similaire au vôtre dispose déjà d’une solution de contournement. Un conseil utile consiste à filtrer les problèmes par la *Cosmos* balise.
• Passez en revue les conseils de performances pour le Kit de développement logiciel (SDK) Python Azure Cosmos DB et suivez les pratiques suggérées.
• Lisez le reste de cet article, si vous n’avez pas trouvé de solution. Ensuite, déposez un problème GitHub. S’il existe une option permettant d’ajouter des balises à votre problème GitHub, ajoutez une *Cosmos* balise.

Journalisation et capture des diagnostics

Cette bibliothèque utilise la bibliothèque de journalisation standard pour la journalisation des diagnostics. Les informations de base sur les sessions HTTP (URL, en-têtes, etc.) sont journalisées au niveau INFO.

La journalisation détaillée au niveau DUBUG, y compris les corps de requête/réponse et les en-têtes non adoptés, peut être activée sur un client avec l’argument 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)

De la même façon, logging_enable peut activer la journalisation détaillée pour une seule opération, même quand elle n’est pas activée pour le client :

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

Vous pouvez également vous connecter à l’aide du CosmosHttpLoggingPolicy, qui s’étend du HttpLoggingPolicy azure core, en passant votre enregistreur à l’argument logger. Par défaut, il utilise le comportement à partir de HttpLoggingPolicy. Le passage de l’argument enable_diagnostics_logging activera le CosmosHttpLoggingPolicy, avec des informations supplémentaires dans la réponse pertinentes pour le débogage des problèmes 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)

De même, la journalisation peut être activée pour une seule opération en passant un enregistreur d’événements à la demande singulière. Pourtant, si vous souhaitez utiliser le CosmosHttpLoggingPolicy pour obtenir des informations supplémentaires, l'argument enable_diagnostics_logging doit être transmis au constructeur du client.

# 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)

Conception de nouvelle tentative

Consultez notre guide pour concevoir des applications résilientes avec les kits de développement logiciel (SDK) Azure Cosmos DB pour obtenir des conseils sur la procédure de conception d’applications résilientes et pour découvrir les sémantiques de nouvelles tentatives du kit de développement logiciel (SDK).

Problèmes courants et solutions de contournement

Recommandations d’ordre général

Pour un résultat optimal :

• Vérifiez que l’application s’exécute sur la même région que votre compte Azure Cosmos DB.
• Vérifiez l’utilisation du processeur sur l’hôte où l’application est en cours d’exécution. Si l’utilisation du processeur est de 50 % ou plus, exécutez votre application sur un hôte avec une configuration plus élevée. Vous pouvez également distribuer la charge sur d’autres ordinateurs.
  • Si vous exécutez votre application sur Azure Kubernetes Service, vous pouvez utiliser Azure Monitor pour surveiller l’utilisation du processeur.

Consulter les métriques du portail

Les métriques du portail vous aident à déterminer si un problème est lié au client ou au service. Par exemple, si les métriques contiennent un taux important de requêtes à débit limité (code d’état HTTP 429), ce qui signifie que la requête est limitée, voir la section Taux de requêtes trop élevé.

Régulation du débit de connexion

La limitation de connexion peut se produire en raison d’une [limite de connexion sur une machine hôte] ou d’un épuisement des ports Azure SNAT (PAT).

Limite de connexion sur une machine hôte

Certains systèmes Linux, tels que Red Hat, ont une limite supérieure sur le nombre total de fichiers ouverts. Les sockets dans Linux sont implémentés en tant que fichiers. Ce nombre limite également le nombre total de connexions. Exécutez la commande suivante.

ulimit -a

Le nombre maximal de fichiers ouverts autorisés, identifiés comme « nofile », doit être au moins double de la taille de votre pool de connexions. Pour plus d’informations, consultez les conseils de performances du Kit de développement logiciel (SDK) Python Azure Cosmos DB.

Épuisement du port SNAT (PAT) Azure

Si votre application est déployée sur des machines virtuelles Azure sans adresse IP publique, par défaut, les ports Azure SNAT établissent des connexions à n’importe quel point de terminaison en dehors de votre machine virtuelle. Le nombre de connexions autorisées de la machine virtuelle au point de terminaison Azure Cosmos DB est limité par la configuration Azure SNAT.

Les ports SNAT Azure sont utilisés uniquement lorsque votre machine virtuelle a une adresse IP privée et qu’un processus de la machine virtuelle tente de se connecter à une adresse IP publique. Il existe deux solutions de contournement pour éviter la limitation azure SNAT :

• Ajoutez votre point de terminaison de service Azure Cosmos DB au sous-réseau de votre réseau virtuel Machines virtuelles Azure. Pour plus d’informations, consultez Points de terminaison de service de réseau virtuel Azure.

  Quand le point de terminaison de service est activé, les requêtes ne sont plus envoyées d’une adresse IP publique à Azure Cosmos DB. Au lieu de cela, les identités du réseau virtuel et du sous-réseau sont envoyées. Cette modification peut entraîner des problèmes de pare-feu si seules les adresses IP publiques sont autorisées. Si vous utilisez un pare-feu, quand vous activez le point de terminaison de service, ajoutez un sous-réseau au pare-feu à l’aide de Listes de contrôle d’accès de réseau virtuel.

• Affectez une adresse IP publique à votre machine virtuelle Azure.

Impossible d’atteindre le service - pare-feu

azure.core.exceptions.ServiceRequestError: indique que le Kit de développement logiciel (SDK) ne peut pas atteindre le service. Suivez la limite de connexion sur un ordinateur hôte.

Échec de connexion à l’émulateur Azure Cosmos DB

Le certificat HTTPS de l’émulateur Azure Cosmos DB est auto-signé. Pour que le Kit de développement logiciel (SDK) Python fonctionne avec l’émulateur, importez le certificat de l’émulateur. Pour plus d’informations, consultez Exporter des certificats d’émulateur Azure Cosmos DB.

Serveur proxy HTTP

Si vous utilisez un proxy HTTP, vérifiez qu’il peut prendre en charge le nombre de connexions configuré dans SDK ConnectionPolicy. Sinon, vous serez confronté à des problèmes de connexion.

Problèmes courants liés aux requêtes

Les métriques de requête vous aident à déterminer où la requête passe la majeure partie du temps. Elles vous permettent de voir quelle portion du temps est consacrée au serveur principal et au client. En savoir plus sur le Guide des performances des requêtes.

Étapes suivantes

• En savoir plus sur les recommandations en matière de performances pour le Kit de développement logiciel (SDK) Python
• En savoir plus sur les meilleures pratiques pour le Kit de développement logiciel (SDK) Python