Otimizar configurações de ligação para o SDK Java v4 do Azure Cosmos DB

  • Artigo

APLICA-SE A: NoSQL

Importante

As sugestões de desempenho neste artigo destinam-se apenas ao SDK Java v4 do Azure Cosmos DB. Veja as Notas de versão do SDK Java v4 do Azure Cosmos DB, o repositório Maven e o Guia de resolução de problemas do SDK Java v4 do Azure Cosmos DB para obter mais informações. Se estiver a utilizar uma versão mais antiga do que a v4, veja o guia Migrar para o SDK Java v4 do Azure Cosmos DB para obter ajuda na atualização para v4.

O Azure Cosmos DB é uma base de dados distribuída rápida e flexível que dimensiona perfeitamente com latência e débito garantidos. Não tem de fazer grandes alterações à arquitetura nem escrever código complexo para dimensionar a base de dados com o Azure Cosmos DB. Aumentar e reduzir verticalmente é tão fácil como fazer uma única chamada à API ou chamada ao método SDK. No entanto, como o Azure Cosmos DB é acedido através de chamadas de rede, existem configurações de ligação que pode otimizar para alcançar o pico de desempenho ao utilizar o SDK Java v4 do Azure Cosmos DB.

Configuração da ligação

Nota

No SDK Java v4 do Azure Cosmos DB, o modo Direto é a melhor opção para melhorar o desempenho da base de dados com a maioria das cargas de trabalho.

Para saber mais sobre as diferentes opções de conectividade, veja o artigo Modos de conectividade .

Modo de ligação direta

O modo de ligação predefinido do SDK Java é direto. No modo direto, os pedidos do Azure Cosmos DB são feitos através de TCP ao utilizar o SDK Java v4 do Azure Cosmos DB. O modo Direto internamente utiliza uma arquitetura especial para gerir dinamicamente os recursos de rede e obter o melhor desempenho. A arquitetura do lado do cliente utilizada no modo Direto permite a utilização previsível da rede e o acesso multiplexado às réplicas do Azure Cosmos DB. Para saber mais sobre a arquitetura, veja a arquitetura de ligação do modo direto

Pode configurar o modo de ligação no construtor de clientes com o método directMode(), conforme mostrado abaixo. Para configurar o modo direto com predefinições, chame o directMode() método sem argumentos. Para personalizar as definições de ligação do modo direto, transmita DirectConnectionConfig para a 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();

Personalizar o modo de ligação direta

Se o comportamento não predefinido do modo Direto for pretendido, crie uma instância DirectConnectionConfig e personalize as respetivas propriedades e, em seguida, transmita a instância de propriedade personalizada para o método directMode() no construtor de cliente do Azure Cosmos DB.

Estas definições de configuração controlam o comportamento da arquitetura do modo Direto subjacente abordada acima.

Como primeiro passo, utilize as seguintes definições de configuração recomendadas abaixo. Estas opções directConnectionConfig são definições de configuração avançadas que podem afetar o desempenho do SDK de formas inesperadas; recomendamos que os utilizadores evitem modificá-los, a menos que se sintam muito confortáveis em compreender as desvantagens e seja absolutamente necessário. Contacte a equipa do Azure Cosmos DB se se deparar com problemas neste tópico específico.

