Behandeln von Problemen bei der Verwendung des Azure Cosmos DB Java SDK v4 mit der API für NoSQL-Konten

Artikel
04/18/2024

GILT FÜR: NoSQL

Wichtig

In diesem Artikel wird die Problembehandlung für das Azure Cosmos DB Java SDK v4 behandelt. Weitere Informationen finden Sie in den Versionshinweisen zum Azure Cosmos DB Java SDK v4, im Maven-Repository und in den Leistungstipps. Wenn Sie aktuell eine ältere Version als v4 verwenden, lesen Sie den Leitfaden Migrieren zu Azure Cosmos DB Java SDK v4, um Hilfe beim Aktualisieren auf v4 zu erhalten.

In diesem Artikel werden häufig auftretende Probleme, Problemumgehungen, Diagnoseschritte und Tools bei Verwendung des Azure Cosmos DB Java SDK v4 mit Azure Cosmos DB for NoSQL-Konten behandelt. Das Azure Cosmos DB Java SDK v4 bietet eine clientseitige logische Darstellung für den Zugriff auf Azure Cosmos DB for NoSQL. Dieser Artikel beschreibt hilfreiche Tools und Vorgehensweisen für Problemfälle.

Beginnen Sie mit dieser Liste:

Sehen Sie sich den Abschnitt Häufig auftretende Probleme und Problemumgehungen in diesem Artikel an.
Sehen Sie sich das Java SDK im zentralen Azure Cosmos DB-Repository an, das Open-Source auf GitHub verfügbar ist. Es verfügt über einen aktiv überwachten Problemabschnitt. Überprüfen Sie, ob Sie ein ähnliches Problem finden, für das bereits eine Problemumgehung dokumentiert wurde. Ein hilfreicher Tipp ist das Filtern von Problemen nach dem Tag *cosmos:v4-item*.
Sehen Sie sich die Leistungstipps für Azure Cosmos DB Java SDK v4 an, und implementieren Sie die empfohlenen Methoden.
Lesen Sie den Rest dieses Artikels, falls Sie keine Lösung gefunden haben. Reichen Sie anschließend ein GitHub-Problem ein. Wenn es eine Option zum Hinzufügen von Tags zu Ihrem GitHub-Issue gibt, fügen Sie das Tag *cosmos:v4-item* hinzu.

Erfassen der Diagnosen

Datenbank-, Container-, Element- und Abfrageantworten im Java V4 SDK umfassen eine Diagnostics-Eigenschaft. In dieser Eigenschaft werden alle Informationen zu einer einzelnen Anforderung aufgezeichnet, unter anderem auch, ob es Wiederholungsversuche oder vorübergehende Fehler gab.

Die Diagnosen werden als Zeichenfolge zurückgegeben. Die Zeichenfolge ändert sich mit jeder Version, da sie verbessert wird, um die Problembehandlung für verschiedene Szenarios zu verbessern. Bei jeder Version des SDK kann die Zeichenfolge ihr Format verlieren. Analysieren Sie die Zeichenfolge nicht, um Breaking Changes zu vermeiden.

Das folgende Codebeispiel zeigt, wie Diagnoseprotokolle mit dem Java V4 SDK gelesen werden:

Wichtig

Es wird empfohlen, die empfohlene Mindestversion des Java v4 SDK zu überprüfen und sicherzustellen, dass Sie diese oder eine höhere Version verwenden. Die empfohlene Version finden Sie hier.

Sync
Asynchron

Datenbankvorgänge

CosmosDatabaseResponse databaseResponse = client.createDatabaseIfNotExists(databaseName);
CosmosDiagnostics diagnostics = databaseResponse.getDiagnostics();
logger.info("Create database diagnostics : {}", diagnostics);

Containervorgänge

CosmosContainerResponse containerResponse = database.createContainerIfNotExists(containerProperties,
                  throughputProperties);
CosmosDiagnostics diagnostics = containerResponse.getDiagnostics();
logger.info("Create container diagnostics : {}", diagnostics);

Elementvorgänge

// Write Item
CosmosItemResponse<Family> item = container.createItem(family, new PartitionKey(family.getLastName()),
                    new CosmosItemRequestOptions());
        
