Partage via

Bonnes pratiques pour le SDK Java Azure Cosmos DB

  • Article

S’APPLIQUE À : NoSQL

Cet article décrit les bonnes pratiques pour utiliser le SDK Java Azure Cosmos DB. Les pratiques suivantes vous aideront à améliorer la latence, la disponibilité et améliorer les performances globales.

Check-list

Activée Rubrique Détails/Liens
Version du SDK Utilisez toujours la dernière version du kit SDK Azure Cosmos DB disponible pour des performances optimales.
Client Singleton Utilisez une seule instance de CosmosClient pour la durée de vie de votre application pour de meilleures performances.
Régions Exécutez autant que possible votre application dans la même région Azure que celle dans laquelle se trouve votre compte Azure Cosmos DB. Activez les régions 2-4 et répliquez vos comptes dans plusieurs régions pour une disponibilité optimale. Pour les charges de travail de production, activez le basculement managé par le service. En l’absence de cette configuration, le compte subit une perte de disponibilité en écriture pendant toute la durée de la panne de la région d’écriture, car le basculement manuel échoue en raison d’un manque de connectivité de la région. Pour savoir comment ajouter plusieurs régions à l’aide du SDK Java, rendez-vous ici.
Disponibilité et basculements Définissez les preferredRegions dans le SDK v4. Pendant les basculements, les opérations d’écriture sont envoyées à la région d’écriture en cours et toutes les lectures sont envoyées à la première région de la liste de régions de votre choix. Pour plus d’informations sur le mécanisme de basculement régional, consultez le Guide de résolution des problèmes de disponibilité.
UC Vous pouvez rencontrer des problèmes de connectivité/disponibilité en raison d’un manque de ressources sur votre ordinateur client. Surveillez l’utilisation du processeur sur les nœuds qui exécutent le client Azure Cosmos DB et augmentez/arrêtez si l’utilisation est très élevée.
Hosting Pour les cas les plus courants de charges de travail de production, nous vous recommandons vivement d’utiliser des machines virtuelles avec au moins 4 cœurs et 8 Go de mémoire si possible.
Modes de connectivité Utilisez le Mode direct pour obtenir des performances optimales. Pour obtenir des instructions sur la procédure à suivre, consultez la documentation du SDK V4.
Mise en réseau Si vous utilisez une machine virtuelle pour exécuter votre application, activez la Mise en réseau accélérée sur votre machine virtuelle pour faciliter les goulots d’étranglement dus à un trafic élevé et réduire la latence ou l’instabilité du processeur. Vous pouvez également envisager d’utiliser une Machine virtuelle de fin supérieure où l’utilisation maximale de l’UC est inférieure à 70%.
Épuisement des ports éphémères Pour les connexions éparses ou sporadiques, nous vous recommandons de définir idleEndpointTimeout avec une valeur plus élevée. La propriété idleEndpointTimeout dans DirectConnectionConfig permet de contrôler quand fermer les connexions inutilisées. Cela réduira le nombre de connexions inutilisées. Par défaut, les connexions inactives à un point de terminaison sont conservées ouvertes pendant 1 heure. S’il n’y a pas de demandes à un point de terminaison spécifique pendant la durée du délai d’expiration du point de terminaison inactif, le client direct ferme toutes les connexions à ce point de terminaison pour économiser les ressources et le coût des E/S.
Utilisation du Scheduler approprié (éviter le vol de threads Netty E/S Eventloop) Évitez les appels bloquants : .block(). L’ensemble de la pile des appels est asynchrone afin de tirer parti des modèles d’API asynchrones et de l’utilisation du threading et des planificateurs appropriés.
Délais d’expiration de bout en bout Pour obtenir des délais d’expiration de bout en bout, implémentez la stratégie de délai d’expiration de bout en bout dans le Kit de développement logiciel (SDK) Java. Pour plus d’informations sur les délais d’expiration avec Azure Cosmos DB, rendez-vous ici
Logique de nouvelle tentative Une erreur temporaire est une erreur qui a une cause sous-jacente qui se résout rapidement seule. Les applications qui se connectent à votre base de données doivent être conçues de sorte à s’attendre à de telles erreurs temporaires. Pour les gérer, implémentez une logique de nouvelle tentative dans leur code au lieu de les exposer aux utilisateurs comme des erreurs d’application. Le kit de développement logiciel (SDK) intègre une logique permettant de gérer ces échecs temporaires sur des demandes renouvelables telles que des opérations de lecture ou d’interrogation. Le SDK ne réessaiera pas les écritures en cas d’échec temporaire, car les écritures ne sont pas idempotent. Le kit de développement logiciel (SDK) permet aux utilisateurs de configurer une logique de nouvelle tentative pour les limitations. Pour plus d’informations sur les erreurs où les nouvelles tentatives sont possibles, rendez-vous ici
Mise en cache des noms de base de données/collection Récupérez les noms de vos bases de données et de vos conteneurs à partir de la configuration ou mettez-les en cache au démarrage. Les appels tels que CosmosAsyncDatabase#read() ou CosmosAsyncContainer#read() peuvent entraîner des appels de métadonnées au service, qui consomment les RU réservées au système. createDatabaseIfNotExists() doit également être utilisé une seule fois pour configurer la base de données. De manière générale, ces opérations ne doivent pas être effectuées fréquemment.
Requêtes parallèles Le kit SDK Azure Cosmos DB prend en charge l’exécution de requêtes en parallèle pour améliorer la latence et le débit sur vos requêtes. Nous vous recommandons de définir la maxDegreeOfParallelism propriété dans le CosmosQueryRequestsOptions au nombre de partitions que vous avez. Si vous ne connaissez pas le nombre de partitions, définissez la valeur sur -1 qui vous donnera la meilleure latence. En outre, définissez le maxBufferedItemCount sur le nombre attendu de résultats retournés pour limiter le nombre de résultats pré-récupérés.
Tests de performances - Interruptions Lorsque vous effectuez des tests sur votre application, vous devez implémenter des backoffs à intervalles RetryAfter. Le respect de l’interruption contribue à garantir un temps d’attente minimal entre les différentes tentatives.
Indexation La stratégie d’indexation d’Azure Cosmos DB vous permet également de spécifier les chemins de document à inclure ou exclure lors de l’indexation en utilisant les chemins d’indexation IndexingPolicy#getIncludedPaths() et IndexingPolicy#getExcludedPaths(). Veillez à exclure les chemins inutilisés de l’indexation pour accélérer les écritures. Pour obtenir un exemple sur la création d’index avec le SDK, rendez-vous ici
Taille du document Les frais de requête d’une opération donnée sont directement liés à la taille du document. Nous vous recommandons de réduire la taille de vos documents, car les opérations sur les documents volumineux coûtent plus que les opérations sur des documents plus petits.
Taille de la page Par défaut, les résultats de requête sont retournés dans des segments de 100 éléments ou de 4 Mo, selon la limite atteinte en premier. Si une requête retourne plus de 100 éléments, augmentez la taille de page pour réduire le nombre d’allers-retours requis. La consommation de mémoire augmente à mesure que la taille de page augmente.
Activation des métriques de requête Pour journaliser davantage vos exécutions de requêtes back-end, suivez les instructions pour capturer les métriques de requêtes SQL à l’aide du SDK Java
Journalisation SDK Utilisez la journalisation du SDK pour capturer des informations de diagnostic supplémentaires et résoudre les problèmes de latence. Journalisez les CosmosDiagnostics dans le SDK Java pour obtenir des informations de diagnostic Azure Cosmos DB plus détaillées sur la requête actuelle au service. À titre d’exemple de cas d’usage, capturez les diagnostics sur une exception et sur les opérations terminées si CosmosDiagnostics#getDuration() est supérieur à une valeur de seuil désignée (par exemple, si vous avez un contrat SLA de 10 secondes, puis capturez les diagnostics lorsque getDuration()> 10 secondes). Il est recommandé d’utiliser ces diagnostics uniquement lors des tests de performances. Pour plus d’informations, suivez Capturer les diagnostics sur le SDK Java
Évitez d'utiliser des caractères spéciaux dans les identifiants Certains caractères sont restreints et ne peuvent pas être utilisés dans certains identifiants : '/', '\', '?', '#'. La suggestion générale est de ne pas utiliser de caractères spéciaux dans les identifiants tels que le nom de la base de données, le nom de la collection, l'ID de l'élément ou la clé de partition pour éviter tout comportement inattendu.

