Résoudre les problèmes liés à l’utilisation du SDK Python Azure Cosmos DB avec des comptes d’API pour NoSQL

S’APPLIQUE À : NoSQL

• Kit de développement logiciel (SDK) Python
• Kit SDK Java v4
• Kit SDK Java asynchrone v2
• .NET

Important

Cet article traite uniquement de la résolution des problèmes liés au SDK Python Azure Cosmos DB. Pour plus d’informations, consultez le fichier Lisez-moi, les Notes de publication, le package (PyPI), le package (Conda) et les conseils relatifs aux performances du SDK Python Azure Cosmos DB.

Cet article traite des problèmes, solutions de contournement, étapes de diagnostic et outils courants lors de l’utilisation du SDK Python Azure Cosmos DB avec des comptes Azure Cosmos DB for NoSQL. Le SDK Python Azure Cosmos DB fournit la représentation logique côté client pour accéder à Azure Cosmos DB for 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.
• Consultez le SDK Python dans le référentiel centralisé Azure Cosmos DB, disponible en open source sur GitHub. Il contient une section Problèmes qui est activement tenue à jour. Vérifiez si un problème similaire au vôtre dispose déjà d’une solution de contournement. Une astuce intéressante consiste à filtrer les problèmes par la balise *Cosmos*.
• Consultez les conseils relatifs aux performances pour le 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, consignez un problème GitHub. S’il existe une option permettant d’ajouter des balises à votre problème GitHub, ajoutez une balise *Cosmos*.

Journalisation et capture des diagnostics

Important

Nous vous recommandons d’utiliser la dernière version du SDK Python. Vous pouvez consulter l’historique des versions ici

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 de niveau DEBUG, contenant les corps de requête/réponse et les en-têtes non rédigés, peut être activée sur un client à l’aide de 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 avec CosmosHttpLoggingPolicy, qui s’étend depuis azure core HttpLoggingPolicy en passant votre enregistreur d’événements à l’argument logger. Le comportement de HttpLoggingPolicy est utilisé par défaut. Le passage de l’argument enable_diagnostics_logging active CosmosHttpLoggingPolicy et fournit des informations supplémentaires dans la réponse qui portent sur 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. Toutefois, si vous souhaitez utiliser CosmosHttpLoggingPolicy pour obtenir des informations supplémentaires, l’argument enable_diagnostics_logging doit être passé au constructeur 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 dans la même région que votre compte Azure Cosmos DB.
• Vérifiez l’utilisation du processeur sur l’ordinateur hôte où l’application est en cours d’exécution. Si l’utilisation du processeur est supérieure ou égale à 50 %, exécutez votre application sur un hôte disposant d’une configuration plus élevée. Vous pouvez aussi distribuer la charge sur plusieurs ordinateurs.
  • Si vous exécutez votre application sur Azure Kubernetes Service, vous pouvez vous servir d’Azure Monitor pour superviser 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é.

Limitation de la connexion

Une limitation de connexion peut se produire en raison d’une [limite de connexion sur un ordinateur hôte] ou d’un [manque de ports Azure SNAT (PAT)].

Limite de connexion sur un ordinateur hôte

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

ulimit -a

La quantité maximale de fichiers ouverts autorisée, qui sont identifiés comme « nofile », doit être au moins le double votre taille de pool de connexions. Pour plus d’informations, consultez les conseils relatifs aux performances du SDK Python Azure Cosmos DB.

Insuffisance de ports Azure SNAT (PAT)

Si votre application est déployée sur Machine virtuelle Azure sans adresse IP publique, par défaut les ports Azure SNAT établissent des connexions avec 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 Azure SNAT sont utilisés uniquement quand votre machine virtuelle a une adresse IP privée et qu’un processus à partir de la machine virtuelle tente de se connecter avec 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.

  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.

• Assignez 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. Respectez 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 SDK Python fonctionne avec l’émulateur, importez le certificat de l’émulateur. Pour plus d’informations, consultez Exporter les certificats de l’é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

• Découvrir les recommandations en matière de performances pour le SDK Python
• Découvrir les bonnes pratiques relatives au SDK Python