CosmosDiagnostics diagnostics = item.getDiagnostics();
logger.info("Create item diagnostics : {}", diagnostics);
        
// Read Item
CosmosItemResponse<Family> familyCosmosItemResponse = container.readItem(documentId,
                    new PartitionKey(documentLastName), Family.class);
        
CosmosDiagnostics diagnostics = familyCosmosItemResponse.getDiagnostics();
logger.info("Read item diagnostics : {}", diagnostics);

Abfragevorgänge

String sql = "SELECT * FROM c WHERE c.lastName = 'Witherspoon'";
        
CosmosPagedIterable<Family> filteredFamilies = container.queryItems(sql, new CosmosQueryRequestOptions(),
                    Family.class);
        
//  Add handler to capture diagnostics
filteredFamilies = filteredFamilies.handle(familyFeedResponse -> {
    logger.info("Query Item diagnostics through handle : {}", 
    familyFeedResponse.getCosmosDiagnostics());
});
        
//  Or capture diagnostics through iterableByPage() APIs.
filteredFamilies.iterableByPage().forEach(familyFeedResponse -> {
    logger.info("Query item diagnostics through iterableByPage : {}",
    familyFeedResponse.getCosmosDiagnostics());
});

Azure Cosmos DB-Ausnahmen

try {
  CosmosItemResponse<Family> familyCosmosItemResponse = container.readItem(documentId,
                    new PartitionKey(documentLastName), Family.class);
} catch (CosmosException ex) {
  CosmosDiagnostics diagnostics = ex.getDiagnostics();
  logger.error("Read item failure diagnostics : {}", diagnostics);
}

Datenbankvorgänge

Mono<CosmosDatabaseResponse> databaseResponseMono = client.createDatabaseIfNotExists(databaseName);
databaseResponseMono.map(databaseResponse -> {
  CosmosDiagnostics diagnostics = databaseResponse.getDiagnostics();
  logger.info("Create database diagnostics : {}", diagnostics);
}).subscribe();

Containervorgänge

Mono<CosmosContainerResponse> containerResponseMono = database.createContainerIfNotExists(containerProperties,
                    throughputProperties);
containerResponseMono.map(containerResponse -> {
  CosmosDiagnostics diagnostics = containerResponse.getDiagnostics();
  logger.info("Create container diagnostics : {}", diagnostics);
}).subscribe();

Elementvorgänge

// Write Item
Mono<CosmosItemResponse<Family>> itemResponseMono = container.createItem(family,
                    new PartitionKey(family.getLastName()),
                    new CosmosItemRequestOptions());
        
itemResponseMono.map(itemResponse -> {
  CosmosDiagnostics diagnostics = itemResponse.getDiagnostics();
  logger.info("Create item diagnostics : {}", diagnostics);
}).subscribe();
        
// Read Item
Mono<CosmosItemResponse<Family>> itemResponseMono = container.readItem(documentId,
                    new PartitionKey(documentLastName), Family.class);

itemResponseMono.map(itemResponse -> {
  CosmosDiagnostics diagnostics = itemResponse.getDiagnostics();
  logger.info("Read item diagnostics : {}", diagnostics);
}).subscribe();

Abfragevorgänge

String sql = "SELECT * FROM c WHERE c.lastName = 'Witherspoon'";
CosmosPagedFlux<Family> filteredFamilies = container.queryItems(sql, new CosmosQueryRequestOptions(),
                    Family.class);
//  Add handler to capture diagnostics
filteredFamilies = filteredFamilies.handle(familyFeedResponse -> {
  logger.info("Query Item diagnostics through handle : {}",
  familyFeedResponse.getCosmosDiagnostics());
});
        
//  Or capture diagnostics through byPage() APIs.
filteredFamilies.byPage().map(familyFeedResponse -> {
  logger.info("Query item diagnostics through byPage : {}",
  familyFeedResponse.getCosmosDiagnostics());
}).subscribe();

Azure Cosmos DB-Ausnahmen

Mono<CosmosItemResponse<Family>> itemResponseMono = container.readItem(documentId,
                    new PartitionKey(documentLastName), Family.class);

