Melhores práticas do SDK do Java do Azure Cosmos DB

  • Artigo

APLICA-SE A: NoSQL

Este artigo mostra as melhores práticas de uso do SDK do Java do Azure Cosmos DB. Seguir essas práticas ajudará a melhorar a latência, a disponibilidade e o desempenho geral.

Lista de verificação

Verificado Tópico Detalhes/links
Versão do SDK Sempre use a versão mais recente disponível do SDK do Azure Cosmos DB para obter o desempenho ideal.
Cliente Singleton Use uma instância única de CosmosClient pelo tempo de vida do seu aplicativo para melhor desempenho.
Regiões Execute sempre que for possível seu aplicativo na mesma região do Azure da sua conta do Azure Cosmos DB para reduzir a latência. Habilita 2 a 4 regiões e replique suas contas em várias regiões para melhor disponibilidade. Para cargas de trabalho de produção, habilite o failover gerenciado pelo serviço. Na ausência dessa configuração, a conta passará por perda de disponibilidade de gravação durante toda a interrupção da região de gravação, pois o failover manual não funcionará devido à falta de conectividade da região. Para saber como adicionar várias regiões usando o SDK do Java, acesse aqui
Disponibilidade e failovers Defina as preferredRegions no SDK v4. Durante failovers, as operações de gravação são enviadas à região de gravação atual e todas as leituras são enviadas à primeira região da sua lista de regiões preferenciais. Para obter mais informações sobre a mecânica do failover regional, confira o guia de solução de problemas de disponibilidade.
CPU Você poderá ter problemas de conectividade/disponibilidade devido à falta de recursos no computador cliente. Monitore a utilização da CPU em nós que executam o cliente do Azure Cosmos DB e escale verticalmente ou horizontalmente se o uso for muito elevado.
Hosting Para casos mais comuns de cargas de trabalho de produção, é altamente recomendável usar, pelo menos, VMs de quatro núcleos e com 8 GB de memória sempre que possível.
Modos de conectividade Use o modo Direto para ter o melhor desempenho. Para obter instruções sobre como fazer isso, confira a documentação do SDK v4.
Rede Se usar uma máquina virtual, para executar seu aplicativo, habilite a Rede Acelerada na sua VM para ajudar com gargalos devido ao alto tráfego e reduzir a latência ou a tremulação da CPU. Talvez você também queira considerar o uso de uma máquina virtual topo de linha em que o uso máximo da CPU está abaixo de 70%.
Esgotamento de porta efêmera Para conexões esparsas ou esporádicas, recomendamos definir o idleEndpointTimeout com um valor mais alto. A propriedade idleEndpointTimeout em DirectConnectionConfig ajuda a controlar o tempo em que as conexões não usadas são fechadas. Isso reduzirá o número de conexões não usadas. Por padrão, as conexões ociosas com um ponto de extremidade são mantidas abertas por uma hora. Se não houver solicitações para um ponto de extremidade específico para a duração de tempo limite de ponto de extremidade ocioso, o cliente direto fechará todas as conexões com esse ponto de extremidade para economizar recursos e custo de E/S.
Usar o Agendador Apropriado (Evitar roubo de threads Netty de E/S Eventloop) Evite chamadas de bloqueio: .block(). Toda a pilha de chamadas é assíncrona para se beneficiar de padrões de API assíncrona e do uso de threads e agendadores apropriados
Tempos limite de ponta a ponta Para obter tempos limite de ponta a ponta, implemente a política de tempo limite de ponta a ponta no SDK do Java. Para obter mais detalhes sobre tempos limite com o Azure Cosmos DB, visite aqui
Lógica de repetição Um erro transitório é um erro que tem uma causa subjacente que será resolvida por si só em breve. Aplicativos que se conectam ao banco de dados devem ser criados para esperar esses erros transitórios. Para lidar com eles, implemente a lógica de repetição no código, em vez de mostrá-los aos usuários como erros de aplicativo. O SDK tem lógica interna para lidar com essas falhas transitórias em solicitações de novas tentativas, como operações de leitura ou consulta. O SDK não repetirá as gravações em caso de falhas transitórias, pois as gravações não são idempotentes. O SDK permite que os usuários configurem a lógica de repetir para limitações. Para obter detalhes sobre os erros em que é recomendado repetir a operação, acesse aqui
Cache de nomes de banco de dados/coleção Recupere os nomes dos bancos de dados e coleções de configuração ou armazene-os em cache na inicialização. Chamadas como CosmosAsyncDatabase#read() ou CosmosAsyncContainer#read() resultarão em chamadas de metadados para o serviço, que consomem o limite de RU reservado pelo sistema. createDatabaseIfNotExists() também deve ser usado apenas uma vez para configurar o banco de dados. Em geral, essas operações devem ser executadas com pouca frequência.
Consultas paralelas O SDK do Azure Cosmos DB permite executar consultas em paralelo para melhorar a latência e a taxa de transferência nas consultas. Recomendamos definir a propriedade maxDegreeOfParallelism no CosmosQueryRequestsOptions para o número de partições que você tem. Se você não estiver ciente do número de partições, defina o valor como -1, que dará a melhor latência. Além disso, defina maxBufferedItemCount para o número esperado de resultados retornados para limitar o número de resultados pré-buscados.
Retiradas de teste de desempenho Ao executar testes no seu aplicativo, você deve implementar retiradas em intervalos de RetryAfter. Respeitar essa retirada garante que você perca o mínimo de tempo esperando entre as tentativas.
Indexação A política de indexação do Azure Cosmos DB também permite especificar quais caminhos de documento serão incluídos ou excluídos da indexação usando os caminhos de indexação IndexingPolicy#getIncludedPaths() e IndexingPolicy#getExcludedPaths(). Não deixe de excluir caminhos não utilizados da indexação para gravações mais rápidas. Para ver um exemplo de como criar índices usando o SDK, acesse aqui
Tamanho do documento A carga da solicitação para uma operação especificada está diretamente correlacionada ao tamanho do documento. Recomendamos reduzir o tamanho dos seus documentos, pois as operações em documentos grandes custam mais do que em documentos menores.
Tamanho da Página Por padrão, os resultados da consulta são retornados em blocos de 100 itens ou 4 MB, o limite que for atingido primeiro. Se uma consulta retornar mais de 100 itens, aumente o tamanho da página para reduzir o número de viagens de ida e volta necessárias. O consumo de memória aumentará à medida que o tamanho da página aumentar.
Habilitar métricas de consulta Para obter o log adicional das suas execuções de consulta de back-end, siga as instruções sobre como capturar métricas de consulta SQL usando o SDK do Java
Registro em log de SDK Use o registro em log do SDK para capturar informações de diagnóstico adicionais e solucionar problemas de latência. Registre em log o CosmosDiagnostics no SDK do Java para obter informações de diagnóstico do Azure Cosmos DB mais detalhadas da solicitação atual para o serviço. Como exemplo de caso de uso, capture o diagnóstico em qualquer exceção e em operações concluídas se o CosmosDiagnostics#getDuration() for maior que o valor limite designado (ou seja, se você tiver um SLA de 10 segundos, capture o diagnóstico quando getDuration()> 10 segundos). Aconselhamos usar apenas esses diagnósticos durante o teste de desempenho. Para obter mais informações, siga o diagnóstico de captura no SDK do Java
Evite usar caracteres especiais em identificadores Alguns caracteres são restritos e não podem ser usados em alguns identificadores: '/', '\', '?', '#'. A recomendação geral é não usar caracteres especiais em identificadores como nome do banco de dados, nome da coleção, ID do item ou chave de partição para evitar qualquer comportamento inesperado.

