Compartilhar via

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

  • Aplica-se a: ✅ NoSQL

Importante

As dicas de desempenho neste artigo são apenas para o SDK do Java v4 do Azure Cosmos DB. Exiba as notas de versão do SDK do Java v4 do Azure Cosmos DB, o repositório Maven e o guia de solução de problemas do SDK do Java v4 do Azure Cosmos DB para obter mais informações. Se você estiver usando uma versão mais antiga do que a v4, consulte o guia Migrar para o SDK do Java v4 do Azure Cosmos DB para obter ajuda com a 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 grandes alterações de arquitetura nem escrever códigos complexos 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 atingir 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 no modo direto são feitas por TCP ao usar o SDK do Java do Azure Cosmos DB v4. 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 previsível da rede e o acesso multiplexado às réplicas do Azure Cosmos DB. Para saber mais sobre arquitetura, consulte a arquitetura de conexão de modo direto

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

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 nondefault Direct mode for desejado, crie uma instância DirectConnectionConfig e personalize suas propriedades e, em seguida, passe a instância de propriedade personalizada para o método directMode() no construtor de clientes do Azure Cosmos DB.

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

Como primeira etapa, use as seguintes configurações recomendadas aqui. Essas opções de DirectConnectionConfig são configurações avançadas, que podem afetar o desempenho do SDK de maneiras inesperadas; recomendamos que os usuários evitem modificá-los, a menos que se sintam confortáveis em entender as compensações e isso é necessário. Entre em contato com a equipe do Azure Cosmos DB se você tiver problemas sobre esse assunto específico.

Opções de configuração Padrão Recommended Detalhes
idleConnectionTimeout "PT0" (ZERO) "PT0" (ZERO) Isso representa a duração do tempo de inatividade para uma única conexão com um nó de endpoint/back-end (representando uma réplica). Por padrão, o SDK não fecha automaticamente as conexões ociosas com os 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 para esse nó de ponto de extremidade/back-end após 1 hora para salvar recursos de rede e custo de E/S. Para um padrão de tráfego esparso ou esporádico, recomendamos definir esse valor para 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 utiliza os recursos de rede e terá um número maior de conexões mantidas abertas a qualquer momento. Se isso estiver definido como ZERO, a verificação de endpoint ocioso será desabilitada.
maxConnectionsPerEndpoint (máximo de conexões por ponto de extremidade) "130" "130" Isso representa o tamanho do limite máximo do pool de conexões para um nó endpoint/back-end (representando uma réplica). O SDK cria conexões com o nó de endpoint/backend sob demanda e com base em requisições simultâneas recebidas. Por padrão, se necessário, o SDK cria no máximo 130 conexões com 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 ponto de extremidade ou nó de back-end específico (representando uma réplica). O SDK enfileira solicitações para uma única conexão com um nó de endpoint/back-end sob a demanda e com base nas requisições simultâneas de entrada. Por padrão, se necessário, o SDK enfileira no máximo 30 solicitações para uma única conexão para 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).
tempo_limite_de_conexão "PT5S" "~PT1S" Isso representa a duração do tempo limite do estabelecimento de conexão para que uma única conexão seja estabelecida com um nó de ponto de extremidade/back-end. Por padrão, o SDK aguarda no máximo 5 segundos para o estabelecimento da conexão antes de gerar um erro. O estabelecimento de conexão TCP usa um handshake de várias etapas que aumenta a latência do tempo de estabelecimento da conexão, portanto, é recomendável que os clientes definam esse valor de acordo com suas configurações de largura de banda e ambiente de rede. OBSERVAÇÃO: Essa recomendação de ~PT1S é apenas para aplicativos implantados em regiões colocalizadas de suas contas do Cosmos DB.
tempoDeEsperaDaSolicitaçãoNaRede "PT5S" "PT5S" Isso representa a duração do tempo limite da rede para uma única solicitação. O SDK aguardará no máximo essa duração para consumir uma resposta de serviço após a solicitação ter 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 muito alto pode resultar em menos tentativas e reduzir as chances de sucesso com as tentativas.

Modo de conexão de gateway

Operações de plano de controle, como banco de dados e CRUD de contêiner, sempre utilizam o modo gateway. Mesmo quando o usuário tiver configurado o modo Direto para operações do plano de dados, as operações de plano de controle e metadados usam configurações padrão do modo gateway. Isso atende à maioria dos usuários. No entanto, os usuários que desejam o modo direto para operações do plano de dados e a capacidade de ajustar os parâmetros do modo gateway do plano 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();

Personalizando o modo de conexão do gateway

Se o comportamento do modo gateway não padrão for desejado, crie uma instância gatewayConnectionConfig e personalize suas propriedades e, em seguida, passe a instância de propriedade personalizada para o método de substituição directMode() ou gatewayMode() no construtor de clientes do Azure Cosmos DB.

Como primeira etapa, use as seguintes configurações recomendadas aqui. Essas opções de GatewayConnectionConfig são configurações avançadas, que podem afetar o desempenho do SDK de maneiras inesperadas; recomendamos que os usuários evitem modificá-los, a menos que se sintam confortáveis em entender as compensações e isso é necessário. Entre em contato com a equipe do Azure Cosmos DB se você tiver problemas sobre esse assunto específico.

Opções de configuração Padrão Recommended 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 cria 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 com o 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 seu cluster de banco de dados existente para planejamento de capacidade.

  • Last updated on