itemResponseMono.onErrorResume(throwable -> {
  if (throwable instanceof CosmosException) {
    CosmosException cosmosException = (CosmosException) throwable;
    CosmosDiagnostics diagnostics = cosmosException.getDiagnostics();
    logger.error("Read item failure diagnostics : {}", diagnostics);
  }
  return Mono.error(throwable);
}).subscribe();

Protokollieren der Diagnose

Java V4 SDK-Versionen v4.43.0 und höher unterstützen die automatische Protokollierung von Cosmos-Diagnosen für alle Anforderungen oder Fehler, wenn sie bestimmte Kriterien erfüllen. Anwendungsentwickler*innen können Schwellenwerte für die Wartezeit (für Punktvorgänge (Erstellen, Lesen, Ersetzen, Upsertvorgänge, Patchen) oder Vorgänge ohne Punkte (Abfrage, Änderungsfeed, Massen- und Batchvorgänge)), die Anforderungsgebühr und die Nutzlastgröße definieren. Wenn die Anforderungen diese definierten Schwellenwerte überschreiten, werden die Cosmos-Diagnosen für diese Anforderungen automatisch ausgegeben.

Standardmäßig protokolliert das Java v4 SDK diese Diagnosen automatisch in einem bestimmten Format. Dies kann jedoch geändert werden, indem die CosmosDiagnosticsHandler-Schnittstelle implementiert und ein eigener benutzerdefinierter Diagnosehandler bereitgestellt wird.

CosmosDiagnosticsThresholds und CosmosDiagnosticsHandler können dann im CosmosClientTelemetryConfig-Objekt verwendet werden, das beim Erstellen des synchronen oder asynchronen Clients an CosmosClientBuilder übergeben werden sollte.

HINWEIS: Diese Diagnoseschwellenwerte werden auf verschiedene Arten von Diagnosen angewendet, einschließlich Protokollierungs-, Ablaufverfolgungs- und Clienttelemetrie.

Die folgenden Codebeispiele zeigen, wie Diagnoseschwellenwerte und benutzerdefinierte Diagnoseprotokollierungen definiert und über die Clienttelemetriekonfiguration verwendet werden:

Sync
Asynchron

Definieren von benutzerdefinierten Diagnoseschwellenwerten

//  Create diagnostics threshold
CosmosDiagnosticsThresholds cosmosDiagnosticsThresholds = new CosmosDiagnosticsThresholds();
//  These thresholds are for demo purposes
//  NOTE: Do not use the same thresholds for production
cosmosDiagnosticsThresholds.setPayloadSizeThreshold(100_00);
cosmosDiagnosticsThresholds.setPointOperationLatencyThreshold(Duration.ofSeconds(1));
cosmosDiagnosticsThresholds.setNonPointOperationLatencyThreshold(Duration.ofSeconds(5));
cosmosDiagnosticsThresholds.setRequestChargeThreshold(100f);

Definieren eines benutzerdefinierten Diagnosehandlers

//  By default, DEFAULT_LOGGING_HANDLER can be used
CosmosDiagnosticsHandler cosmosDiagnosticsHandler = CosmosDiagnosticsHandler.DEFAULT_LOGGING_HANDLER;

//  App developers can also define their own diagnostics handler
cosmosDiagnosticsHandler = new CosmosDiagnosticsHandler() {
    @Override
    public void handleDiagnostics(CosmosDiagnosticsContext diagnosticsContext, Context traceContext) {
        logger.info("This is custom diagnostics handler: {}", diagnosticsContext.toJson());
    }
};

Definieren von CosmosClientTelemetryConfig

//  Create Client Telemetry Config
CosmosClientTelemetryConfig cosmosClientTelemetryConfig =
    new CosmosClientTelemetryConfig();
cosmosClientTelemetryConfig.diagnosticsHandler(cosmosDiagnosticsHandler);
cosmosClientTelemetryConfig.diagnosticsThresholds(cosmosDiagnosticsThresholds);

//  Create sync client
CosmosClient client = new CosmosClientBuilder()
    .endpoint(AccountSettings.HOST)
    .key(AccountSettings.MASTER_KEY)
    .clientTelemetryConfig(cosmosClientTelemetryConfig)
    .buildClient();

Definieren von benutzerdefinierten Diagnoseschwellenwerten

