Ajustar as configurações de conexão para o SDK do Java v4 do Azure Cosmos DB

  • Artigo

APLICA-SE A: NoSQL

Importante

As dicas de desempenho neste artigo são apenas para o SDK do Java v4 do Azure Cosmos DB. Confira as Notas sobre a versão do SDK do Java v4 do Azure Cosmos DB, o repositório do Maven, o Guia de solução de problemas do SDK do Java v4 do Azure Cosmos DB para saber mais. Se você estiver usando uma versão mais antiga do que a v4, confira o guia Migrar para o SDK do Java v4 do Azure Cosmos DB para obter ajuda na atualização para a v4.

O Azure Cosmos DB é um banco de dados distribuído rápido e flexível que pode ser dimensionado perfeitamente com garantia de latência e produtividade. Você não precisa fazer alterações importantes de arquitetura nem escrever um código complexo para dimensionar seu banco de dados com o Azure Cosmos DB. Aumentar e reduzir é tão fácil quanto fazer uma única chamada à API ou uma chamada ao método do SDK. No entanto, como o Azure Cosmos DB é acessado por meio de chamadas de rede, há configurações de conexão que você pode ajustar para obter o desempenho máximo ao usar o SDK do Java v4 do Azure Cosmos DB.

Configuração de conexão

Observação

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

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

Modo de conexão direta

O modo de conexão padrão do SDK do Java é direto. As solicitações do Azure Cosmos DB do modo Direto são feitas por TCP quando o SDK do Java v4 do Azure Cosmos DB é usado. Internamente, o modo direto usa uma arquitetura especial para gerenciar dinamicamente os recursos de rede e obter o melhor desempenho. A arquitetura do lado do cliente empregada no modo direto permite a utilização de rede previsível e o acesso multiplexado a réplicas do Azure Cosmos DB. Para saber mais sobre arquitetura, confira a arquitetura de conexão do modo direto

Você pode configurar o modo de conexão no construtor de cliente usando o método directMode(), conforme mostrado abaixo. Para configurar o modo direto com as configurações padrão, chame o método directMode() sem argumentos. Para personalizar as configurações de conexão do modo direto, passe DirectConnectionConfig para a API directMode().

API assíncrona do SDK do Java 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();

Personalizando o modo de conexão direta

Se o comportamento de modo direto não padrão for desejado, crie uma instância DirectConnectionConfig e personalize as propriedades dela. Em seguida, passe a instância de propriedade personalizada para o método directMode() no construtor de cliente do Azure Cosmos DB.

Essas definições de configuração controlam o comportamento da arquitetura de modo direto subjacente discutida acima.

Como uma primeira etapa, use as definições de configuração recomendadas abaixo. Essas opções de DirectConnectionConfig são definições avançadas de configuração que podem afetar o desempenho do SDK de maneiras inesperadas; recomendamos que os usuários evitem modificá-los, a menos que entendam perfeitamente os riscos e as compensações e se for absolutamente necessário. Entre em contato com a equipe do Azure Cosmos DB se você encontrar problemas neste tópico específico.

