Conseils sur les performances pour Azure Cosmos DB et .NET

Azure Cosmos DB est une base de données distribuée rapide et flexible, qui peut être mise à l’échelle en toute transparence avec des niveaux de latence et de 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. Pour en savoir plus, consultez Approvisionner le débit sur un conteneur ou Approvisionner le débit sur une base de données.

Comme Azure Cosmos DB est accessible via des appels réseau, vous pouvez apporter des optimisations côté client pour atteindre des performances de pointe quand vous utilisez le kit SDK SQL .NET.

Si vous essayez d’améliorer les performances de votre base de données, envisagez les options présentées dans les sections suivantes.

Recommandations relatives à l’hébergement

Activer le garbage collection (GC) côté serveur

Réduire la fréquence de garbage collection peut aider dans certains cas. Dans .NET, définissez gcServer sur true.

Effectuer une montée en charge de votre charge de travail cliente

Si vous effectuez des tests à des niveaux de débit élevés ou à des taux supérieurs à 50 000 unités de requête par seconde (RU/s), l’application cliente peut devenir un goulot d’étranglement de la charge de travail, car la machine risque de limiter l’utilisation du processeur ou du réseau. Si vous atteignez ce point, vous pouvez continuer à augmenter le compte Azure Cosmos DB en augmentant la taille des instances de vos applications clientes sur plusieurs serveurs.

Opérations sur les métadonnées

N'utilisez pas Create...IfNotExistsAsync ou Read...Async pour vérifier l'existence d'une base de données ou d'un conteneur dans le chemin critique ou avant d'effectuer une opération sur un élément. La validation doit être effectuée uniquement au démarrage de l’application quand elle est nécessaire, si vous vous attendez à ce qu’elles soient supprimées (sinon, il n’est pas nécessaire). Ces opérations de métadonnées génèrent une latence de bout en bout supplémentaire, n’ont aucun contrat SLA et ont leurs propres limitations distinctes qui ne sont pas mises à l’échelle comme les opérations de données.

Journalisation et suivi

Pour certains environnements .NET DefaultTraceListener est activé. Le DefaultTraceListener pose des problèmes de performance dans les environnements de production, provoquant des goulots d’étranglement importants au niveau du processeur et des E/S. Vérifiez et assurez-vous que DefaultTraceListener est désactivé pour votre application en le supprimant des TraceListeners dans les environnements de production.

Les versions du Kit de développement logiciel (SDK) supérieures à 3.23.0 la suppriment automatiquement lorsqu’elles sont détectées. Avec les versions antérieures, vous pouvez la supprimer à l’aide des commandes suivantes :

if (!Debugger.IsAttached)
{
    Type defaultTrace = Type.GetType("Microsoft.Azure.Cosmos.Core.Trace.DefaultTrace,Microsoft.Azure.Cosmos.Direct");
    TraceSource traceSource = (TraceSource)defaultTrace.GetProperty("TraceSource").GetValue(null);
    traceSource.Listeners.Remove("Default");
    // Add your own trace listeners
}

<configuration>
  <system.diagnostics>
    <sources>
      <source name="DocDBTrace" switchName="SourceSwitch" switchType="System.Diagnostics.SourceSwitch" >
        <listeners>
          <remove name="Default" />
          <!--Add your own trace listeners-->
          <add name="myListener" ... />
        </listeners>
      </source>
    </sources>
  </system.diagnostics>
<configuration>

Disponibilité élevée

Pour obtenir des conseils généraux sur la configuration de la haute disponibilité dans Azure Cosmos DB, consultez Haute disponibilité dans Azure Cosmos DB.

En plus d’une bonne configuration de base dans la plateforme de base de données, il existe des techniques spécifiques qui peuvent être implémentées dans le Kit de développement logiciel (SDK) .NET lui-même, ce qui peut vous aider dans les scénarios de panne. Deux stratégies notables sont la stratégie de disponibilité basée sur le seuil et le disjoncteur au niveau de la partition.

Stratégie de disponibilité basée sur le seuil

La stratégie de disponibilité basée sur des seuils peut améliorer la latence de fin et la disponibilité en envoyant des demandes de lecture parallèles aux régions secondaires (comme défini dans ApplicationPreferredRegions) et en acceptant la réponse la plus rapide. Cette approche peut réduire considérablement l’effet des pannes régionales ou des conditions à latence élevée sur les performances des applications.

Exemple de configuration :

La configuration de cette opération peut être effectuée à l’aide de CosmosClientBuilder:

CosmosClient client = new CosmosClientBuilder("connection string")
    .WithApplicationPreferredRegions(
        new List<string> { "East US", "East US 2", "West US" } )
    .WithAvailabilityStrategy(
        AvailabilityStrategy.CrossRegionHedgingStrategy(
        threshold: TimeSpan.FromMilliseconds(500),
        thresholdStep: TimeSpan.FromMilliseconds(100)
     ))
    .Build();

Ou en configurant des options et en les ajoutant à CosmosClient:

CosmosClientOptions options = new CosmosClientOptions()
{
    AvailabilityStrategy
     = AvailabilityStrategy.CrossRegionHedgingStrategy(
        threshold: TimeSpan.FromMilliseconds(500),
        thresholdStep: TimeSpan.FromMilliseconds(100)
     )
      ApplicationPreferredRegions = new List<string>() { "East US", "East US 2", "West US"},
};

CosmosClient client = new CosmosClient(
    accountEndpoint: "account endpoint",
    authKeyOrResourceToken: "auth key or resource token",
    clientOptions: options);

Fonctionnement :

1. Requête initiale : Au moment T1, une demande de lecture est adressée à la région primaire (par exemple, USA Est). Le Kit de développement logiciel (SDK) attend une réponse jusqu’à 500 millisecondes (valeur threshold).

2. Deuxième requête : S’il n’existe aucune réponse de la région primaire dans les 500 millisecondes, une requête parallèle est envoyée à la région préférée suivante (par exemple, USA Est 2).

3. Troisième demande : Si ni la région primaire ni la région secondaire ne répond dans les 600 millisecondes (500 ms + 100 ms, la thresholdStep valeur), le SDK envoie une autre requête parallèle à la troisième région préférée (par exemple, USA Ouest).

4. La réponse la plus rapide gagne : Quelle que soit la région qui répond en premier, cette réponse est acceptée et les autres requêtes parallèles sont ignorées.

Disjoncteur au niveau de la partition

Le disjoncteur au niveau de la partition (CPPB) est une fonctionnalité du Kit de développement logiciel (SDK) .NET qui améliore la disponibilité et la latence en suivant les partitions physiques non saines. Lorsqu’elle est activée, elle permet d’acheminer les demandes vers des régions plus saines, ce qui empêche les défaillances en cascade en raison de problèmes régionaux ou spécifiques à la partition. La fonctionnalité est indépendante du basculement déclenché par le back-end et est contrôlée par le biais de variables d’environnement.

Cette fonctionnalité est désactivée par défaut, mais elle est activée automatiquement lorsque le basculement au niveau de la partition est activé.

Fonctionnement

1. Détection des défaillances : Lorsque des erreurs spécifiques telles que 503 Service Unavailable, 408 Request Timeoutou des jetons d’annulation sont observés, le SDK compte des échecs consécutifs pour une partition.
2. Déclenchement du basculement : une fois qu’un seuil configuré d’échecs consécutifs est atteint, le kit de développement logiciel (SDK) redirige les demandes de cette plage de clés de partition vers la région préférée suivante à l’aide de GlobalPartitionEndpointManagerCore.TryMarkEndpointUnavailableForPartitionKeyRange.
3. Récupération en arrière-plan : une tâche en arrière-plan est lancée pendant le basculement pour vérifier régulièrement l’intégrité de la partition ayant échoué en essayant de se connecter à ses quatre réplicas. Une fois fonctionnel, le Kit de développement logiciel (SDK) enlève l'override et retourne à la région primaire.

Comportement par type de compte

• Écriture à région unique (maître unique) : Seules les demandes de lecture participent à la logique de basculement PPCB.
• Écriture multirégion (multimaître) : Les demandes de lecture et d’écriture utilisent une logique de basculement PPCB.

Options de configuration

Utilisez les variables d’environnement suivantes pour configurer CPPB :

Comparaison des optimisations de disponibilité

• Stratégie de disponibilité basée sur le seuil :

  • Avantage : réduit la latence de fin en envoyant des demandes de lecture parallèles aux régions secondaires et améliore la disponibilité en préemptant les requêtes qui entraînent des délais d’attente réseau.
  • Compromis : entraîne des coûts supplémentaires de RU (unités de requête) par rapport au disjoncteur, en raison des demandes parallèles supplémentaires entre régions (mais uniquement pendant les périodes où les seuils sont dépassés).
  • Cas d’usage : Optimal pour les charges de travail lourdes en lecture où la réduction de la latence est critique et un coût supplémentaire (en termes de frais de RU et de pression du processeur client) est acceptable. Les opérations d’écriture peuvent également bénéficier, si elles sont choisies dans une stratégie de nouvelle tentative d’écriture non idempotente et que le compte a des écritures multi-régions.

