Partilhar via

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

  • Artigo

APLICA-SE A: NoSQL

Importante

As dicas de desempenho neste artigo são apenas para o SDK Java v4 do Azure Cosmos DB. Consulte as Notas de versão do SDK Java do Azure Cosmos DB v4, o repositório Maven e o guia de solução de problemas do SDK Java do Azure Cosmos DB v4 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 Java do Azure Cosmos DB v4 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 latência e taxa de transferência garantidas. Não é necessário fazer grandes alterações na arquitetura ou escrever código complexo para dimensionar seu banco de dados com o Azure Cosmos DB. Escalar para cima e para baixo é tão fácil quanto fazer uma única chamada de API ou chamada de método 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 Java v4 do Azure Cosmos DB.

Configuração da conexão

Nota

No SDK 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 Java SDK é direto. As solicitações do Azure Cosmos DB de modo direto são feitas por TCP ao usar o SDK Java do Azure Cosmos DB v4. O modo Internamente Direto usa uma arquitetura especial para gerenciar dinamicamente os recursos da 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 abaixo. Para configurar o modo direto com as 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 API directMode() .

Java SDK V4 (Maven com.azure::azure-cosmos) API assíncrona


/* 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 do modo Direct não padrão 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 definições de configuração controlam o comportamento da arquitetura subjacente do modo Direct discutida acima.

Como primeiro passo, use as seguintes definições de configuração recomendadas abaixo. Essas opções DirectConnectionConfig são definições de configuração avançadas que podem afetar o desempenho do SDK de maneiras inesperadas, recomendamos que os usuários evitem modificá-las, a menos que se sintam muito confortáveis em entender as compensações e isso seja absolutamente necessário. Entre em contato com a equipe do Azure Cosmos DB se tiver problemas neste tópico específico.

Opção de configuração Predefinido Recomendado Detalhes
idleConnectionTimeout "PT0" (ZERO) "PT0" (ZERO) Isso representa a duração do tempo limite de conexão ociosa para uma única conexão com 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 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 economizar 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é mesmo 24 horas, para que o SDK não precise abrir as conexões com frequência. No entanto, isso utilizará os recursos da 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 ponto de extremidade ociosa será desativada.
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 endpoint/back-end sob demanda e com base em solicitações simultâneas recebidas. Por padrão, se necessário, o SDK criará no máximo 130 conexões com um nó de endpoint/back-end. (NOTA: 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 com um nó de endpoint/back-end sob demanda e com base em solicitações simultâneas recebidas. Por padrão, se necessário, o SDK enfileirará no máximo 30 solicitações para uma única conexão para um nó de endpoint/back-end específico. (NOTA: 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 de estabelecimento de conexão para uma única conexão a ser estabelecida com 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 lançar um erro. O estabelecimento de conexão TCP usa handshake de várias etapas que aumenta a latência do tempo de estabelecimento da conexão, portanto, os clientes são recomendados a definir esse valor de acordo com sua largura de banda de rede e configurações de ambiente. NOTA: Esta recomendação de ~PT1S é apenas para aplicativos implantados em regiões colocalizadas de suas contas do Cosmos DB.
networkRequestTimeout "PT5S" "PT5S" Isso representa a duração do tempo limite de rede para uma única solicitação. O SDK aguardará no máximo 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 só permite valores entre 1 segundo (min) e 10 segundos (max). Definir um valor muito alto pode resultar em menos tentativas e reduzir as chances de sucesso por tentativas.

Modo de conexão de gateway

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

Java SDK V4 (Maven com.azure::azure-cosmos) API assíncrona


/* 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 o método gatewayMode() acima no construtor de clientes do Azure Cosmos DB.

Como primeiro passo, use as seguintes definições de configuração recomendadas abaixo. Essas opções de GatewayConnectionConfig são definições de configuração avançadas que podem afetar o desempenho do SDK de maneiras inesperadas, recomendamos que os usuários evitem modificá-las, a menos que se sintam muito confortáveis em entender as compensações e isso seja absolutamente necessário. Entre em contato com a equipe do Azure Cosmos DB se tiver problemas neste tópico específico.

Opção de configuração Predefinido Recomendado 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 com o Gateway. Após esse período, a conexão será fechada automaticamente e será removida do pool de conexões.

Próximos passos

Para saber mais sobre dicas de desempenho para Java SDK, consulte Dicas de desempenho para o Azure Cosmos DB Java SDK v4.

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

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