Résoudre les problèmes liés à l’utilisation du Kit de développement logiciel (SDK) Java Asynchrone Azure Cosmos DB v2 avec l’API pour les comptes NoSQL

Cet article traite des problèmes courants, des solutions de contournement, des étapes de diagnostic et des outils lorsque vous utilisez le Kit de développement logiciel (SDK) Java Async avec des comptes Azure Cosmos DB pour NoSQL. Le Kit de développement logiciel (SDK) Java Async fournit une représentation logique côté client pour accéder à Azure Cosmos DB pour 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.
• Examinez le Kit de développement logiciel (SDK), qui est disponible open source sur GitHub. Il comporte une section de problèmes qui est activement surveillée. Vérifiez si un problème similaire au vôtre dispose déjà d’une solution de contournement.
• Consultez les conseils relatifs aux performances et suivez les pratiques suggérées.
• Lisez le reste de cet article, si vous n’avez pas trouvé de solution. Ensuite, déposez un problème GitHub.

Problèmes courants et solutions de contournement

Problèmes réseau, échec du délai d’attente de lecture Netty, faible débit, latence élevée

Recommandations d’ordre général

• Vérifiez que l’application s’exécute sur la même région que votre compte Azure Cosmos DB.
• Vérifiez l’utilisation du processeur sur l’hôte où l’application est en cours d’exécution. Si l’utilisation du processeur est de 90 % ou plus, exécutez votre application sur un hôte avec une configuration plus élevée. Vous pouvez également distribuer la charge sur d’autres ordinateurs.

Régulation du débit de connexion

La limitation de connexion peut se produire en raison d’une limite de connexion sur une machine hôte ou d’épuisement des ports Azure SNAT (PAT).

Limite de connexion sur une machine hôte

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

ulimit -a

Le nombre maximal de fichiers ouverts autorisés, identifiés comme « nofile », doit être au moins double de la taille de votre pool de connexions. Pour plus d’informations, consultez conseils sur les performances.

Épuisement du port SNAT (PAT) Azure

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 à 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 SNAT Azure sont utilisés uniquement lorsque votre machine virtuelle a une adresse IP privée et qu’un processus de la machine virtuelle tente de se connecter à 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 Azure.

  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.

• Affectez une adresse IP publique à votre machine virtuelle Azure.

Impossible d’atteindre le service - pare-feu

ConnectTimeoutException indique que le Kit de développement logiciel (SDK) ne peut pas atteindre le service. Vous pouvez obtenir un échec similaire à ce qui suit lors de l’utilisation du mode direct :