• Disjoncteur au niveau de la partition :

  • Avantage : Améliore la disponibilité et la latence en évitant les partitions non saines, ce qui garantit que les demandes sont acheminées vers des régions plus saines.
  • Compromis : n’entraîne aucun coût supplémentaire de RU, mais peut toujours permettre une certaine perte de disponibilité initiale pour les requêtes qui entraînent des délais d’expiration du réseau.
  • Cas d’usage : idéal pour les charges de travail en écriture lourdes ou mixtes, où des performances cohérentes sont essentielles, en particulier lorsque vous traitez des partitions qui risquent de devenir en mauvais état de manière intermittente.

Ces deux stratégies peuvent être utilisées conjointement pour améliorer la disponibilité de la lecture et de l’écriture et réduire le temps de latence de fin. Le disjoncteur au niveau de la partition peut gérer une variété de scénarios de défaillance transitoire, y compris ceux qui peuvent entraîner un ralentissement des réplicas, sans qu’il soit nécessaire d’effectuer des requêtes en parallèle. En outre, l’ajout d’une stratégie de disponibilité basée sur des seuils réduit davantage la latence de queue et élimine la perte de disponibilité, si un coût de RU supplémentaire est acceptable.

En implémentant ces stratégies, les développeurs peuvent s’assurer que leurs applications restent résilientes, conservent un niveau de performance élevé et offrent une meilleure expérience utilisateur même pendant les pannes régionales ou les conditions à latence élevée.

Régions exclues

La fonctionnalité régions exclues permet un contrôle précis sur le routage des demandes en vous permettant d’exclure des régions spécifiques de vos emplacements préférés en fonction de la demande. Cette fonctionnalité est disponible dans le Kit de développement logiciel (SDK) .NET Azure Cosmos DB version 3.37.0 et ultérieure.

Principaux avantages :

• Gérer la limitation du débit : lors de la rencontre de réponses 429 (Trop de requêtes), routez automatiquement les demandes vers d’autres régions avec un débit disponible
• Routage ciblé : vérifiez que les demandes sont traitées à partir de régions spécifiques en excluant tous les autres
• Ignorer l’ordre par défaut : remplacer la liste des régions par défaut pour les demandes individuelles sans créer de clients distincts

Configuration :

Les régions exclues peuvent être configurées au niveau de la requête à l’aide de la ExcludeRegions propriété :

CosmosClientOptions clientOptions = new CosmosClientOptions()
{
    ApplicationPreferredRegions = new List<string> {"West US", "Central US", "East US"}
};

CosmosClient client = new CosmosClient(connectionString, clientOptions);

Database db = client.GetDatabase("myDb");
Container container = db.GetContainer("myContainer");

//Request will be served out of the West US region
await container.ReadItemAsync<dynamic>("item", new PartitionKey("pk"));

//By using ExcludeRegions, we are able to bypass the ApplicationPreferredRegions list
// and route a request directly to the East US region
await container.ReadItemAsync<dynamic>(
  "item", 
  new PartitionKey("pk"),
  new ItemRequestOptions()
  {
    ExcludeRegions = new List<string>() { "West US", "Central US" }
  });

Exemple de cas d’usage : gestion de la limitation du débit :

ItemResponse<CosmosItem> item;
item = await container.ReadItemAsync<CosmosItem>("id", partitionKey);

if (item.StatusCode == HttpStatusCode.TooManyRequests)
{
    ItemRequestOptions requestOptions = new ItemRequestOptions()
    {
        ExcludeRegions = new List<string>() { "East US" }
    };

    item = await container.ReadItemAsync<CosmosItem>("id", partitionKey, requestOptions);
}

La fonctionnalité fonctionne également avec des requêtes et d’autres opérations :

QueryRequestOptions queryRequestOptions = new QueryRequestOptions()
{
    ExcludeRegions = new List<string>() { "East US" }
};

using (FeedIterator<CosmosItem> queryFeedIterator = container.GetItemQueryIterator<CosmosItem>(
    queryDefinition, 
    requestOptions: queryRequestOptions))
{
    while(queryFeedIterator.HasMoreResults)
    {
        var item = await queryFeedIterator.ReadNextAsync();
    }
}

Optimisation de la cohérence et de la disponibilité

La fonctionnalité régions exclues fournit un mécanisme supplémentaire pour équilibrer la cohérence et les compromis de disponibilité dans votre application. Cette fonctionnalité est particulièrement utile dans les scénarios dynamiques où les exigences peuvent changer en fonction des conditions opérationnelles :

Gestion dynamique des pannes : lorsqu’une région primaire subit une panne et que les seuils de disjoncteur au niveau de la partition s’avèrent insuffisants, les régions exclues permettent un basculement immédiat sans modification du code ou redémarrages d’application. Cela fournit une réponse plus rapide aux problèmes régionaux par rapport à l’attente de l’activation automatique du disjoncteur.