Meilleures pratiques lors de l’utilisation du mode Passerelle

Les requêtes d’Azure Cosmos DB sont effectuées via le protocole HTTPS/REST lorsque vous utilisez le mode passerelle. Elles sont soumises à la limite de connexion par défaut par nom d’hôte ou adresse IP. Vous risquez de devoir définir maxConnectionPoolSize avec une autre valeur (de 100 à 1 000) afin que la bibliothèque cliente puisse utiliser plusieurs connexions simultanées à Azure Cosmos DB. Dans le SDK Java v4, la valeur par défaut pour GatewayConnectionConfig#maxConnectionPoolSize est 1000. Pour changer cette valeur, vous pouvez définir GatewayConnectionConfig#maxConnectionPoolSize avec une autre valeur.

Meilleures pratiques pour les charges de travail lourdes en écriture

Pour les charges de travail qui ont des charges utiles de création intensives, attribuez à l’option de requête CosmosClientBuilder#contentResponseOnWriteEnabled() la valeur false. Le service ne renvoie plus la ressource créée ou mise à jour au kit de développement logiciel (SDK). Normalement, comme l’application détient l’objet en cours de création, le service n’a pas besoin de le retourner. Les valeurs d’en-tête sont toujours accessibles, comme des frais de requête. La désactivation de la réponse de contenu peut améliorer les performances, car le kit SDK n’a plus besoin d’allouer de la mémoire ni de sérialiser le corps de la réponse. Cela réduit également l’utilisation de la bande passante réseau pour améliorer encore les performances.

Étapes suivantes

Pour en savoir plus sur les conseils de performances pour le SDK Java, consultez Conseils sur les performances pour le SDK Java v4 Azure Cosmos DB.

Pour en savoir plus sur la conception de votre application pour une mise à l’échelle et de hautes performances, consultez Partitionnement, clés de partition et mise à l’échelle dans Cosmos DB.

Vous tentez d’effectuer une planification de la capacité pour une migration vers Azure Cosmos DB ? Vous pouvez utiliser les informations sur votre cluster de bases de données existant pour la planification de la capacité.