//  Create diagnostics threshold
CosmosDiagnosticsThresholds cosmosDiagnosticsThresholds = new CosmosDiagnosticsThresholds();
//  These thresholds are for demo purposes
//  NOTE: Do not use the same thresholds for production
cosmosDiagnosticsThresholds.setPayloadSizeThreshold(100_00);
cosmosDiagnosticsThresholds.setPointOperationLatencyThreshold(Duration.ofSeconds(1));
cosmosDiagnosticsThresholds.setNonPointOperationLatencyThreshold(Duration.ofSeconds(5));
cosmosDiagnosticsThresholds.setRequestChargeThreshold(100f);

Definieren eines benutzerdefinierten Diagnosehandlers

//  By default, DEFAULT_LOGGING_HANDLER can be used
CosmosDiagnosticsHandler cosmosDiagnosticsHandler = CosmosDiagnosticsHandler.DEFAULT_LOGGING_HANDLER;

//  App developers can also define their own diagnostics handler
cosmosDiagnosticsHandler = new CosmosDiagnosticsHandler() {
    @Override
    public void handleDiagnostics(CosmosDiagnosticsContext diagnosticsContext, Context traceContext) {
        logger.info("This is custom diagnostics handler: {}", diagnosticsContext.toJson());
    }
};

Definieren von CosmosClientTelemetryConfig

//  Create Client Telemetry Config
CosmosClientTelemetryConfig cosmosClientTelemetryConfig =
    new CosmosClientTelemetryConfig();
cosmosClientTelemetryConfig.diagnosticsHandler(cosmosDiagnosticsHandler);
cosmosClientTelemetryConfig.diagnosticsThresholds(cosmosDiagnosticsThresholds);

//  Create async client
CosmosAsyncClient client = new CosmosClientBuilder()
    .endpoint(AccountSettings.HOST)
    .key(AccountSettings.MASTER_KEY)
    .clientTelemetryConfig(cosmosClientTelemetryConfig)
    .buildAsyncClient();

Wiederholungsentwurf

In unserem Leitfaden zum Entwerfen von resilienten Anwendungen mit Azure Cosmos DB SDKs finden Sie entsprechende Anleitungen und lernen die Wiederholungssemantiken des SDK kennen.

Häufig auftretende Probleme und Problemumgehungen

Überprüfen der Metriken im Portal

Indem Sie die Portalmetriken überprüfen, können Sie feststellen, ob es sich um ein Problem auf Clientseite handelt oder ob es ein Problem mit dem Dienst gibt. Wenn die Metriken beispielsweise viele Anforderungen mit Ratenbegrenzungen aufweisen (HTTP-Statuscode 429), bedeutet dies, dass die Anforderung gedrosselt wird. Siehe dann den Abschnitt Anforderungsrate zu hoch.

Netzwerkprobleme, Netty-Lesetimeoutfehler, niedriger Durchsatz, hohe Latenz

Allgemeine Empfehlungen

Für eine optimale Leistung:

Vergewissern Sie sich, dass die App in der gleichen Region ausgeführt wird, in der sich auch Ihr Azure Cosmos DB-Konto befindet.
Überprüfen Sie die CPU-Auslastung auf dem Host, auf dem die App ausgeführt wird. Wenn die CPU-Auslastung 50 Prozent oder mehr beträgt, führen Sie Ihre App auf einem Host mit einer höheren Konfiguration aus. Alternativ können Sie die Last auf mehrere Computer verteilen.
- Wenn Sie Ihre Anwendung in Azure Kubernetes Service ausführen, können Sie Azure Monitor zum Überwachen der CPU-Auslastung verwenden.

Verbindungsdrosselung

Eine Verbindungsdrosselung kann entweder aufgrund eines Verbindungslimit auf einem Hostcomputer oder aufgrund von Azure SNAT-Portauslastung (PAT) auftreten.

Verbindungslimit auf einem Hostcomputer

Bei einigen Linux-Systemen (beispielsweise Red Hat) gilt eine Obergrenze für die Gesamtzahl geöffneter Dateien. Da Sockets in Linux als Dateien implementiert werden, schränkt dies auch die Gesamtanzahl von Verbindungen ein. Führen Sie den folgenden Befehl aus.

ulimit -a