As melhores práticas ao usar o modo Gateway

As solicitações do Azure Cosmos DB são feitas sobre HTTPS/REST ao usar o modo de gateway. Elas estão sujeitas ao limite de conexão padrão por nome de host ou endereço IP. Pode ser necessário ajustar maxConnectionPoolSize com outro valor (de 100 a 1.000) para que a biblioteca de clientes possa usar várias conexões simultâneas com o Azure Cosmos DB. No SDK v4 do Java, o valor padrão de GatewayConnectionConfig#maxConnectionPoolSize é 1.000. Para alterá-lo, defina GatewayConnectionConfig#maxConnectionPoolSize com outro valor.

Melhores práticas para cargas de trabalho com muita gravação

Para cargas de trabalho com cargas de criação pesadas, defina a opção de solicitação CosmosClientBuilder#contentResponseOnWriteEnabled() como false. O serviço não retornará mais o recurso criado ou atualizado para o SDK. Normalmente, como o aplicativo tem o objeto que está sendo criado, ele não precisa que o serviço o retorne. Os valores de cabeçalho ainda são acessíveis, como uma carga de solicitação. Desabilitar a resposta de conteúdo pode ajudar a melhorar o desempenho, pois o SDK não precisa mais alocar memória ou serializar o corpo da resposta. Isso também reduz o uso de largura de banda da rede e ajudar ainda mais no desempenho.

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.