Préférences de cohérence conditionnelle : les applications peuvent implémenter différentes stratégies de cohérence en fonction de l’état opérationnel :

• État stable : hiérarchiser les lectures cohérentes en excluant toutes les régions à l’exception du principal, garantissant ainsi la cohérence des données au coût potentiel de disponibilité
• Scénarios de panne : Favoriser la disponibilité par rapport à une cohérence stricte en autorisant le routage interrégion, en acceptant le décalage potentiel des données en échange d’une disponibilité continue du service

Cette approche permet aux mécanismes externes (tels que les gestionnaires de trafic ou les équilibreurs de charge) d’orchestrer les décisions de basculement pendant que l’application conserve le contrôle des exigences de cohérence par le biais de modèles d’exclusion de région.

Lorsque toutes les régions sont exclues, les demandes sont acheminées vers la région principale/hub. Cette fonctionnalité fonctionne avec tous les types de requêtes, y compris les requêtes, et est particulièrement utile pour gérer les instances clientes singleton tout en obtenant un comportement de routage flexible.

Networking

Stratégie de connexion : utilisation du mode de connexion direct

Le mode de connexion par défaut du Kit de développement logiciel (SDK) .NET v3 est direct avec le protocole TCP. Vous configurez le mode de connexion lorsque vous créez l’instance CosmosClient dans CosmosClientOptions. Pour en savoir plus sur les différentes options de connectivité, consultez l’article sur les modes de connectivité.

CosmosClient client = new CosmosClient(
  "<nosql-account-endpoint>",
  tokenCredential
  new CosmosClientOptions
  {
      ConnectionMode = ConnectionMode.Gateway // ConnectionMode.Direct is the default
  }
);

Épuisement des ports éphémères

Si vous êtes confronté à un volume de connexion élevé ou à une utilisation élevée des ports sur vos instances, vérifiez d’abord que vos instances clientes sont des singletons. En d’autres termes, les instances clientes doivent être uniques pour la durée de vie de l’application.

Lorsqu’il s’exécute sur le protocole TCP, le client optimise la latence en utilisant les connexions à long terme. Cela diffère du protocole HTTPS, qui met fin aux connexions après deux minutes d’inactivité.

Dans les scénarios où vous disposez de peu d’accès, si vous remarquez un nombre de connexions supérieur par rapport au mode passerelle, vous pouvez :

• Configurer la propriété CosmosClientOptions.PortReuseMode sur PrivatePortPool (en vigueur avec la version 4.6.1 ou ultérieure du framework et .NET Core version 2.0 ou ultérieure). Cette propriété permet au kit SDK d’utiliser un petit pool de ports éphémères pour différents points de terminaison de destination Azure Cosmos DB.
• Configurer la propriété CosmosClientOptions.IdleTcpConnectionTimeout afin qu’elle soit supérieure ou égale à 10 minutes. Les valeurs recommandées sont comprises entre 20 minutes et 24 heures.

Pour des performances optimales, colocalisez les clients dans la même région Azure

Dans la mesure du possible, placez toutes les applications qui appellent Azure Cosmos DB dans la même région que la base de données Azure Cosmos DB. Voici une comparaison approximative : des appels à Azure Cosmos DB dans une même région s’effectuent en 1 à 2 millisecondes (ms), mais la latence entre la côte ouest et la côte est des États-Unis est supérieure à 50 ms. Cette latence peut varier d’une requête à l’autre, en fonction de l’itinéraire utilisé par la requête lorsqu’elle passe du client à la limite du centre de données Azure.

Vous pouvez obtenir la latence la plus faible possible en veillant à ce que l’application appelante soit située dans la même région Azure que le point de terminaison Azure Cosmos DB configuré. Pour obtenir la liste des régions disponibles, voir Régions Azure.

Augmenter le nombre de threads/tâches

Étant donné que les appels à Azure Cosmos DB sont effectués sur le réseau, vous devrez peut-être modifier le degré de concurrence de vos requêtes, afin que l’application cliente attende un temps minimal entre les requêtes. Par exemple, si vous utilisez la bibliothèque parallèle de tâches .NET, créez des centaines de tâches de lecture ou d’écriture dans Azure Cosmos DB.

Activer la mise en réseau accélérée pour réduire la latence et la gigue du processeur

Il est recommandé de suivre les instructions pour activer la mise en réseau accélérée dans votre machine virtuelle Azure Windows ou Linux afin d’optimiser les performances.