Opções de configuração Padrão Recomendadas Detalhes
idleConnectionTimeout "PT0" (ZERO) "PT0" (ZERO) Isso representa a duração do tempo limite de conexão ociosa para uma única conexão a um nó de ponto de extremidade/back-end (representando uma réplica). Por padrão, o SDK não fecha automaticamente as conexões ociosas aos nós de back-end.
idleEndpointTimeout "PT1H" "PT1H" Isso representa a duração do tempo limite de conexão ociosa para o pool de conexões para um nó de ponto de extremidade/back-end (representando uma réplica). Por padrão, se não houver solicitações de entrada para um nó de ponto de extremidade/back-end específico, o SDK fechará todas as conexões no pool de conexões a esse nó de ponto de extremidade/back-end após 1 hora para economizar recursos de rede e custo de E/S. Para o padrão de tráfego esparso ou esporádico, recomendamos definir esse valor como um número maior, como 6 horas, 12 horas ou até 24 horas, para que o SDK não precise abrir as conexões com frequência. No entanto, isso utilizará os recursos de rede e terá um número maior de conexões mantidas abertas a qualquer momento. Se isso for definido como ZERO, a verificação de ponto de extremidade ocioso será desabilitada.
maxConnectionsPerEndpoint "130" "130" Isso representa o tamanho do limite superior do pool de conexões para um nó de ponto de extremidade/back-end (representando uma réplica). O SDK cria conexões com o nó de ponto de extremidade/back-end sob demanda e com base em solicitações simultâneas de entrada. Por padrão, se necessário, o SDK criará no máximo 130 conexões a um nó de ponto de extremidade/back-end. (OBSERVAÇÃO: o SDK não cria essas 130 conexões antecipadamente).
maxRequestsPerConnection "30" "30" Isso representa o tamanho do limite superior do número máximo de solicitações que podem ser enfileiradas em uma única conexão para um nó de ponto de extremidade/back-end específico (representando uma réplica). O SDK enfileira solicitações para uma única conexão a um nó de ponto de extremidade/back-end sob demanda e com base em solicitações simultâneas de entrada. Por padrão, se necessário, o SDK enfileirará no máximo 30 solicitações para uma única conexão a um nó de ponto de extremidade/back-end específico. (OBSERVAÇÃO: o SDK não enfileira essas 30 solicitações para uma única conexão antecipadamente).
connectTimeout "PT5S" "~PT1S" Isso representa a duração do tempo limite do estabelecimento da conexão para que uma única conexão seja estabelecida a um nó de ponto de extremidade/back-end. Por padrão, o SDK aguardará no máximo 5 segundos para o estabelecimento da conexão antes de gerar um erro. O estabelecimento da conexão TCP usa handshake de várias etapas, o que aumenta a latência do tempo de estabelecimento da conexão, sendo, portanto, recomendável que os clientes definam esse valor de acordo com a largura de banda de rede e as configurações de ambiente. OBSERVAÇÃO: esta recomendação de ~PT1S é apenas para aplicativos implantados em regiões colocadas de suas contas do Cosmos DB.
networkRequestTimeout "PT5S" "PT5S" Isso representa a duração do tempo limite da rede para uma única solicitação. O SDK aguardará o máximo por essa duração para consumir uma resposta de serviço depois que a solicitação tiver sido gravada na conexão de rede. O SDK permite apenas valores entre 1 segundo (mínimo) e 10 segundos (máximo). Definir um valor alto demais pode resultar em uma quantidade menor de novas tentativas e reduzir as chances de sucesso por novas tentativas.

Modo de conexão de gateway

As operações do painel de controle, como o banco de dados e o contêiner CRUD sempre utilizam o modo gateway. Mesmo quando o usuário tiver configurado o modo Direto para operações do plano de dados, o painel de controle e as operações de metadados usarão configurações padrão do modo Gateway. Isso é adequado para a maioria dos usuários. No entanto, os usuários que desejam o modo direto para operações de plano de dados, bem como ajustabilidade de parâmetros do modo de gateway do painel de controle, podem usar a seguinte substituição directMode() :

API assíncrona do SDK do Java 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();

Personalizar o modo de conexão Gateway

Se o comportamento de modo Gateway não padrão for desejado, crie uma instância GatewayConnectionConfig e personalize as propriedades dela. Em seguida, passe 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 uma primeira etapa, use as definições de configuração recomendadas abaixo. Essas opções de GatewayConnectionConfig são definições avançadas de configuração que podem afetar o desempenho do SDK de maneiras inesperadas; recomendamos que os usuários evitem modificá-los, a menos que entendam perfeitamente os riscos e as compensações e se for absolutamente necessário. Entre em contato com a equipe do Azure Cosmos DB se você encontrar problemas neste tópico específico.

Opções de configuração Padrão Recomendadas Detalhes
maxConnectionPoolSize "1000" "1000" Isso representa o tamanho do limite superior do tamanho do pool de conexões para o cliente http subjacente, que é o número máximo de conexões que o SDK criará para solicitações que vão para o modo Gateway. O SDK reutiliza essas conexões ao enviar solicitações para o Gateway.
idleConnectionTimeout "PT60S" "PT60S" Isso representa a duração do tempo limite de conexão ociosa para uma única conexão ao Gateway. Após esse tempo, a conexão será fechada automaticamente e será removida do pool de conexões.

Próximas etapas

Para conhecer mais dicas de desempenho para o SDK do Java, confira Dicas de desempenho para o SDK do Java v4 do Azure Cosmos DB.

Para saber mais sobre como projetar seu aplicativo para escala e alto desempenho, consulte Particionamento e escala no Azure Cosmos DB.

Tentando fazer um planejamento de capacidade para uma migração para o Microsoft Azure Cosmos DB? Você pode usar informações sobre o cluster de banco de dados existente para fazer isso.