Melhores práticas para o SDK do .NET do Azure Cosmos DB

APLICA-SE A: NoSQL

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

Assista ao vídeo abaixo para saber mais sobre como usar o SDK do .NET com um engenheiro do Azure Cosmos DB!

Lista de verificação

Capturar diagnósticos

Todas as respostas no SDK, incluindo CosmosException, têm uma propriedade Diagnostics. Ela registra todas as informações relacionadas à solicitação única, incluindo se houve novas tentativas ou quaisquer falhas temporárias.

Os diagnósticos são retornados como uma cadeia de caracteres. A cadeia de caracteres muda a cada versão, à medida que é aprimorada para solucionar melhor os diferentes cenários. Com cada versão do SDK, a cadeia de caracteres terá alterações interruptivas na formatação. Não analise a cadeia de caracteres para evitar alterações interruptivas. O exemplo de código a seguir mostra como ler os logs de diagnóstico usando o SDK do .NET:

try
{
    ItemResponse<Book> response = await this.Container.CreateItemAsync<Book>(item: testItem);
    if (response.Diagnostics.GetClientElapsedTime() > ConfigurableSlowRequestTimeSpan)
    {
        // Log the response.Diagnostics.ToString() and add any additional info necessary to correlate to other logs 
    }
}
catch (CosmosException cosmosException)
{
    // Log the full exception including the stack trace with: cosmosException.ToString()
    
    // The Diagnostics can be logged separately if required with: cosmosException.Diagnostics.ToString()
}

// When using Stream APIs
ResponseMessage response = await this.Container.CreateItemStreamAsync(partitionKey, stream);
if (response.Diagnostics.GetClientElapsedTime() > ConfigurableSlowRequestTimeSpan || !response.IsSuccessStatusCode)
{
    // Log the diagnostics and add any additional info necessary to correlate to other logs with: response.Diagnostics.ToString()
}

Práticas recomendadas para conexões HTTP

O SDK do .NET usa HttpClient para executar solicitações HTTP, independentemente do modo de conectividade configurado. No Modo direto o HTTP é usado para operações de metadados e, no modo Gateway, é usado para operações de plano de dados e metadados. Um dos conceitos básicos do HttpClient é garantir que o HttpClient possa reagir às alterações de DNS em sua conta personalizando o tempo de vida da conexão em pool. Desde que as conexões em pool sejam mantidas abertas, elas não reagem às alterações de DNS. Essa configuração força as conexões em pool a serem fechadas periodicamente, garantindo que seu aplicativo reaja às alterações de DNS. Nossa recomendação é que você personalize esse valor de acordo com o modo de conectividade e a carga de trabalho para equilibrar o impacto no desempenho da criação frequente de novas conexões, com a necessidade de reagir às alterações de DNS (disponibilidade). Um valor de cinco minutos seria um bom começo que pode ser aumentado se estiver afetando o desempenho, especialmente para o Modo gateway.

Você pode injetar seu HttpClient personalizado por meio de CosmosClientOptions.HttpClientFactory, por exemplo:

// Use a Singleton instance of the SocketsHttpHandler, which you can share across any HttpClient in your application
SocketsHttpHandler socketsHttpHandler = new SocketsHttpHandler();
// Customize this value based on desired DNS refresh timer
socketsHttpHandler.PooledConnectionLifetime = TimeSpan.FromMinutes(5);

CosmosClientOptions cosmosClientOptions = new CosmosClientOptions()
{
    // Pass your customized SocketHttpHandler to be used by the CosmosClient
    // Make sure `disposeHandler` is `false`
    HttpClientFactory = () => new HttpClient(socketsHttpHandler, disposeHandler: false)
};

// Use a Singleton instance of the CosmosClient
return new CosmosClient("<connection-string>", cosmosClientOptions);

Se você usar a injeção de dependência do .NET, poderá simplificar o processo Singleton:

SocketsHttpHandler socketsHttpHandler = new SocketsHttpHandler();
// Customize this value based on desired DNS refresh timer
socketsHttpHandler.PooledConnectionLifetime = TimeSpan.FromMinutes(5);
// Registering the Singleton SocketsHttpHandler lets you reuse it across any HttpClient in your application
services.AddSingleton<SocketsHttpHandler>(socketsHttpHandler);

