Partager via

Ajuster les configurations de connexion pour le Kit de développement logiciel (SDK) Java Azure Cosmos DB v4

  • Article

S’APPLIQUE À : NoSQL

Important

Ces conseils en matière de performances concernent uniquement le SDK Java v4 Azure Cosmos DB. Pour plus d’informations, consultez les notes de publication du SDK Java v4 Azure Cosmos DB, le dépôt Maven et le guide de dépannage du SDK Java v4 Azure Cosmos DB. Si vous utilisez actuellement une version antérieure à v4, consultez le guide de migration vers le SDK Java v4 Azure Cosmos DB pour obtenir de l’aide sur la mise à niveau.

Azure Cosmos DB est une base de données distribuée rapide et flexible qui peut être mise à l’échelle en toute transparence avec une latence et un débit garantis. Vous n’avez pas à apporter de modifications d’architecture majeures ou écrire de code complexe pour mettre à l’échelle votre base de données avec Azure Cosmos DB. La réduction et l’augmentation de l’échelle est aussi simple que le passage d’un appel d’API ou de Kit de développement logiciel (SDK). Toutefois, étant donné qu’Azure Cosmos DB est accessible au moyen d’appels réseau, vous pouvez ajuster des configurations de connexion de manière à atteindre des performances de pointe lorsque vous utilisez le Kit de développement logiciel (SDK) Azure Cosmos DB Java v4.

Configuration de connexion

Notes

Dans le Kit de développement logiciel (SDK) Azure Cosmos DB Java v4, le Mode direct est le meilleur choix pour améliorer les performances des bases de données avec la plupart des charges de travail.

Pour en savoir plus sur les différentes options de connectivité, consultez l’article sur les modes de connectivité.

Mode de connexion directe

Le mode de connexion par défaut du kit de développement logiciel (SDK) Java est le mode direct. Les requêtes Azure Cosmos DB en mode direct sont effectuées sur TCP lors de l’utilisation du Kit de développement logiciel (SDK) Azure Cosmos DB Java v4. En interne, le mode direct utilise une architecture spéciale pour gérer dynamiquement les ressources réseau et obtenir de meilleures performances. L’architecture côté client utilisée en mode direct permet une utilisation prévisible du réseau et un accès multiplexé aux réplicas Azure Cosmos DB. Pour en savoir plus sur l’architecture, consultez l’architecture de connexion en mode direct

Vous pouvez configurer le mode de connexion dans le générateur de clients à l’aide de la méthode directMode() comme indiqué ci-dessous. Pour configurer le mode direct avec les paramètres par défaut, appelez la méthode directMode() sans arguments. Pour personnaliser les paramètres de connexion en mode direct, passez DirectConnectionConfig à l’API directMode().

API asynchrone du kit SDK Java V4 (Maven com.azure::azure-cosmos)


/* Direct mode, default settings */
CosmosAsyncClient clientDirectDefault = new CosmosClientBuilder()
        .endpoint(HOSTNAME)
        .key(MASTERKEY)
        .consistencyLevel(CONSISTENCY)
        .directMode()
        .buildAsyncClient();

/* Direct mode, custom settings */
DirectConnectionConfig directConnectionConfig = DirectConnectionConfig.getDefaultConfig();

// Example config, do not use these settings as defaults
directConnectionConfig.setMaxConnectionsPerEndpoint(130);
directConnectionConfig.setIdleConnectionTimeout(Duration.ZERO);

CosmosAsyncClient clientDirectCustom = new CosmosClientBuilder()
        .endpoint(HOSTNAME)
        .key(MASTERKEY)
        .consistencyLevel(CONSISTENCY)
        .directMode(directConnectionConfig)
        .buildAsyncClient();

/* Gateway mode, default settings */
CosmosAsyncClient clientGatewayDefault = new CosmosClientBuilder()
        .endpoint(HOSTNAME)
        .key(MASTERKEY)
        .consistencyLevel(CONSISTENCY)
        .gatewayMode()
        .buildAsyncClient();

/* Gateway mode, custom settings */
GatewayConnectionConfig gatewayConnectionConfig = GatewayConnectionConfig.getDefaultConfig();

// Example config, do not use these settings as defaults
gatewayConnectionConfig.setProxy(new ProxyOptions(ProxyOptions.Type.HTTP, InetSocketAddress.createUnresolved("your.proxy.addr",80)));
gatewayConnectionConfig.setMaxConnectionPoolSize(1000);