Die maximal zulässige Anzahl geöffneter Dateien (nofile) muss mindestens doppelt so hoch sein wie die Größe Ihres Verbindungspools. Weitere Informationen finden Sie im Artikel zu den Leistungstipps für das Azure Cosmos DB Java SDK v4.

Azure SNAT-Portauslastung (PAT)

Wenn Ihre App auf einem virtuellen Azure-Computer ohne öffentliche IP-Adresse bereitgestellt wird, werden standardmäßig Azure SNAT-Ports verwendet, um Verbindungen mit beliebigen Endpunkten außerhalb Ihres virtuellen Computers herzustellen. Die Anzahl zulässiger Verbindungen des virtuellen Computers mit dem Azure Cosmos DB-Endpunkt wird durch die Azure SNAT-Konfiguration eingeschränkt.

Azure SNAT-Ports werden nur verwendet, wenn Ihr virtueller Computer eine private IP-Adresse besitzt und ein Prozess auf dem virtuellen Computer versucht, eine Verbindung mit einer öffentlichen IP-Adresse herzustellen. Es gibt zwei Problemumgehungen, um die Einschränkung durch Azure SNAT zu vermeiden:

Fügen Sie Ihren Azure Cosmos DB-Dienstendpunkt dem Subnetz Ihres virtuellen Netzwerks von Azure Virtual Machines hinzu. Weitere Informationen finden Sie unter Azure Virtual Network-Dienstendpunkte.

Wenn der Dienstendpunkt aktiviert ist, werden die Anforderungen nicht mehr von einer öffentlichen IP-Adresse an Azure Cosmos DB gesendet. Stattdessen wird die Identität des virtuellen Netzwerks und des Subnetzes gesendet. Diese Änderung kann zu Firewallproblemen führen, wenn nur öffentliche IP-Adressen zulässig sind. Wenn Sie eine Firewall verwenden und den Dienstendpunkt aktivieren, fügen Sie der Firewall mithilfe von VNET-ACLs ein Subnetz hinzu.
Weisen Sie Ihrem virtuellen Azure-Computer eine öffentliche IP-Adresse zu.

Dienst nicht erreichbar – Firewall

ConnectTimeoutException gibt an, dass das SDK den Dienst nicht erreichen kann. Im direkten Modus erhalten Sie möglicherweise einen Fehler ähnlich dem folgenden:

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]

Wenn Sie auf dem Computer mit der App eine Firewall ausführen, öffnen Sie den Portbereich 10.000 bis 20.000, der im direkten Modus verwendet wird. Halten Sie auch das Verbindungslimit auf einem Hostcomputer ein.

UnknownHostException

UnknownHostException bedeutet, dass das Java-Framework den DNS-Eintrag für den Azure Cosmos DB-Endpunkt auf dem betroffenen Computer nicht auflösen kann. Überprüfen Sie, ob der Computer den DNS-Eintrag auflösen kann. Wenn Sie eine benutzerdefinierte DNS-Auflösungssoftware verwenden (z. B. VPN oder Proxy oder eine benutzerdefinierte Lösung), stellen Sie sicher, dass sie die richtige Konfiguration für den DNS-Endpunkt enthält, der laut Fehlermeldung nicht aufgelöst werden kann. Wenn der Fehler weiterhin besteht, können Sie die DNS-Auflösung des Computers durch Senden eines curl-Befehls an den in der Fehlermeldung beschriebenen Endpunkt überprüfen.

HTTP-Proxy

Wenn Sie einen HTTP-Proxy verwenden, vergewissern Sie sich, dass er die Anzahl von Verbindungen unterstützt, die in ConnectionPolicy des SDK konfiguriert ist. Andernfalls treten Verbindungsprobleme auf.

Ungültiges Codierungsmuster: Blockieren eines Netty E/A-Threads

Das SDK verwendet für die Kommunikation mit Azure Cosmos DB die Netty-E/A-Bibliothek. Das SDK verfügt über eine asynchrone API und verwendet nicht blockierende E/A-APIs von Netty. Die E/A-Aufgaben des SDK werden in Netty-E/A-Threads ausgeführt. Die Anzahl von Netty-E/A-Threads ist so konfiguriert, dass sie mit der Anzahl von CPU-Kernen des App-Computers übereinstimmt.