// Use a Singleton instance of the CosmosClient
services.AddSingleton<CosmosClient>(serviceProvider =>
{
    SocketsHttpHandler socketsHttpHandler = serviceProvider.GetRequiredService<SocketsHttpHandler>();
    CosmosClientOptions cosmosClientOptions = new CosmosClientOptions()
    {
        HttpClientFactory = () => new HttpClient(socketsHttpHandler, disposeHandler: false)
    };

    return new CosmosClient("<connection-string>", cosmosClientOptions);
});

As melhores práticas ao usar o modo Gateway

Aumente System.Net MaxConnections por host 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 definir MaxConnections como um valor mais alto (de 100 a 1000) para que a biblioteca de cliente possa utilizar várias conexões simultâneas com o Azure Cosmos DB. No SDK .NET 1.8.0 e posteriores, o valor padrão de ServicePointManager.DefaultConnectionLimit será 50. Para alterá-lo, defina CosmosClientOptions.GatewayModeMaxConnectionLimit como um valor mais alto.

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 EnableContentResponseOnWrite 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.

Boas práticas para aplicativos multilocatário

Os aplicativos que distribuem o uso entre vários locatários, sendo que cada locatário é representado por um banco de dados, contêiner ou chave de partição diferentes, dentro da mesma conta do Azure Cosmos DB, devem usar uma única instância de cliente. Uma única instância de cliente pode interagir com todos os bancos de dados, contêineres e chaves de partição dentro de uma conta e usar o padrão de banco de dados individual é uma boa prática.

No entanto, quando cada locatário é representado por uma conta diferente do Azure Cosmos DB é necessário criar uma instância de cliente separada para cada conta. O padrão de banco de dados individual continua se aplicando a cada cliente (um cliente para cada conta por todo o tempo de vida do aplicativo), mas se o volume de locatários for alto, o número de clientes poderá ser difícil de gerenciar. As conexões podem aumentar além dos limites do ambiente de computação e causar problemas de conectividade.

Nesses casos, é recomendável:

• Entender as limitações do ambiente de computação (recursos de CPU e conexão). Recomendamos o uso de VMs com pelo menos 4 núcleos e 8 GB de memória sempre que possível.
• Com base nas limitações do ambiente de computação, determine o número de instâncias de cliente (e, portanto, o número de locatários) que uma única instância de computação pode controlar. Você pode estimar o número de conexões que serão abertas por cliente, dependendo do modo de conexão escolhido.
• Avalie a distribuição de locatários entre todas as instâncias. Se cada instância de computação puder controlar com sucesso uma determinada quantidade limitada de locatários, o balanceamento de carga e o roteamento dos locatários para instâncias de computação diferentes permitirão uma ampliação à medida que o número de locatários aumentar.
• Para cargas de trabalho esparsas, pense em usar um armazenamento em cache Menos Frequentemente Usado como a estrutura para manter as instâncias do cliente e descartar clientes para os locatários que não foram acessados durante um intervalo de tempo. Uma opção no .NET são as MemoryCacheEntryOptions, nas quais RegisterPostEvictionCallback pode ser usado para descartar clientes inativos e SetSlidingExpiration pode ser usado para definir o intervalo de tempo máximo para manter conexões inativas.
• Avalie o uso do modo Gateway para reduzir o número de conexões de rede.
• Ao usar o modo Direto, pense em ajustar o CosmosClientOptions.IdleTcpConnectionTimeout e oCosmosClientOptions.PortReuseMode na configuração do modo direto para fechar conexões não utilizadas e manter o volume de conexões sob controle.

Próximas etapas

Para obter um aplicativo de exemplo que é usado na avaliação do Azure Cosmos DB para cenários de alto desempenho em alguns computadores cliente, consulte Teste de desempenho e escala com o 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.

• Se souber as taxas de solicitação típicas da carga de trabalho do banco de dados atual, leia sobre como estimar unidades de solicitação usando o planejador de capacidade do Azure Cosmos DB