Sans mise en réseau accélérée, les E/S transitant entre votre machine virtuelle Azure et d’autres ressources Azure peuvent être acheminées inutilement via un hôte et un commutateur virtuel situé entre la machine virtuelle et sa carte réseau. Le fait d’avoir l’hôte et le commutateur virtuel inline dans le chemin de données entraîne non seulement une augmentation de la latence et de l’instabilité dans le canal de communication, mais aussi le vol des cycles processeur de la machine virtuelle. Avec la mise en réseau accélérée, les interfaces de la machine virtuelle se connectent directement à la carte réseau sans intermédiaires ; tous les détails de la stratégie réseau qui étaient gérés par l'hôte et le commutateur virtuel sont désormais pris en charge par le matériel de la carte réseau ; l'hôte et le commutateur virtuel sont contournés. L’activation de l’accélération réseau se traduit généralement par une latence plus faible et plus cohérente, un débit plus élevé et une utilisation réduite du processeur.

Limitations : l’accélération réseau doit être prise en charge sur le système d’exploitation de la machine virtuelle et ne peut être activée que si la machine virtuelle est arrêtée et libérée. La machine virtuelle ne peut pas être déployée avec Azure Resource Manager. App Service n’a pas de réseau accéléré activé.

Pour plus d’informations, consultez les instructions Windows et Linux .

Utilisation du Kit de développement logiciel (SDK)

Installation du kit de développement logiciel (SDK) le plus récent

Les SDK Azure Cosmos DB sont constamment améliorés pour fournir des performances optimales. Pour déterminer le kit SDK le plus récent et passer en revue les améliorations, consultez SDK Azure Cosmos DB.

Utiliser les API de flux

Le Kit de développement logiciel (SDK) .NET V3 contient des API de flux qui peuvent recevoir et retourner des données sans sérialisation.

Les applications intermédiaires qui ne consomment pas directement les réponses du Kit de développement logiciel (SDK), mais qui les relayent vers d’autres couches Application, peuvent tirer parti des API de flux. Pour obtenir des exemples sur la gestion des flux, consultez les exemples de gestion d’élément.

Utilisez un client singleton Azure Cosmos DB tout au long de la durée de vie de votre application

Chaque CosmosClient instance est thread-safe et effectue une gestion efficace des connexions et la mise en cache des adresses lorsqu’elle fonctionne en mode direct. Pour permettre une gestion efficace des connexions et améliorer les performances du client SDK, nous vous recommandons d’utiliser une seule instance par AppDomain pour la durée de vie de l’application, pour chaque compte avec lequel l’application interagit.

Pour les applications multilocataires qui gèrent plusieurs comptes, consultez les meilleures pratiques associées.

Lorsque vous travaillez sur Azure Functions, les instances doivent également suivre les instructions existantes et gérer une seule instance.

Évitez les appels bloquants

Le kit SDK Azure Cosmos DB doit être conçu pour traiter plusieurs requêtes simultanément. Les API asynchrones permettent à un petit pool de threads de gérer des milliers de requêtes simultanées sans attendre lors d’appels bloquants. Au lieu d’attendre la fin d’une tâche synchrone de longue durée, le thread peut travailler sur une autre requête.

Un problème de performances courant dans les applications utilisant le kit SDK Azure Cosmos DB bloque les appels qui pourraient être asynchrones. De nombreux appels bloquants synchrones entraînent la starvation du pool de threads et une dégradation des temps de réponse.

À ne pas faire :

• Bloquer l’exécution asynchrone en appelant Task.Wait ou Task.Result.
• Utiliser Task.Run pour rendre une API synchrone asynchrone.
• Acquérir des verrous dans les chemins de code courants. Le kit SDK .NET Azure Cosmos DB est le plus performant lorsqu’il est conçu pour exécuter du code en parallèle.
• Appeler Task.Run et l’attendre tout de suite. ASP.NET Core exécute déjà le code d’application sur des threads de pool de threads normaux, donc l’appel de Task.Run entraîne uniquement une planification de pool de threads superflue. Même si le code planifié bloque un thread, Task.Run n’empêche pas cela.
• N’utilisez pas ToList() sur Container.GetItemLinqQueryable<T>(), qui utilise des appels bloquants pour vider la requête de manière synchrone. Utilisez ToFeedIterator() pour vider la requête de façon asynchrone.

À faire :

• Appeler les API .NET Azure Cosmos DB de façon asynchrone.
• L’ensemble de la pile des appels est asynchrone afin de tirer parti des modèles async/await.

Un profileur, tel que PerfView, peut être utilisé pour rechercher des threads fréquemment ajoutés au pool de threads. L’événement Microsoft-Windows-DotNETRuntime/ThreadPoolWorkerThread/Start indique qu’un thread a été ajouté au pool de threads.