CosmosAsyncClient clientGatewayCustom = new CosmosClientBuilder()
        .endpoint(HOSTNAME)
        .key(MASTERKEY)
        .consistencyLevel(CONSISTENCY)
        .gatewayMode(gatewayConnectionConfig)
        .buildAsyncClient();

/* No connection mode, defaults to Direct mode with default settings */
CosmosAsyncClient clientDefault = new CosmosClientBuilder()
        .endpoint(HOSTNAME)
        .key(MASTERKEY)
        .consistencyLevel(CONSISTENCY)
        .buildAsyncClient();

Personnalisation du mode de connexion directe

Si vous souhaitez opter pour un comportement de mode direct non défini par défaut, créez une instance DirectConnectionConfig et personnalisez ses propriétés, puis transmettez l’instance des propriétés personnalisées à la méthode directMode() dans le générateur de clients Azure Cosmos DB.

Ces paramètres de configuration contrôlent le comportement de l’architecture du mode direct sous-jacent dont il est question précédemment.

Pour commencer, utilisez les paramètres de configuration recommandés ci-dessous. Ces options DirectConnectionConfig correspondent à des paramètres de configuration avancés susceptibles d’affecter les performances du kit de développement logiciel (SDK) de manière inattendue. Nous recommandons donc aux utilisateurs de ne pas les modifier, sauf s’ils ont une très bonne connaissance des compromis et que cela est absolument nécessaire. Si vous rencontrez des problèmes sur ce point particulier, contactez l’équipe Azure Cosmos DB.

Option de configuration Default Recommandé Détails
idleConnectionTimeout « PT0 » (ZÉRO) « PT0 » (ZÉRO) Cela représente la durée du délai d’expiration de la connexion inactive pour une connexion unique à un nœud de point de terminaison/back-end (représentant un réplica). Par défaut, le Kit de développement logiciel (SDK) ne ferme pas automatiquement les connexions inactives aux nœuds back-end.
idleEndpointTimeout "PT1H" "PT1H" Cela représente la durée du délai d’expiration de la connexion inactive pour le pool de connexions pour un nœud de point de terminaison/back-end (représentant un réplica). Par défaut, s’il n’y a pas de requêtes entrantes vers un nœud de point de terminaison/back-end spécifique, le Kit de développement logiciel (SDK) ferme toutes les connexions du pool de connexions à ce nœud de point de terminaison/back-end après 1 heure pour économiser les ressources réseau et le coût d’E/S. Pour le modèle de trafic épars ou sporadique, nous vous recommandons de définir cette valeur sur un nombre plus élevé, par exemple 6 heures, 12 heures, voire 24 heures, afin que le Kit de développement logiciel (SDK) n’ait pas à ouvrir les connexions fréquemment. Toutefois, cela utilisera les ressources réseau et un plus grand nombre de connexions seront maintenues ouvertes à tout moment. Si cette valeur est définie sur ZÉRO, la vérification du point de terminaison inactif est désactivée.
maxConnectionsPerEndpoint "130" "130" Cela représente la taille de limite supérieure du pool de connexions pour un nœud de point de terminaison/back-end (représentant un réplica). Le Kit de développement logiciel (SDK) crée des connexions au nœud de point de terminaison/back-end à la demande et en fonction des requêtes simultanées entrantes. Par défaut, si nécessaire, le Kit de développement logiciel (SDK) crée un maximum de 130 connexions à un nœud de point de terminaison/back-end. (REMARQUE : le Kit de développement logiciel (SDK) ne crée pas ces 130 connexions à l’avance.)
maxRequestsPerConnection "30" "30" Cela représente la taille de limite supérieure du nombre maximal de requêtes pouvant être mises en file d’attente sur une seule connexion pour un nœud de point de terminaison/back-end spécifique (représentant un réplica). Le Kit de développement logiciel (SDK) met en file d’attente les requêtes vers une connexion unique à un nœud de point de terminaison/back-end à la demande et en fonction des requêtes simultanées entrantes. Par défaut, si nécessaire, le Kit de développement logiciel (SDK) met en file d’attente un maximum de 30 requêtes vers une connexion unique pour un nœud de point de terminaison/back-end spécifique. (REMARQUE : le Kit de développement logiciel (SDK) ne met pas en file d’attente ces 30 requêtes vers une connexion unique à l’avance.)
connectTimeout "PT5S" « ~PT1S » Cela représente la durée du délai d’expiration de l’établissement de la connexion pour une connexion unique à établir avec un nœud de point de terminaison/back-end. Par défaut, le Kit de développement logiciel (SDK) attend 5 secondes maximum pour l’établissement de la connexion avant de lever une erreur. L’établissement de la connexion TCP utilise l’établissement d’une liaison à plusieurs étapes qui augmente la latence de la durée d’établissement de la connexion. Par conséquent, il est recommandé aux clients de définir cette valeur en fonction de leur bande passante réseau et de leurs paramètres d’environnement. REMARQUE : cette recommandation de ~PT1S concerne uniquement les applications déployées dans les régions colocalisées de leurs comptes Cosmos DB.
networkRequestTimeout "PT5S" "PT5S" Cela représente la durée du délai d’expiration réseau d’une requête unique. Le Kit de développement logiciel (SDK) attend au maximum pendant cette durée pour utiliser une réponse de service une fois que la requête a été écrite dans la connexion réseau. Le Kit de développement logiciel (SDK) autorise uniquement les valeurs comprises entre 1 seconde (min.) et 10 secondes (max.). La définition d’une valeur trop élevée peut entraîner moins de nouvelles tentatives et réduire les chances de succès des nouvelles tentatives.

