Optimieren von Verbindungskonfigurationen für das Azure Cosmos DB Java SDK v4

  • Artikel

GILT FÜR: NoSQL

Wichtig

Die Leistungstipps in diesem Artikel gelten ausschließlich für das Azure Cosmos DB Java SDK v4. Weitere Informationen finden Sie in den Versionshinweisen zum Azure Cosmos DB Java SDK v4, im Maven-Repository und im Leitfaden zur Problembehandlung für das Azure Cosmos DB Java SDK v4. Wenn Sie aktuell eine ältere Version als v4 verwenden, lesen Sie den Leitfaden Migrieren zum Azure Cosmos DB Java SDK v4, um Hilfe beim Upgrade auf v4 zu erhalten.

Azure Cosmos DB ist eine schnelle und flexible verteilte Datenbank mit nahtloser Skalierung, garantierter Latenz und garantiertem Durchsatz. Die Skalierung Ihrer Datenbank mit Azure Cosmos DB erfordert weder aufwendige Änderungen an der Architektur noch das Schreiben von komplexem Code. Zentrales Hoch- und Herunterskalieren ist ebenso problemlos möglich wie das Aufrufen einer einzelnen API oder SDK-Methode. Da der Zugriff auf Azure Cosmos DB jedoch über Netzwerkaufrufe erfolgt, können Sie bei der Verwendung des Azure Cosmos DB Java SDK v4 Verbindungskonfigurationen optimieren, um eine optimale Leistung zu erzielen.

Verbindungskonfiguration

Hinweis

Im Azure Cosmos DB Java SDK v4 ist der direkte Modus die beste Wahl, um die Datenbankleistung bei den meisten Workloads zu verbessern.

Weitere Informationen zu verschiedenen Konnektivitätsoptionen finden Sie im Artikel zu den Konnektivitätsmodi.

Direkter Verbindungsmodus

Als Standardverbindungsmodus des Java SDK wird der direkte Modus verwendet. Bei Verwendung des Azure Cosmos DB Java SDK v4 erfolgen Azure Cosmos DB-Anforderungen im direkten Modus über TCP. Intern verwendet der direkte Modus eine spezielle Architektur, um Netzwerkressourcen dynamisch zu verwalten und die beste Leistung zu erzielen. Die clientseitige Architektur, die im direkten Modus eingesetzt wird, ermöglicht vorhersagbare Netzwerkauslastungen und Multiplexzugriff auf Azure Cosmos DB-Replikate. Weitere Informationen zur Architektur finden Sie unter Verbindungsarchitektur im direkten Modus.

Sie können den Verbindungsmodus im Clientgenerator mithilfe der Methode directMode() wie unten gezeigt konfigurieren. Um den direkten Modus mit den Standardeinstellungen zu konfigurieren, rufen Sie die Methode directMode() ohne Argumente auf. Zum Anpassen von Verbindungseinstellungen im direkten Modus übergeben Sie DirectConnectionConfig an die directMode()-API.

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