Désactiver la réponse de contenu sur les opérations d’écriture

Pour les charges de travail dont le contenu de création est lourd, attribuez à l’option de requête EnableContentResponseOnWrite la valeur false. Le service ne retourne 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 les 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.

ItemRequestOptions requestOptions = new ItemRequestOptions() { EnableContentResponseOnWrite = false };
ItemResponse<Book> itemResponse = await this.container.CreateItemAsync<Book>(book, new PartitionKey(book.pk), requestOptions);
// Resource will be null
itemResponse.Resource

Activer l’exécution en bloc pour optimiser le débit plutôt que la latence

Activez en bloc pour les scénarios où la charge de travail nécessite une grande quantité de débit et la latence n’est pas aussi importante. Pour plus d’informations sur l’activation de l’exécution en bloc et sur les scénarios où elle devrait être utilisée, consultez Introduction à la prise en charge de l’exécution en bloc.

Augmenter System.Net MaxConnections par hôte 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 devrez peut-être définir MaxConnections sur une valeur plus élevée (de 100 à 1 000) afin que la bibliothèque cliente puisse utiliser plusieurs connexions simultanées à Azure Cosmos DB. Dans le Kit de développement logiciel (SDK) .NET 1.8.0 et versions ultérieures, la valeur par défaut de ServicePointManager. DefaultConnectionLimit est 50. Pour modifier cette valeur, vous pouvez définir Documents.Client.ConnectionPolicy.MaxConnectionLimit sur une valeur supérieure.

Augmenter le nombre de threads/tâches

Consultez Augmenter le nombre de threads/tâches dans la section Mise en réseau de cet article.

Gestion des dépendances Newtonsoft.Json

Aperçu

Le SDK .NET Azure Cosmos DB a une dépendance sur Newtonsoft.Json pour les opérations de sérialisation JSON. Cette dépendance n’est pas gérée automatiquement : vous devez ajouter Newtonsoft.Json explicitement en tant que dépendance directe dans votre projet.

Le SDK se compile sur Newtonsoft.Json 10.x en interne, qui a une vulnérabilité de sécurité connue. Bien que le Kit de développement logiciel (SDK) soit techniquement compatible avec la version 10.x et que l’utilisation du SDK de Newtonsoft.Json n’est pas sensible au problème de sécurité signalé, nous vous recommandons toujours d’utiliser la version 13.0.3 ou ultérieure pour éviter les éventuels problèmes de sécurité ou conflits. Les versions 13.x incluent des changements cassants, mais les modèles d’utilisation du Kit de développement logiciel (SDK) sont compatibles avec ces modifications.

Configuration recommandée

Ajoutez toujours Newtonsoft.Json explicitement la version 13.0.3 ou ultérieure en tant que dépendance directe lors de l’utilisation du Kit de développement logiciel (SDK) .NET Azure Cosmos DB v3. N’utilisez pas la version 10.x en raison de vulnérabilités de sécurité connues.

Pour les projets .csproj standard

<ItemGroup>
  <PackageReference Include="Microsoft.Azure.Cosmos" Version="3.47.0" />
  <PackageReference Include="Newtonsoft.Json" Version="13.0.4" />
</ItemGroup>

Pour les projets utilisant la gestion centralisée des packages

Si votre projet utilise Directory.Packages.props:

<Project>
  <ItemGroup>
    <PackageVersion Include="Microsoft.Azure.Cosmos" Version="3.47.0" />
    <PackageVersion Include="Newtonsoft.Json" Version="13.0.4" />
  </ItemGroup>
</Project>

Résolution des problèmes de conflits de version

Référence Newtonsoft.Json manquante

Si vous rencontrez une erreur de build telle que :

The Newtonsoft.Json package must be explicitly referenced with version >= 10.0.2. Please add a reference to Newtonsoft.Json or set the 'AzureCosmosDisableNewtonsoftJsonCheck' property to 'true' to bypass this check.

Cette erreur est générée intentionnellement par les cibles de build du Kit de développement logiciel (SDK) Cosmos DB pour vous assurer que la dépendance est correctement configurée.

Solution pour les applications :

Ajoutez une référence explicite à Newtonsoft.Json, comme indiqué dans la section Configuration recommandée ci-dessus.

Solution pour les bibliothèques :

Si vous créez une bibliothèque (et non une application) et souhaitez différer la dépendance Newtonsoft.Json aux consommateurs de votre bibliothèque, vous pouvez contourner cette vérification en définissant la propriété MSBuild dans votre .csproj:

<PropertyGroup>
  <AzureCosmosDisableNewtonsoftJsonCheck>true</AzureCosmosDisableNewtonsoftJsonCheck>
</PropertyGroup>

Conflits de version de paquet

Si vous rencontrez des erreurs de génération telles que :

error NU1109: Detected package downgrade: Newtonsoft.Json from 13.0.4 to centrally defined 13.0.3

Solution:

1. Identifiez la version requise en vérifiant quels packages ont besoin de versions plus récentes :

   dotnet list package --include-transitive | Select-String "Newtonsoft.Json"
   

2. Mettez à jour votre version de package centralisée pour qu’elle corresponde ou dépasse la version la plus élevée requise :

   <PackageVersion Include="Newtonsoft.Json" Version="13.0.4" />
   

3. Nettoyer et reconstruire :

   dotnet clean
   dotnet restore
   dotnet build
   

Compatibilité des versions

Le tableau suivant présente les versions minimales recommandées de Newtonsoft.Json pour chaque version du Kit de développement logiciel (SDK) Cosmos DB. Bien que le Kit de développement logiciel (SDK) puisse fonctionner techniquement avec la version 10.x, ces versions ne doivent jamais être utilisées en raison de vulnérabilités de sécurité.

Meilleures pratiques

• Toujours ajouter en tant que dépendance directe : le Kit de développement logiciel (SDK) ne gère pas automatiquement cette dépendance pour vous
• Utiliser la version 13.0.3 ou ultérieure : n’utilisez jamais 10.x malgré la compatibilité technique, en raison des vulnérabilités de sécurité connues
• Obligatoire même avec System.Text.Json : vous devez inclure Newtonsoft.Json même lors de l’utilisation UseSystemTextJsonSerializerWithOptions, car le SDK l’utilise en interne pour les types système
• Épingler la version explicitement : ne vous fiez pas à la résolution des dépendances transitives
• Surveiller les avertissements - Traiter les avertissements de rétrogradation du package NuGet (NU1109) comme des erreurs dans les pipelines CI/CD

Opérations de requête

Pour les opérations de requête, consultez les conseils de performances pour les requêtes.

Stratégie d’indexation

Exclusion des chemins d’accès inutilisés de l’indexation pour des écritures plus rapides

La stratégie d’indexation Azure Cosmos DB vous permet également de spécifier les chemins d’accès de document à inclure ou exclure de l’indexation à l’aide de chemins d’indexation (IndexingPolicy.IncludedPaths et IndexingPolicy.ExcludePaths).

Indexer uniquement les chemins dont vous avez besoin vous permet d’améliorer les performances d’écriture, de réduire les frais liés aux unités de requête dans le cadre des opérations d’écriture et de réduire le stockage des index pour les scénarios dans lesquels les modèles de requête sont connus au préalable. Cela est dû au fait que les coûts d’indexation correspondent directement au nombre de chemins d’accès uniques indexés. Par exemple, le code suivant montre comment exclure une section entière des documents (une sous-arborescence) de l’indexation à l’aide du * caractère générique :