Die Netty-E/A-Threads sind nur für nicht blockierende Netty-E/A-Aufgaben vorgesehen. Das SDK gibt das API-Aufrufergebnis für einen der Netty-E/A-Threads an den Code der App zurück. Wenn die App nach dem Empfang von Ergebnissen im Netty-Thread einen länger dauernden Vorgang ausführt, stehen dem SDK möglicherweise nicht genügend E/A-Threads für interne E/A-Aufgaben zur Verfügung. Eine solche App-Programmierung kann zu niedrigem Durchsatz, hoher Wartezeit und zu io.netty.handler.timeout.ReadTimeoutException-Fehlern führen. Wechseln Sie zur Problemumgehung den Thread, wenn Sie wissen, dass der Vorgang länger dauert.

Betrachten Sie beispielsweise den folgenden Codeschnipsel, in dem Elemente zu einem Container hinzugefügt werden. (Hier finden Sie eine Anleitung zum Einrichten der Datenbank und des Containers.) Möglicherweise wird im Netty-Thread eine Aufgabe ausgeführt, die mehr als nur ein paar Millisekunden dauert. In diesem Fall kann es vorkommen, dass für die Verarbeitung von E/A-Aufgaben kein Netty-E/A-Thread mehr vorhanden ist. Dies führt dann zu einem ReadTimeoutException-Fehler.

Java SDK V4 (Maven com.azure::azure-cosmos) Async-API


//Bad code with read timeout exception

int requestTimeoutInSeconds = 10;

/* ... */

AtomicInteger failureCount = new AtomicInteger();
// Max number of concurrent item inserts is # CPU cores + 1
Flux<Family> familyPub =
        Flux.just(Families.getAndersenFamilyItem(), Families.getAndersenFamilyItem(), Families.getJohnsonFamilyItem());
familyPub.flatMap(family -> {
    return container.createItem(family);
}).flatMap(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) {
    }
    return Mono.empty();
}).doOnError(Exception.class, exception -> {
    failureCount.incrementAndGet();
}).blockLast();
assert(failureCount.get() > 0);

Ändern Sie zur Problemumgehung den Thread für die Ausführung zeitaufwendiger Aufgaben. Definieren Sie eine Singletoninstanz des Schedulers für Ihre App.

Java SDK V4 (Maven com.azure::azure-cosmos) Async-API

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

Unter Umständen müssen zeitaufwendige Aufgaben (etwa rechenintensive Aufgaben oder blockierende E/A-Vorgänge) ausgeführt werden. Verlagern Sie den Thread in diesem Fall mithilfe der API .publishOn(customScheduler) auf einen durch customScheduler bereitgestellten Worker.

Java SDK V4 (Maven com.azure::azure-cosmos) Async-API

container.createItem(family)
        .publishOn(customScheduler) // Switches the thread.
        .subscribe(
                // ...
        );

Durch die Verwendung von publishOn(customScheduler) geben Sie den Netty-E/A-Thread frei und wechseln zu Ihrem eigenen benutzerdefinierten Thread, der vom benutzerdefinierten Scheduler bereitgestellt wird. Diese Änderung löst das Problem. Es treten keine Fehler vom Typ io.netty.handler.timeout.ReadTimeoutException mehr auf.

Anforderungsrate zu groß

Hierbei handelt es sich um einen serverseitigen Fehler. Er gibt an, dass Sie den bereitgestellten Durchsatz verbraucht haben. Wiederholen Sie den Vorgang zu einem späteren Zeitpunkt. Sollte dieser Fehler häufiger auftreten, empfiehlt sich unter Umständen eine Erhöhung des Sammlungsdurchsatzes.

Implementieren von Backoff in getRetryAfterInMilliseconds-Intervallen

Es empfiehlt sich, die Last während Leistungstests so lange erhöhen, bis eine geringe Menge von Anforderungen gedrosselt wird. Wenn es sich um eine gedrosselte Anwendung handelt, sollte die Clientanwendung für das vom Server angegebene Wiederholungsintervall aussetzen. Durch das Aussetzen wird die geringstmögliche Wartezeit zwischen den Wiederholungsversuchen gewährleistet.

Fehlerbehandlung über reaktive Java SDK-Kette

