Diagnostiquer et résoudre des problèmes lors de l’utilisation du Kit de développement logiciel (SDK) Azure Cosmos DB

Article
06/01/2023

S’APPLIQUE À : NoSQL

Cet article traite des problèmes courants, des solutions de contournement, des étapes de diagnostic et des outils quand vous utilisez le kit SDK .NET avec des comptes Azure Cosmos DB for NoSQL. Le Kit de développement logiciel (SDK) .NET 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.

Liste de contrôle pour la résolution des problèmes

Examinez la liste de contrôle avant de mettre votre application en production. L’utilisation de la liste de contrôle empêche l’affichage de plusieurs problèmes courants. Elle permet également de diagnostiquer rapidement quand un problème se produit :

Utilisez le dernier Kit de développement logiciel (SDK). Les kits de développement logiciel (SDK) en préversion ne doivent pas être utilisés en production. Cela vous évitera de rencontrer des problèmes connus déjà corrigés.
Consultez les conseils relatifs aux performances et suivez les pratiques suggérées. Cela vous aidera à éviter des problèmes de mise à l’échelle, de latence et autres liés aux performances.
Activez la journalisation du SDK pour vous aider à résoudre un problème. L’activation de la journalisation pouvant affecter les performances, il est préférable de ne l’activer que lors de la résolution de problèmes. Vous pouvez activer les journaux suivants :
- Journaliser les métriques à l’aide du portail Azure. Les métriques du portail présentent la télémétrie d’Azure Cosmos DB, qui est utile pour déterminer si le problème est lié à Azure Cosmos DB ou au client.
- Consignez la chaîne de diagnostic des opérations et/ou des exceptions.

Jetez un coup d’œil à la section Problèmes courants et solutions de contournement dans cet article.

Consultez la section des problèmes GitHub qui faisant l’objet d’une surveillance active. Vérifiez si un problème similaire au vôtre dispose déjà d’une solution de contournement. Si vous ne trouvez pas une solution, signalez un incident GitHub. Vous pouvez ouvrir un ticket de support pour des problèmes urgents.

Capturer les diagnostics

Toutes les réponses du kit de développement logiciel (SDK) y compris CosmosException possède une propriété Diagnostics. Cette propriété enregistre toutes les informations relatives à la requête unique, notamment en cas de nouvelles tentatives ou d’échecs temporaires.

Les diagnostics sont retournés sous forme de chaîne. La chaîne change avec chaque version, car elle est améliorée pour résoudre les différents scénarios. Avec chaque version du SDK, le formatage de la chaîne comporte des changements cassants. N’analysez pas la chaîne pour éviter les changements cassants. L’exemple de code suivant montre comment lire les journaux de diagnostic à l’aide du kit de développement logiciel (SDK) .NET :

try
{
    ItemResponse<Book> response = await this.Container.CreateItemAsync<Book>(item: testItem);
    if (response.Diagnostics.GetClientElapsedTime() > ConfigurableSlowRequestTimeSpan)
    {
        // Log the response.Diagnostics.ToString() and add any additional info necessary to correlate to other logs 
    }
}
catch (CosmosException cosmosException)
{
    // Log the full exception including the stack trace with: cosmosException.ToString()
    
    // The Diagnostics can be logged separately if required with: cosmosException.Diagnostics.ToString()
}

// When using Stream APIs
ResponseMessage response = await this.Container.CreateItemStreamAsync(partitionKey, stream);
if (response.Diagnostics.GetClientElapsedTime() > ConfigurableSlowRequestTimeSpan || !response.IsSuccessStatusCode)
{
    // Log the diagnostics and add any additional info necessary to correlate to other logs with: response.Diagnostics.ToString()
}

Problèmes courants et solutions de contournement

Recommandations d’ordre général

Suivez tout lien aka.ms inclus dans les détails de l’exception.
Exécutez autant que possible votre application dans la région Azure dans laquelle se trouve votre compte Azure Cosmos DB.
Vous pouvez rencontrer des problèmes de connectivité/disponibilité en raison d’un manque de ressources sur votre ordinateur client. Nous vous recommandons de surveiller votre utilisation de l’UC sur les nœuds exécutant le client Azure Cosmos DB et d’adapter leur échelle si leur charge est importante.

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

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

SNAT

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 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. Cette situation peut aboutir à la limitation de la connexion, à la fermeture de la connexion ou aux délais d’expiration de la requête mentionnés ci-dessus.

Les ports Azure SNAT sont utilisés uniquement quand votre machine virtuelle a une adresse IP privée et tente de se connecter avec une adresse IP publique. Il existe deux solutions de contournement pour éviter la limitation d’Azure SNAT (à condition que vous utilisiez déjà une seule instance client sur l’ensemble de l’application) :

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.

Latence réseau élevée

Consultez notre guide de résolution des problèmes de latence pour plus d’informations sur la résolution des problèmes de latence.

Échecs d’authentification du proxy

Si vous voyez apparaître des erreurs du type HTTP 407 :

Response status code does not indicate success: ProxyAuthenticationRequired (407);

Cette erreur n’est pas générée par le kit SDK ni par le service Azure Cosmos DB. Elle est liée à la configuration réseau. Il manque probablement l’authentification requise pour un proxy de votre configuration réseau. Si vous ne prévoyez pas de vous servir d’un proxy, contactez votre équipe réseau. Si vous utilisez un proxy, veillez à définir la configuration WebProxy appropriée sur CosmosClientOptions.WebProxy lorsque vous créez l’instance cliente.

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.

Si vous rencontrez l’erreur suivante : Unable to load DLL 'Microsoft.Azure.Cosmos.ServiceInterop.dll' or one of its dependencies:, et que vous utilisez Windows, vous devez effectuer une mise à niveau vers la version la plus récente de Windows.

Étapes suivantes

Découvrez les recommandations en matière de performances pour le SDK .NET
Découvrez les bonnes pratiques relatives au SDK .NET

Partager via