/* 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();

Anpassen des direkten Verbindungsmodus

Wenn ein nicht standardmäßiges Verhalten beim direkten Modus gewünscht ist, erstellen Sie eine DirectConnectionConfig-Instanz, passen Sie deren Eigenschaften an, und übergeben Sie die angepasste Eigenschafteninstanz dann an die Methode directMode() im Azure Cosmos DB-Client-Generator.

Diese Konfigurationseinstellungen steuern das Verhalten der zugrunde liegenden Architektur des weiter oben behandelten direkten Modus.

Verwenden Sie als ersten Schritt die folgenden empfohlenen Konfigurationseinstellungen. Diese DirectConnectionConfig-Optionen sind erweiterte Konfigurationseinstellungen, die sich auf unerwartete Weise auf die SDK-Leistung auswirken können. Es wird empfohlen, dass Benutzer diese nicht ändern, es sei denn, sie kennen die möglichen Auswirkungen und dies ist absolut notwendig. Wenden Sie sich an das Azure Cosmos DB-Team, wenn Sie mit diesem speziellen Thema Probleme haben.

Konfigurationsoption Standard Empfohlen Details
idleConnectionTimeout „PT0“ (NULL) „PT0“ (NULL) Dies bezeichnet die Dauer des Verbindungstimeouts bei Leerlauf für eine einzelne Verbindung mit einem Endpunkt/Back-End-Knoten (der ein Replikat darstellt). Standardmäßig schließt das SDK Verbindungen mit den Back-End-Knoten im Leerlauf nicht automatisch.
idleEndpointTimeout „PT1H“ „PT1H“ Dies bezeichnet die Dauer des Verbindungstimeouts bei Leerlauf für den Verbindungspool für einen Endpunkt/Back-End-Knoten (der ein Replikat darstellt). Wenn keine Anforderungen an einem bestimmten Endpunkt/Back-End-Knoten eingehen, schließt das SDK standardmäßig nach einer Stunde alle Verbindungen im Verbindungspool mit diesem Endpunkt/Back-End-Knoten, um Netzwerkressourcen und E/A-Kosten zu sparen. Bei einem Muster mit geringem oder sporadischem Datenverkehr wird empfohlen, diesen Wert auf eine höhere Zahl wie 6 Stunden, 12 Stunden oder sogar 24 Stunden festzulegen, damit das SDK die Verbindungen nicht so häufig öffnen muss. Dies beansprucht jedoch die Netzwerkressourcen und führt zu einer höheren Anzahl von Verbindungen, die zu einem bestimmten Zeitpunkt geöffnet bleiben. Wenn dieser Wert auf NULL festgelegt ist, wird die Überprüfung des Endpunkts im Leerlauf deaktiviert.
maxConnectionsPerEndpoint „130“ „130“ Dies bezeichnet die Obergrenze für die Größe des Verbindungspools für einen Endpunkt/Back-End-Knoten (der ein Replikat darstellt). Das SDK erstellt Verbindungen mit dem Endpunkt-/Back-End-Knoten nach Bedarf und basierend auf eingehenden gleichzeitigen Anforderungen. Standardmäßig erstellt das SDK bei Bedarf maximal 130 Verbindungen mit einem Endpunkt/Back-End-Knoten. (HINWEIS: Das SDK erstellt diese 130 Verbindungen nicht im Voraus.)
maxRequestsPerConnection „30“ „30“ Dies bezeichnet die Obergrenze für die maximalen Anzahl von Anforderungen, die bei einer einzelnen Verbindung für einen bestimmten Endpunkt/Back-End-Knoten (der ein Replikat darstellt) in die Warteschlange gestellt werden können. Das SDK stellt Anforderungen an eine einzelne Verbindung mit einem Endpunkt/Back-End-Knoten nach Bedarf und basierend auf eingehenden gleichzeitigen Anforderungen in die Warteschlange. Standardmäßig stellt das SDK bei Bedarf maximal 30 Anforderungen an eine einzelne Verbindung für einen bestimmten Endpunkt/Back-End-Knoten in die Warteschlange. (HINWEIS: Das SDK stellt diese 30 Anforderungen für eine einzelne Verbindung nicht im Voraus in die Warteschlange.)
connectTimeout „PT5S“ „~PT1S“ Dies bezeichnet die Dauer des Timeouts bei der Verbindungsherstellung für eine einzelne Verbindung, die mit einem Endpunkt/Back-End-Knoten hergestellt werden soll. Standardmäßig wartet das SDK maximal fünf Sekunden auf die Verbindungsherstellung, bevor ein Fehler ausgelöst wird. Die TCP-Verbindungsherstellung verwendet einen mehrstufigen Handshake, der die Latenzzeit der Verbindungsherstellung erhöht. Daher wird Kunden empfohlen, diesen Wert entsprechend ihrer Netzwerkbandbreite und den Umgebungseinstellungen festzulegen. HINWEIS: Diese Empfehlung von ~PT1S gilt nur für Anwendungen, die in verbundenen Regionen ihrer Cosmos DB-Konten bereitgestellt werden.
networkRequestTimeout „PT5S“ „PT5S“ Dies bezeichnet die Dauer des Netzwerktimeouts für eine einzelne Anforderung. Das SDK wartet maximal über diese Zeitspanne, um eine Dienstantwort zu nutzen, nachdem die Anforderung in die Netzwerkverbindung geschrieben wurde. Das SDK lässt nur Werte zwischen einer Sekunde (Minimum) und zehn Sekunden (Maximum) zu. Das Festlegen eines zu hohen Werts kann zu weniger Wiederholungen führen und die Erfolgschancen durch Wiederholungen verringern.

Gatewayverbindungsmodus

Vorgänge auf Steuerungsebene, z. B. Datenbank- und Container-CRUD, verwenden immer den Gatewaymodus. Selbst wenn der Benutzer den direkten Modus für Vorgänge auf Datenebene konfiguriert hat, verwenden Vorgänge auf Steuerungsebene und Metadatenvorgänge die Standardeinstellungen für den Gatewaymodus. Dies ist für die meisten Benutzer geeignet. Benutzer, die den direkten Modus für Datenebenenvorgänge verwenden und Gatewaymodusparameter anpassen möchten, können jedoch die folgenden directMode() -Außerkraftsetzung verwenden:

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


/* 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();

Anpassen des Gatewayverbindungsmodus

Wenn ein nicht standardmäßiges Verhalten beim Gatewaymodus gewünscht ist, erstellen Sie eine GatewayConnectionConfig-Instanz. Passen Sie deren Eigenschaften an, und übergeben Sie die angepasste Eigenschafteninstanz dann an die oben aufgeführte Überschreibungsmethode directMode() oder die Methode gatewayMode() im Azure Cosmos DB-Clientgenerator.

Verwenden Sie als ersten Schritt die folgenden empfohlenen Konfigurationseinstellungen. Diese GatewayConnectionConfig-Optionen sind erweiterte Konfigurationseinstellungen, die sich auf unerwartete Weise auf die SDK-Leistung auswirken können. Es wird empfohlen, dass Benutzer diese nicht ändern, es sei denn, sie kennen die möglichen Auswirkungen und dies ist absolut notwendig. Wenden Sie sich an das Azure Cosmos DB-Team, wenn Sie mit diesem speziellen Thema Probleme haben.

Konfigurationsoption Standard Empfohlen Details
maxConnectionPoolSize "1000" "1000" Dies bezeichnet die Obergrenze für die Größe des Verbindungspools für den zugrunde liegenden HTTP-Client, d. h. die maximale Anzahl von Verbindungen, die das SDK für Anfragen im Gatewaymodus erstellt. Das SDK verwendet diese Verbindungen beim Senden von Anforderungen an das Gateway erneut.
idleConnectionTimeout „PT60S“ „PT60S“ Dies bezeichnet die Dauer des Verbindungstimeouts bei Leerlauf für eine einzelne Verbindung mit dem Gateway. Nach dieser Zeitspanne wird die Verbindung automatisch geschlossen und aus dem Verbindungspool entfernt.

Nächste Schritte

Weitere Informationen zu Leistungstipps für das Java SDK finden Sie unter Leistungstipps für das Azure Cosmos DB Java SDK v4.

Weitere Informationen zum Entwerfen einer auf Skalierung und hohe Leistung ausgelegten Anwendung finden Sie unter Partitionieren und Skalieren in Azure Cosmos DB.

Versuchen Sie, die Kapazitätsplanung für eine Migration zu Azure Cosmos DB durchzuführen? Sie können Informationen zu Ihrem vorhandenen Datenbankcluster für die Kapazitätsplanung verwenden.