Die Fehlerbehandlung über das Azure Cosmos DB Java SDK ist wichtig, wenn es um die Anwendungslogik des Clients geht. Es gibt unterschiedliche, vom Reactor Core-Framework bereitgestellte Fehlerbehandlungsmechanismen, die in verschiedenen Szenarien verwendet werden können. Wir empfehlen Kunden, sich diese Fehlerbehandlungsoperatoren im Detail anzusehen und diejenigen zu verwenden, die am besten zu ihren Wiederholungslogikszenarien passen.

Wichtig

Von der Verwendung des Operators onErrorContinue() raten wir ab, weil er nicht in allen Szenarien unterstützt wird. Beachten Sie, dass onErrorContinue() ein spezieller Operator ist, der das Verhalten Ihrer reaktiven Kette unklar machen kann. Er wird nicht auf Downstreamoperatoren, sondern auf Upstreamoperatoren angewendet und erfordert spezifische Operatorunterstützung, damit er funktioniert. Außerdem kann es vorkommen, dass der Bereich in Upstreamelementen unerwartet in Bibliothekscode integriert wird, was zu unbeabsichtigtem Verhalten führt. Weitere Details zu diesem speziellen Operator finden Sie in der Dokumentation zu onErrorContinue().

Fehler beim Herstellen einer Verbindung mit dem Azure Cosmos DB-Emulator

Das HTTPS-Zertifikat des Azure Cosmos DB-Emulators ist selbstsigniert. Importieren Sie das Emulatorzertifikat in eine Java TrustStore-Instanz, damit das SDK mit dem Emulator verwendet werden kann. Weitere Informationen finden Sie unter Exportieren der Azure Cosmos DB-Emulatorzertifikate.

Probleme durch Abhängigkeitskonflikte

Das Azure Cosmos DB Java SDK umfasst zahlreiche Abhängigkeiten. Allgemein gilt, wenn Ihre Projektabhängigkeitsstruktur eine ältere Version eines Artefakts enthält, von dem das Azure Cosmos DB Java SDK abhängig ist, kann dies zu unerwarteten Fehlern beim Ausführen Ihrer Anwendung führen. Wenn Sie debuggen, warum Ihre Anwendung unerwartete Ausnahmen auslöst, sollten Sie sicherstellen, dass die Abhängigkeitsstruktur keine ältere Version einer oder mehrerer Abhängigkeiten des Azure Cosmos DB Java SDK miteinbezieht.

Zur Umgehung dieses Problems müssen Sie identifizieren, welche der Projektabhängigkeiten eine alte Version enthält, und die transitive Abhängigkeit für diese ältere Version ausschließen. Schließlich müssen Sie dem Azure Cosmos DB Java SDK erlauben, eine neuere Version zu verwenden.

Führen Sie den folgenden Befehl für Ihre Projektdatei „pom.xml“ aus, um zu identifizieren, welche Ihrer Projektabhängigkeiten eine ältere Version enthält:

mvn dependency:tree

Weitere Informationen finden Sie in der Anleitung zur Maven-Abhängigkeitsstruktur.

Sobald Sie wissen, welche Abhängigkeit Ihres Projekts von einer älteren Version abhängig ist, können Sie die Abhängigkeit von der Bibliothek in Ihrer pom-Datei ändern und die transitive Abhängigkeit ausschließen, indem Sie dem folgenden Beispiel folgen (im Beispiel wird davon ausgegangen, dass es sich bei der veralteten Abhängigkeit um reactor-core handelt):

<dependency>
  <groupId>${groupid-of-lib-which-brings-in-reactor}</groupId>
  <artifactId>${artifactId-of-lib-which-brings-in-reactor}</artifactId>
  <version>${version-of-lib-which-brings-in-reactor}</version>
  <exclusions>
    <exclusion>
      <groupId>io.projectreactor</groupId>
      <artifactId>reactor-core</artifactId>
    </exclusion>
  </exclusions>
</dependency>

Weitere Informationen finden Sie in der Anleitung zum Ausschließen transitiver Abhängigkeiten.

Aktivieren von Client-SDK-Protokollierung