Opção de configuração Predefinição Recomendado Detalhes
idleConnectionTimeout "PT0" (ZERO) "PT0" (ZERO) Isto representa a duração do tempo limite da ligação inativa para uma única ligação a um nó de ponto final/back-end (que representa uma réplica). Por predefinição, o SDK não fecha automaticamente as ligações inativas aos nós de back-end.
idleEndpointTimeout "PT1H" "PT1H" Isto representa a duração do tempo limite da ligação inativa para o conjunto de ligações para um nó de ponto final/back-end (que representa uma réplica). Por predefinição, se não existirem pedidos recebidos para um nó de ponto final/back-end específico, o SDK fechará todas as ligações no conjunto de ligações para esse nó de ponto final/back-end após 1 hora para poupar recursos de rede e custos de E/S. Para um padrão de tráfego disperso ou esporádico, recomendamos que defina este valor para um número mais elevado, como 6 horas, 12 horas ou mesmo 24 horas, para que o SDK não tenha de abrir as ligações com frequência. No entanto, isto irá utilizar os recursos de rede e terá um maior número de ligações mantidas abertas a qualquer momento. Se estiver definido como ZERO, a verificação do ponto final inativo será desativada.
maxConnectionsPerEndpoint "130" "130" Isto representa o tamanho superior vinculado do conjunto de ligações para um nó de ponto final/back-end (que representa uma réplica). O SDK cria ligações para o nó de ponto final/back-end a pedido e com base em pedidos simultâneos recebidos. Por predefinição, se necessário, o SDK criará um máximo de 130 ligações a um nó de ponto final/back-end. (NOTA: o SDK não cria estas 130 ligações antecipadamente).
maxRequestsPerConnection "30" "30" Isto representa o tamanho limite superior do número máximo de pedidos que podem ser colocados em fila numa única ligação para um nó de ponto final/back-end específico (que representa uma réplica). O SDK coloca em fila pedidos para uma única ligação a um nó de ponto final/back-end a pedido e com base em pedidos simultâneos recebidos. Por predefinição, se necessário, o SDK colocará em fila o máximo de 30 pedidos para uma única ligação para um nó de ponto final/back-end específico. (NOTA: o SDK não coloca em fila estes 30 pedidos para uma única ligação antecipadamente).
connectTimeout "PT5S" "~PT1S" Isto representa a duração do tempo limite do estabelecimento da ligação para que uma única ligação seja estabelecida com um nó de ponto final/back-end. Por predefinição, o SDK aguardará um máximo de 5 segundos para o estabelecimento da ligação antes de gerar um erro. O estabelecimento de ligação TCP utiliza um handshake de vários passos , o que aumenta a latência do tempo de estabelecimento da ligação, pelo que os clientes são recomendados para definir este valor de acordo com as definições de largura de banda de rede e ambiente. NOTA: esta recomendação de ~PT1S destina-se apenas a aplicações implementadas em regiões colocalizados das respetivas contas do Cosmos DB.
networkRequestTimeout "PT5S" "PT5S" Isto representa a duração do tempo limite da rede para um único pedido. O SDK aguardará o máximo por esta duração para consumir uma resposta de serviço depois de o pedido ter sido escrito na ligação de rede. O SDK só permite valores entre 1 segundo (min) e 10 segundos (máx.). Definir um valor demasiado alto pode resultar em menos repetições e reduzir as hipóteses de êxito por tentativas.

Modo de Ligação do Gateway

As operações do plano de controlo, como a base de dados e o CONTENTOR CRUD, utilizam sempre o Modo de gateway. Mesmo quando o utilizador tiver configurado o Modo direto para operações do plano de dados, o plano de controlo e as operações de metadados utilizam as predefinições do modo de Gateway. Isto é adequado para a maioria dos utilizadores. No entanto, os utilizadores que pretendam o Modo direto para operações do plano de dados, bem como a atumbilidade dos parâmetros do modo de gateway do plano de controlo, podem utilizar a seguinte substituição de directMode( ):

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

Personalizar o modo de ligação do gateway

Se o comportamento do modo de Gateway não predefinido for pretendido, crie uma instância GatewayConnectionConfig e personalize as respetivas propriedades e, em seguida, transmita a instância de propriedade personalizada para o método de substituição directMode() acima ou o método gatewayMode() no construtor de cliente do Azure Cosmos DB.

Como primeiro passo, utilize as seguintes definições de configuração recomendadas abaixo. Estas opções de GatewayConnectionConfig são definições de configuração avançadas que podem afetar o desempenho do SDK de formas inesperadas; recomendamos que os utilizadores evitem modificá-los, a menos que se sintam muito confortáveis em compreender as desvantagens e seja absolutamente necessário. Contacte a equipa do Azure Cosmos DB se se deparar com problemas neste tópico específico.

Opção de configuração Predefinição Recomendado Detalhes
maxConnectionPoolSize "1000" "1000" Isto representa o tamanho superior vinculado do tamanho do conjunto de ligações para o cliente http subjacente, que é o número máximo de ligações que o SDK irá criar para pedidos que vão para o modo de Gateway. O SDK reutiliza estas ligações ao enviar pedidos para o Gateway.
idleConnectionTimeout "PT60S" "PT60S" Isto representa a duração de tempo limite da ligação inativa para uma única ligação ao Gateway. Após esta hora, a ligação será fechada automaticamente e será removida do conjunto de ligações.

Passos seguintes

Para saber mais sobre as sugestões de desempenho do SDK Java, veja Sugestões de desempenho para o SDK Java v4 do Azure Cosmos DB.

Para saber mais sobre como conceber a sua aplicação para dimensionamento e elevado desempenho, veja Criação de partições e dimensionamento no Azure Cosmos DB.

Está a tentar planear a capacidade de uma migração para o Azure Cosmos DB? Pode utilizar informações sobre o cluster de bases de dados existentes para o planeamento de capacidade.