Mode de connexion de passerelle

Les opérations de plan de contrôle telles que la base de données et le conteneur CRUD utilisent toujours le mode passerelle. Même lorsque l’utilisateur a configuré le mode direct pour les opérations de plan de contrôle, les opérations de plan de contrôle et de métadonnées utilisent les paramètres du mode de passerelle par défaut. Cela convient à la plupart des utilisateurs. Toutefois, les utilisateurs qui souhaitent opter pour le mode direct pour les opérations de plan de données et de réglage des paramètres du mode de passerelle de plan de contrôle peuvent utiliser la substitution directMode() ci-dessous :

API asynchrone du kit SDK Java V4 (Maven com.azure::azure-cosmos)


/* Independent customization of Direct mode data plane and Gateway mode control plane */
DirectConnectionConfig directConnectionConfig = DirectConnectionConfig.getDefaultConfig();

// Example config, do not use these settings as defaults
directConnectionConfig.setMaxConnectionsPerEndpoint(130);
directConnectionConfig.setIdleConnectionTimeout(Duration.ZERO);

GatewayConnectionConfig gatewayConnectionConfig = GatewayConnectionConfig.getDefaultConfig();

// Example config, do not use these settings as defaults
gatewayConnectionConfig.setProxy(new ProxyOptions(ProxyOptions.Type.HTTP, InetSocketAddress.createUnresolved("your.proxy.addr",80)));
gatewayConnectionConfig.setMaxConnectionPoolSize(1000);

CosmosAsyncClient clientDirectCustom = new CosmosClientBuilder()
        .endpoint(HOSTNAME)
        .key(MASTERKEY)
        .consistencyLevel(CONSISTENCY)
        .directMode(directConnectionConfig,gatewayConnectionConfig)
        .buildAsyncClient();

Personnalisation du mode de connexion de passerelle

Si vous souhaitez opter pour un comportement de mode passerelle non défini par défaut, créez une instance GatewayConnectionConfig et personnalisez ses propriétés, puis transmettez l’instance des propriétés personnalisées à la méthode de remplacement directMode() ci-dessus ou la méthode gatewayMode() dans le générateur de clients Azure Cosmos DB.

Pour commencer, utilisez les paramètres de configuration recommandés ci-dessous. Ces options GatewayConnectionConfig correspondent à des paramètres de configuration avancés susceptibles d’affecter les performances du Kit de développement logiciel (SDK) de manière inattendue. Nous recommandons donc aux utilisateurs de ne pas les modifier, sauf s’ils ont une très bonne connaissance des compromis et que cela est absolument nécessaire. Si vous rencontrez des problèmes sur ce point particulier, contactez l’équipe Azure Cosmos DB.

Option de configuration Default Recommandé Détails
maxConnectionPoolSize "1000" "1000" Cela représente la taille de limite supérieure de la taille du pool de connexions pour le client http sous-jacent, qui est le nombre maximal de connexions que le Kit de développement logiciel (SDK) créera pour les requêtes passant en mode passerelle. Le Kit de développement logiciel (SDK) réutilise ces connexions lors de l’envoi de requêtes à la passerelle.
idleConnectionTimeout « PT60S » « PT60S » Cela représente la durée du délai d’expiration de la connexion inactive pour une connexion unique à la passerelle. Après ce délai, la connexion est automatiquement fermée et supprimée du pool de connexions.

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