Das Azure Cosmos DB Java SDK v4 verwendet SLF4j als Protokollierungsfassade, die die Anmeldung bei gängigen Protokollierungsframeworks wie log4j und logback unterstützt.

Wenn Sie beispielsweise log4j als Protokollierungsframework verwenden möchten, fügen Sie Ihrem Java-Klassenpfad die folgenden Bibliotheken hinzu:

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

Fügen Sie außerdem eine log4j-Konfiguration hinzu:

# this is a sample log4j configuration

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

log4j.category.com.azure.cosmos=INFO
#log4j.category.io.netty=OFF
#log4j.category.io.projectreactor=OFF
# 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

Weitere Informationen finden Sie im Leitfaden zur sfl4j-Protokollierung.

Netzwerkstatistiken des Betriebssystems

Führen Sie den Befehl „netstat“ aus, um einen Überblick darüber zu erhalten, wie viele Verbindungen sich im Zustand ESTABLISHED, CLOSE_WAIT usw. befinden.

Unter Linux können Sie den folgenden Befehl ausführen:

netstat -nap

Unter Windows können Sie denselben Befehl mit anderen Argumentflags ausführen:

netstat -abn

Filtern Sie das Ergebnis so, dass nur Verbindungen mit dem Azure Cosmos DB-Endpunkt angezeigt werden.

Die Anzahl von Verbindungen mit dem Azure Cosmos DB-Endpunkt im Zustand ESTABLISHED kann nicht höher sein als die Größe des konfigurierten Verbindungspools.

Viele Verbindungen mit dem Azure Cosmos DB-Endpunkt befinden sich möglicherweise im Zustand CLOSE_WAIT. Vielleicht sind es sogar mehr als 1.000. Eine so hohe Zahl deutet darauf hin, dass Verbindungen sehr schnell hergestellt und wieder getrennt werden. Das führt unter Umständen zu Problemen. Weitere Informationen finden Sie im Abschnitt Häufig auftretende Probleme und Problemumgehungen.

Häufige Probleme bei Abfragen

Anhand der Metriken zu Abfragen können Sie bestimmen, wo die Abfrage die meiste Zeit verbringt. An den Abfragemetriken können Sie erkennen, wie viel Zeit im Back-End und auf dem Client verbracht wird. Weitere Informationen finden Sie im Leitfaden zur Abfrageleistung.

Nächste Schritte

Weitere Informationen zu den Leistungsrichtlinien für das Java SDK v4
Weitere Informationen zu den bewährten Methoden für das Java SDK v4

Behandeln von Problemen bei der Verwendung des Azure Cosmos DB Java SDK v4 mit der API für NoSQL-Konten

Erfassen der Diagnosen

Datenbankvorgänge

Containervorgänge

Elementvorgänge

Abfragevorgänge

Azure Cosmos DB-Ausnahmen

Protokollieren der Diagnose

Definieren von benutzerdefinierten Diagnoseschwellenwerten

Definieren eines benutzerdefinierten Diagnosehandlers

Definieren von CosmosClientTelemetryConfig

Wiederholungsentwurf

Häufig auftretende Probleme und Problemumgehungen

Überprüfen der Metriken im Portal

Netzwerkprobleme, Netty-Lesetimeoutfehler, niedriger Durchsatz, hohe Latenz

Allgemeine Empfehlungen

Verbindungsdrosselung

Verbindungslimit auf einem Hostcomputer

Azure SNAT-Portauslastung (PAT)

Dienst nicht erreichbar – Firewall

UnknownHostException

HTTP-Proxy

Ungültiges Codierungsmuster: Blockieren eines Netty E/A-Threads

Java SDK V4 (Maven com.azure::azure-cosmos) Async-API

Java SDK V4 (Maven com.azure::azure-cosmos) Async-API

Java SDK V4 (Maven com.azure::azure-cosmos) Async-API

Anforderungsrate zu groß

Fehlerbehandlung über reaktive Java SDK-Kette

Fehler beim Herstellen einer Verbindung mit dem Azure Cosmos DB-Emulator

Probleme durch Abhängigkeitskonflikte

Aktivieren von Client-SDK-Protokollierung

Netzwerkstatistiken des Betriebssystems

Häufige Probleme bei Abfragen

Nächste Schritte

Zusätzliche Ressourcen