Share via

Ottimizzare le configurazioni di connessione per Azure Cosmos DB Java SDK v4

  • Articolo

SI APPLICA A: NoSQL

Importante

I suggerimenti sulle prestazioni riportati in questo articolo riguardano esclusivamente Azure Cosmos DB Java SDK v4. Per altre informazioni, vedere le note sulla versione di Azure Cosmos DB Java SDK v4, il repository Maven e la guida alla risoluzione dei problemi di Azure Cosmos DB Java SDK v4. Se attualmente si usa una versione precedente a v4, vedere l'articolo Eseguire la migrazione a Java SDK v4 per Azure Cosmos DB per informazioni sull'aggiornamento a v4.

Azure Cosmos DB è un database distribuito veloce e flessibile, facilmente scalabile e con latenza e velocità effettiva garantite. Non è necessario apportare modifiche significative all'architettura o scrivere codice complesso per ridimensionare il database con Azure Cosmos DB. Aumentare o ridurre le prestazioni è semplice come eseguire una singola chiamata API o una chiamata al metodo SDK. Tuttavia, dato che si accede ad Azure Cosmos DB tramite chiamate di rete, è possibile introdurre configurazioni di connessione per ottenere massime prestazioni durante l'uso di Azure Cosmos DB Java SDK v4.

Configurazione connessione

Nota

In Azure Cosmos DB Java SDK v4 la modalità diretta è la scelta ottimale per migliorare le prestazioni del database con la maggior parte dei carichi di lavoro.

Per altre informazioni sulle diverse opzioni di connettività, consultare l'articolo modalità di connettività.

Modalità di connessione diretta

La modalità di connessione predefinita di Java SDK è diretta. Le richieste in modalità diretta di Azure Cosmos DB vengono effettuate tramite TCP quando si usa Azure Cosmos DB Java SDK v4. Internamente Modalità diretta usa un'architettura speciale in modalità diretta per gestire le risorse di rete in modo dinamico e ottenere prestazioni ottimali. L'architettura sul lato client usata in modalità diretta consente l'utilizzo di rete prevedibile e l'accesso in multiplex alle repliche di Azure Cosmos DB. Per altre informazioni sull'architettura, vedere architettura di connessione in modalità diretta.

È possibile configurare la modalità di connessione nel generatore client usando il metodo directMode() come illustrato di seguito. Per configurare la modalità diretta con le impostazioni predefinite, chiamare il metodo directMode() senza argomenti. Per personalizzare le impostazioni di connessione in modalità diretta, eseguire il passaggio di DirectConnectionConfig all'API directMode().

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


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

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

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

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

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

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

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

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

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

Personalizzazione della modalità di connessione diretta

Se si desidera un comportamento in modalità diretta non predefinita, creare un'istanza DirectConnectionConfig e personalizzarne le relative proprietà, passare l'istanza della proprietà personalizzata al metodo directMode() nel generatore client di Azure Cosmos DB.

Queste impostazioni di configurazione controllano il comportamento dell'architettura della modalità diretta sottostante descritta in precedenza.

Come primo passaggio, usare le seguenti impostazioni di configurazione consigliate. Queste opzioni di DirectConnectionConfig sono impostazioni di configurazione avanzate che possono influire sulle prestazioni dell'SDK in modi imprevisti. È consigliabile evitare di modificarle, a meno che non si ritengano utili per comprenderne i vantaggi e gli svantaggi e la modifica non sia assolutamente necessaria. In caso di problemi relativi a questo particolare argomento, contattare il team di Azure Cosmos DB.