GoneException{error=null, resourceAddress='https://cdb-ms-prod-westus-fd4.documents.azure.com:14940/apps/e41242a5-2d71-5acb-2e00-5e5f744b12de/services/d8aa21a5-340b-21d4-b1a2-4a5333e7ed8a/partitions/ed028254-b613-4c2a-bf3c-14bd5eb64500/replicas/131298754052060051p//', statusCode=410, message=Message: The requested resource is no longer available at the server., getCauseInfo=[class: class io.netty.channel.ConnectTimeoutException, message: connection timed out: cdb-ms-prod-westus-fd4.documents.azure.com/101.13.12.5:14940]

Si vous avez un pare-feu en cours d’exécution sur votre machine d'application, ouvrez la plage de ports de 10 000 à 20 000 qui est utilisée par le mode direct. Suivez également la limite de connexion sur un ordinateur hôte.

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.

Modèle de codage non valide : blocage du thread d’E/S Netty

Le Kit de développement logiciel (SDK) utilise la bibliothèque d’E/S Netty pour communiquer avec Azure Cosmos DB. Le Kit de développement logiciel (SDK) possède des API asynchrones et utilise des API d’E/S non bloquantes de Netty. Les tâches d’E/S du SDK sont effectuées sur les threads d’E/S de Netty. Le nombre de threads IO Netty est configuré pour être identique au nombre de cœurs CPU de la machine de l'application.

Les threads d’E/S de Netty sont censés être utilisés uniquement pour des tâches d’E/S non bloquantes de Netty. Le Kit de développement logiciel (SDK) retourne le résultat d’appel de l’API sur l’un des threads d’E/S Netty au code de l’application. Si l’application effectue une opération durable une fois qu’elle reçoit les résultats sur le thread Netty, le Kit de développement logiciel (SDK) n’a peut-être pas suffisamment de threads d’E/S pour effectuer son travail d’E/S interne. Ce codage d’application peut entraîner un faible débit, une latence élevée et des io.netty.handler.timeout.ReadTimeoutException échecs. La solution de contournement consiste à basculer le thread quand vous savez que l’opération prendra de temps.

Par exemple, examinez l’extrait de code suivant. Il se peut que vous effectuiez un travail de longue durée qui prend plus de quelques millisecondes sur le thread Netty. Dans ce cas, vous risquez de passer dans un état où aucun thread d’E/S Netty n’est présent pour traiter les tâches d’E/S. Par conséquent, vous obtenez un échec ReadTimeoutException.

Kit de développement logiciel (SDK) Java asynchrone V2 (Maven com.microsoft.azure ::azure-cosmosdb)

@Test
public void badCodeWithReadTimeoutException() throws Exception {
    int requestTimeoutInSeconds = 10;

    ConnectionPolicy policy = new ConnectionPolicy();
    policy.setRequestTimeoutInMillis(requestTimeoutInSeconds * 1000);

    AsyncDocumentClient testClient = new AsyncDocumentClient.Builder()
            .withServiceEndpoint(TestConfigurations.HOST)
            .withMasterKeyOrResourceToken(TestConfigurations.MASTER_KEY)
            .withConnectionPolicy(policy)
            .build();

    int numberOfCpuCores = Runtime.getRuntime().availableProcessors();
    int numberOfConcurrentWork = numberOfCpuCores + 1;
    CountDownLatch latch = new CountDownLatch(numberOfConcurrentWork);
    AtomicInteger failureCount = new AtomicInteger();

    for (int i = 0; i < numberOfConcurrentWork; i++) {
        Document docDefinition = getDocumentDefinition();
        Observable<ResourceResponse<Document>> createObservable = testClient
                .createDocument(getCollectionLink(), docDefinition, null, false);
        createObservable.subscribe(r -> {
                    try {
                        // Time-consuming work is, for example,
                        // writing to a file, computationally heavy work, or just sleep.
                        // Basically, it's anything that takes more than a few milliseconds.
                        // Doing such operations on the IO Netty thread
                        // without a proper scheduler will cause problems.
                        // The subscriber will get a ReadTimeoutException failure.
                        TimeUnit.SECONDS.sleep(2 * requestTimeoutInSeconds);
                    } catch (Exception e) {
                    }
                },

                exception -> {
                    //It will be io.netty.handler.timeout.ReadTimeoutException.
                    exception.printStackTrace();
                    failureCount.incrementAndGet();
                    latch.countDown();
                },
                () -> {
                    latch.countDown();
                });
    }

    latch.await();
    assertThat(failureCount.get()).isGreaterThan(0);
}

La solution de contournement consiste à changer le thread sur lequel vous effectuez le travail qui prend du temps. Définissez une instance singleton du planificateur pour votre application.

Kit de développement logiciel (SDK) Java asynchrone V2 (Maven com.microsoft.azure ::azure-cosmosdb)

// Have a singleton instance of an executor and a scheduler.
ExecutorService ex  = Executors.newFixedThreadPool(30);
Scheduler customScheduler = rx.schedulers.Schedulers.from(ex);

Vous devrez peut-être effectuer des tâches qui prennent du temps, par exemple des E/S bloquantes ou des tâches qui nécessitent beaucoup de ressources de calcul. Dans ce cas, basculez le thread vers un worker fourni par votre customScheduler à l’aide de l’API .observeOn(customScheduler) .

Kit de développement logiciel (SDK) Java asynchrone V2 (Maven com.microsoft.azure ::azure-cosmosdb)

Observable<ResourceResponse<Document>> createObservable = client
        .createDocument(getCollectionLink(), docDefinition, null, false);

createObservable
        .observeOn(customScheduler) // Switches the thread.
        .subscribe(
            // ...
        );

En utilisant observeOn(customScheduler), vous relâchez le thread d’E/S Netty et basculez vers votre propre thread personnalisé fourni par le planificateur personnalisé. Cette modification résout le problème. Vous n’obtiendrez plus d’échec io.netty.handler.timeout.ReadTimeoutException.

Problème d’épuisement du pool de connexions

PoolExhaustedException est un échec côté client. Cet échec indique que la charge de travail de votre application est supérieure à ce que le pool de connexions du SDK peut servir. Augmentez la taille du pool de connexions ou distribuez la charge sur plusieurs applications.

Taux de requêtes trop élevé

Cette défaillance est une défaillance côté serveur. Il indique que vous avez consommé votre débit provisionné. Réessayez ultérieurement. Si vous obtenez souvent cette défaillance, envisagez une augmentation du débit de collecte.

Échec de connexion à l’émulateur Azure Cosmos DB

Le certificat HTTPS de l’émulateur Azure Cosmos DB est auto-signé. Pour que le Kit de développement logiciel (SDK) fonctionne avec l’émulateur, importez le certificat de l’émulateur dans un magasin de gestion de la confidentialité Java. Pour plus d’informations, consultez Exporter des certificats d’émulateur Azure Cosmos DB.

Problèmes de conflit de dépendances

Exception in thread "main" java.lang.NoSuchMethodError: rx.Observable.toSingle()Lrx/Single;

L’exception ci-dessus suggère que vous avez une dépendance sur une version antérieure de RxJava lib (par exemple, 1.2.2). Notre KIT SDK s’appuie sur RxJava 1.3.8 qui a des API non disponibles dans la version antérieure de RxJava.

La solution de contournement pour ces problèmes consiste à identifier les autres dépendances qui apportent RxJava-1.2.2 et à exclure la dépendance transitive sur RxJava-1.2.2 et à autoriser le Kit de développement logiciel (SDK) CosmosDB à apporter la version la plus récente.

Pour identifier la bibliothèque qui apporte RxJava-1.2.2, exécutez la commande suivante en regard de votre projet pom.xml fichier :

mvn dependency:tree

Pour plus d’informations, consultez le guide de l’arborescence des dépendances maven.

Une fois que vous avez identifié quel autre dépendance de votre projet a RxJava-1.2.2 comme dépendance transitive, vous pouvez modifier la dépendance pour cette bibliothèque dans votre fichier pom et exclure la dépendance transitive RxJava.

<dependency>
  <groupId>${groupid-of-lib-which-brings-in-rxjava1.2.2}</groupId>
  <artifactId>${artifactId-of-lib-which-brings-in-rxjava1.2.2}</artifactId>
  <version>${version-of-lib-which-brings-in-rxjava1.2.2}</version>
  <exclusions>
    <exclusion>
      <groupId>io.reactivex</groupId>
      <artifactId>rxjava</artifactId>
    </exclusion>
  </exclusions>
</dependency>

Pour plus d'informations, consultez le guide sur l'exclusion des dépendances transitives.

Activer la journalisation du Kit de développement logiciel (SDK) client

Le Kit de développement logiciel (SDK) Java Async utilise SLF4j comme façade de journalisation qui prend en charge la connexion dans des frameworks de journalisation populaires tels que log4j et logback.

Par exemple, si vous souhaitez utiliser log4j comme infrastructure de journalisation, ajoutez les bibliothèques suivantes dans votre classpath Java.

<dependency>
  <groupId>org.slf4j</groupId>
  <artifactId>slf4j-log4j12</artifactId>
  <version>${slf4j.version}</version>
</dependency>
<dependency>
  <groupId>log4j</groupId>
  <artifactId>log4j</artifactId>
  <version>${log4j.version}</version>
</dependency>

Ajoutez également une configuration log4j.

# this is a sample log4j configuration

# Set root logger level to DEBUG and its only appender to A1.
log4j.rootLogger=INFO, A1

log4j.category.com.microsoft.azure.cosmosdb=DEBUG
#log4j.category.io.netty=INFO
#log4j.category.io.reactivex=INFO
# A1 is set to be a ConsoleAppender.
log4j.appender.A1=org.apache.log4j.ConsoleAppender

# A1 uses PatternLayout.
log4j.appender.A1.layout=org.apache.log4j.PatternLayout
log4j.appender.A1.layout.ConversionPattern=%d %5X{pid} [%t] %-5p %c - %m%n

Pour plus d’informations, consultez le manuel d'enregistrement sfl4j.

Statistiques du réseau de système d’exploitation

Exécutez la commande netstat pour avoir une idée du nombre de connexions dans des états tels que ESTABLISHED et CLOSE_WAIT.

Sur Linux, vous pouvez exécuter la commande suivante.

netstat -nap

Filtrez le résultat pour ne conserver que les connexions au point de terminaison Azure Cosmos DB.

Le nombre de connexions au point de terminaison Azure Cosmos DB dans l’état ESTABLISHED ne peut pas être supérieur à la taille de votre pool de connexions configuré.

De nombreuses connexions au point de terminaison Azure Cosmos DB peuvent être dans l’état CLOSE_WAIT . Il peut y avoir plus de 1 000. Un nombre élevé indique que les connexions sont établies et détruites rapidement. Cette situation provoque potentiellement des problèmes. Pour plus d’informations, consultez la section Problèmes courants et solutions de contournement .