var containerProperties = new ContainerProperties(id: "excludedPathCollection", partitionKeyPath: "/pk" );
containerProperties.IndexingPolicy.IncludedPaths.Add(new IncludedPath { Path = "/*" });
containerProperties.IndexingPolicy.ExcludedPaths.Add(new ExcludedPath { Path = "/nonIndexedContent/*");
Container container = await this.cosmosDatabase.CreateContainerAsync(containerProperties);

Pour plus d’informations, consultez Stratégies d’indexation d’Azure Cosmos DB.

Débit

RU/s

Azure Cosmos DB offre un ensemble complet d’opérations de base de données. Ces opérations incluent des requêtes relationnelles et hiérarchiques avec des fonctions définies par l’utilisateur( UDF), des procédures stockées et des déclencheurs, qui fonctionnent tous sur les documents d’une collection de bases de données.

Les coûts associés à chacune de ces opérations varient en fonction du processeur, des E/S et de la mémoire nécessaires à l’exécution de l’opération. Plutôt que de vous soucier de la gestion des ressources matérielles, vous pouvez considérer une unité de requête (RU) comme une mesure unique des ressources nécessaires à l’exécution des diverses opérations de base de données et au traitement d’une requête d’application.

Le débit est approvisionné en fonction du nombre d’unités de requête défini pour chaque conteneur. La consommation de RU est évaluée comme un taux d’unités par seconde. Les applications qui dépassent le taux de RU approvisionné pour leur conteneur sont limitées jusqu’à ce que le taux tombe en dessous du niveau provisionné pour le conteneur. Si votre application nécessite un niveau de débit plus élevé, vous pouvez augmenter votre débit en approvisionnant davantage d’unités de requête.

La complexité d’une requête affecte le nombre d’unités de ressources consommées pour une opération. Le nombre de prédicats, la nature des prédicats, le nombre de fichiers UDF et la taille du jeu de données source ont tous une influence sur le coût des opérations de requête.

Pour évaluer le coût additionnel de toute opération (création, mise à jour ou suppression), examinez l’en-tête x-ms-request-charge (ou la propriété équivalente RequestCharge dans ResourceResponse<T> ou FeedResponse<T> dans le SDK .NET) afin de déterminer le nombre de RUs consommés par les opérations :

// Measure the performance (Request Units) of writes
ItemResponse<Book> response = await container.CreateItemAsync<Book>(myBook, new PartitionKey(myBook.PkValue));
Console.WriteLine("Insert of item consumed {0} request units", response.RequestCharge);
// Measure the performance (Request Units) of queries
FeedIterator<Book> queryable = container.GetItemQueryIterator<ToDoActivity>(queryString);
while (queryable.HasMoreResults)
    {
        FeedResponse<Book> queryResponse = await queryable.ExecuteNextAsync<Book>();
        Console.WriteLine("Query batch consumed {0} request units", queryResponse.RequestCharge);
    }

Les frais de requête retournés dans cet en-tête correspondent à une fraction de votre débit provisionné (à savoir 2 000 RU/s). Par exemple, si la requête ci-dessus renvoie 1 000 documents de 1 Ko, le coût de l’opération est de 1 000. Ainsi, en une seconde, le serveur honore uniquement deux requêtes de ce type avant de limiter le taux des requêtes ultérieures. Pour plus d’informations, consultez Unités de requête et la calculatrice d’unités de requête.

Gestion de la limitation du taux/du taux de requêtes trop élevé

Lorsqu’un client tente de dépasser le débit réservé pour un compte, les performances au niveau du serveur ne sont pas affectées et la capacité de débit n’est pas utilisée au-delà du niveau réservé. Le serveur met fin à la requête de manière préventive avec RequestRateTooLarge (code d’état HTTP 429). Il renvoie un en-tête x-ms-retry-after-ms qui indique la durée, en millisecondes, pendant laquelle l’utilisateur doit attendre avant de retenter la requête.

    HTTP Status 429,
    Status Line: RequestRateTooLarge
    x-ms-retry-after-ms :100

Les kits de développement logiciel (SDK) interceptent tous implicitement cette réponse, respectent l’en-tête retry-after spécifiée par le serveur, puis relancent la requête. La tentative suivante réussira toujours, sauf si plusieurs clients accèdent simultanément à votre compte.

Si plusieurs de vos clients opèrent simultanément et systématiquement au-delà du taux de requête, le nombre de nouvelles tentatives par défaut actuellement défini sur 9 en interne par le client ne suffira peut-être pas. Dans ce cas, le client envoie à l’application une exception CosmosException avec le code d’état 429.

Vous pouvez modifier le nombre de nouvelles tentatives par défaut en définissant les RetryOptions sur l’instance CosmosClientOptions. Par défaut, l’exception CosmosException avec le code d’état 429 est retournée après un temps d’attente cumulé de 30 secondes si la requête continue à fonctionner au-dessus du taux de requête. Cette erreur est renvoyée même lorsque le nombre actuel de nouvelles tentatives est inférieur au nombre maximal de nouvelles tentatives, que la valeur actuelle soit la valeur par défaut 9 ou une valeur définie par l’utilisateur.

Le comportement de nouvelle tentative automatisée contribue à améliorer la résilience et la convivialité pour la plupart des applications. Mais cela peut ne pas être le meilleur comportement lorsque vous effectuez des benchmarks des performances, en particulier lorsque vous mesurez la latence. La latence client observée atteindra un pic si l’expérience atteint la limite de serveur et oblige le kit de développement logiciel (SDK) client à effectuer une nouvelle tentative en silence. Pour éviter des pics de latence lors d’expériences de performances, mesurez les frais retournés par chaque opération et assurez-vous que les requêtes restent sous le taux de requêtes réservé.

Pour plus d’informations, consultez Unités de requête.

Pour un débit plus élevé, concevez en prévision des documents plus petits

Les frais de requête (à savoir, le coût de traitement des requêtes) d’une opération donnée sont directement liés à la taille du document. Les opérations sur les documents volumineux coûtent plus cher que les opérations sur les petits documents.

Étapes suivantes

• Mesurer les performances d’Azure Cosmos DB pour NoSQL avec une infrastructure d’évaluation
• Partitionnement et mise à l’échelle horizontale dans Azure Cosmos DB