Opzione di configurazione Default Consigliato Dettagli
idleConnectionTimeout "PT0" (ZERO) "PT0" (ZERO) Rappresenta la durata del timeout di connessione inattiva per una singola connessione a un nodo endpoint/back-end (che rappresenta una replica). Per impostazione predefinita, SDK non chiude automaticamente le connessioni inattive ai nodi back-end.
idleEndpointTimeout "PT1H" "PT1H" Rappresenta la durata del timeout di connessione inattiva per il pool di connessioni per un nodo endpoint/back-end (che rappresenta una replica). Per impostazione predefinita, se non sono presenti richieste in ingresso a un nodo endpoint/back-end specifico, l'SDK chiuderà tutte le connessioni nel pool di connessioni a tale nodo endpoint/back-end dopo 1 ora per risparmiare risorse di rete e costi di I/O. Per il modello di traffico sparse o sporadico, è consigliabile impostare questo valore su un numero superiore, ad esempio 6 ore, 12 ore o persino 24 ore, in modo che l'SDK non dovrà aprire frequentemente le connessioni. Tuttavia, esso utilizzerà le risorse di rete e avrà un numero maggiore di connessioni mantenute aperte in qualsiasi momento. Se è impostato su ZERO, il controllo dell'endpoint inattivo verrà disabilitato.
maxConnectionsPerEndpoint "130" "130" Rappresenta le dimensioni superiori del pool di connessioni per un nodo endpoint/back-end (che rappresenta una replica). L'SDK crea connessioni al nodo endpoint/back-end su richiesta e in base alle richieste simultanee in ingresso. Per impostazione predefinita, se necessario, l’SDK creerà al massimo 130 connessioni a un nodo endpoint/back-end. (NOTA: l’SDK non crea queste 130 connessioni in anticipo).
maxRequestsPerConnection 30 30 Rappresenta la dimensione superiore del limite massimo del numero massimo di richieste che possono essere accodate in una singola connessione per un nodo endpoint/back-end specifico (che rappresenta una replica). L'SDK accoda le richieste a una singola connessione a un nodo endpoint/back-end su richiesta e in base alle richieste simultanee in ingresso. Per impostazione predefinita, se necessario, l'SDK accoderà al massimo 30 richieste a una singola connessione per un nodo endpoint/back-end specifico. (NOTA: l’SDK non accoda queste 30 richieste a una singola connessione in anticipo.)
connectTimeout "PT5S" "~PT1S" Rappresenta la durata del timeout di definizione della connessione per stabilire una singola connessione con un nodo endpoint/back-end. Per impostazione predefinita, l'SDK attenderà un massimo di 5 secondi per stabilire la connessione prima di generare un errore. L'istituzione della connessione TCP utilizza handshake in più passaggi che aumenta la latenza del tempo di definizione della connessione, pertanto si consiglia ai clienti di impostare questo valore in base alle impostazioni della larghezza di banda di rete e dell'ambiente. NOTA: questa raccomandazione relativa a ~PT1S è destinata solo alle applicazioni distribuite in aree con percorso condiviso degli account Cosmos DB.
networkRequestTimeout "PT5S" "PT5S" Rappresenta la durata del timeout di rete per una singola richiesta. L'SDK attenderà il tempo massimo per usare una risposta al servizio dopo che la richiesta è stata scritta nella connessione di rete. L'SDK consente solo valori compresi tra 1 secondo (min) e 10 secondi (max). L'impostazione di un valore troppo alto può comportare un minor numero di tentativi e ridurre le probabilità di successo tramite tentativi.

Modalità di connessione gateway

Le operazioni del piano di controllo, ad esempio il database e il contenitore CRUD, utilizzano sempre la modalità Gateway. Anche quando l'utente ha configurato la modalità diretta per le operazioni del piano dati, il piano di controllo e le operazioni sui metadati utilizzano le impostazioni predefinite della modalità gateway. Questo si adatta alla maggior parte degli utenti. Tuttavia, gli utenti che desiderano la modalità diretta per le operazioni del piano dati e la ottimizzabilità dei parametri della modalità gateway del piano di controllo possono usare l'override directMode() seguente:

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


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

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

GatewayConnectionConfig gatewayConnectionConfig = GatewayConnectionConfig.getDefaultConfig();

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

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

Personalizzazione della modalità di connessione del gateway

Se si desidera un comportamento della modalità gateway non predefinito, creare un'istanza GatewayConnectionConfig e personalizzare le relative proprietà, passare l'istanza della proprietà personalizzata al metodo di override directMode() precedente o al metodo gatewayMode() nel generatore client di Azure Cosmos DB.

Come primo passaggio, usare le seguenti impostazioni di configurazione consigliate. Queste opzioni di GatewayConnectionConfig sono impostazioni di configurazione avanzate che possono influire sulle prestazioni dell'SDK in modi imprevisti. È consigliabile evitare di modificarle, a meno che non si ritengano utili per comprenderne i vantaggi e gli svantaggi e la modifica non sia assolutamente necessaria. In caso di problemi relativi a questo particolare argomento, contattare il team di Azure Cosmos DB.

Opzione di configurazione Default Consigliato Dettagli
maxConnectionPoolSize "1000" "1000" Rappresenta le dimensioni superiori del pool di connessioni per il client HTTP sottostante, ovvero il numero massimo di connessioni create dall'SDK per le richieste che passano alla modalità Gateway. L'SDK riutilizza queste connessioni quando si inviano richieste al Gateway.
idleConnectionTimeout "PT60S" "PT60S" Rappresenta la durata del timeout di connessione inattiva per una singola connessione al Gateway. Dopo questa volta, la connessione verrà chiusa automaticamente e verrà rimossa dal pool di connessioni.

Passaggi successivi

Per altre informazioni relative ai suggerimenti sulle prestazioni per Java SDK, vedere Suggerimenti per le prestazioni di Java SDK v4 per Azure Cosmos DB.

Per altre informazioni sulla progettazione dell'applicazione per scalabilità e prestazioni elevate, vedere l'articolo relativo a partizionamento e ridimensionamento in Azure Cosmos DB.

Si sta tentando di pianificare la capacità per una migrazione ad Azure Cosmos DB? È possibile usare le informazioni del cluster di database esistente per la pianificazione della capacità.