Diagnosticar e resolver problemas ao utilizar o SDK de .NET do Azure Cosmos DB

Artigo
04/13/2024

APLICA-SE A: NoSQL

Este artigo aborda problemas comuns, soluções alternativas, etapas de diagnóstico e ferramentas quando você usa o SDK do .NET com contas do Azure Cosmos DB para NoSQL. O SDK do .NET fornece representação lógica do lado do cliente para acessar o Azure Cosmos DB para NoSQL. Este artigo descreve as ferramentas e abordagens para o ajudar se encontrar problemas.

Lista de verificação para solução de problemas

Considere a lista de verificação a seguir antes de mover seu aplicativo para a produção. Usar a lista de verificação evitará vários problemas comuns que você pode ver. Você também pode diagnosticar rapidamente quando ocorre um problema:

Use o SDK mais recente. Os SDKs de visualização não devem ser usados para produção. Isso evitará problemas conhecidos que já foram corrigidos.
Analise as dicas de desempenho e siga as práticas sugeridas. Isso ajudará a evitar problemas de escala, latência e outros problemas de desempenho.
Habilite o log do SDK para ajudá-lo a solucionar um problema. Habilitar o registro em log pode afetar o desempenho, por isso é melhor habilitá-lo somente ao solucionar problemas. Você pode habilitar os seguintes logs:
- Registre métricas usando o portal do Azure. As métricas do portal mostram a telemetria do Azure Cosmos DB, que é útil para determinar se o problema corresponde ao Azure Cosmos DB ou se é do lado do cliente.
- Registre a cadeia de caracteres de diagnóstico das operações e/ou exceções.

Dê uma olhada na seção Problemas comuns e soluções alternativas neste artigo.

Verifique a seção de problemas do GitHub que é monitorada ativamente. Verifique se algum problema semelhante com uma solução alternativa já foi arquivado. Se você não encontrou uma solução, registre um problema no GitHub. Você pode abrir um tick de suporte para problemas urgentes.

Capturar diagnósticos

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

Os diagnósticos são retornados como uma cadeia de caracteres. A cadeia de caracteres muda a cada versão, pois é aprimorada para solucionar problemas de diferentes cenários. Com cada versão do SDK, a cadeia de caracteres terá alterações de quebra na formatação. Não analise a cadeia de caracteres para evitar a quebra de alterações. O exemplo de código a seguir mostra como ler 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()
}

Problemas comuns e soluções

Sugestões gerais

Siga qualquer aka.ms link incluído nos detalhes da exceção.
Execute seu aplicativo na mesma região do Azure que sua conta do Azure Cosmos DB, sempre que possível.
Você pode ter problemas de conectividade/disponibilidade devido à falta de recursos na máquina cliente. Recomendamos monitorar a utilização da CPU em nós que executam o cliente Azure Cosmos DB e dimensionar/reduzir se eles estiverem sendo executados com alta carga.

Verifique as métricas do portal

Verificar as métricas do portal ajudará a determinar se é um problema do lado do cliente ou se há um problema com o serviço. Por exemplo, se as métricas contiverem uma alta taxa de solicitações limitadas por taxa (código de status HTTP 429), o que significa que a solicitação está sendo limitada, verifique a seção Taxa de solicitação muito grande .

Repetir design

Consulte nosso guia para projetar aplicativos resilientes com SDKs do Azure Cosmos DB para obter orientação sobre como projetar aplicativos resilientes e saiba quais são as semânticas de repetição do SDK.

SNAT

Se a sua aplicação for implementada em Máquinas Virtuais do Azure sem um endereço IP público, por predefinição , as portas SNAT do Azure estabelecem ligações a qualquer ponto de extremidade fora da sua VM. O número de conexões permitidas da VM para o ponto de extremidade do Azure Cosmos DB é limitado pela configuração do Azure SNAT. Essa situação pode levar à limitação da conexão, ao fechamento da conexão ou aos tempos limite de solicitação mencionados acima.

As portas SNAT do Azure são usadas somente quando sua VM tem um endereço IP privado que está se conectando a um endereço IP público. Há duas soluções alternativas para evitar a limitação do Azure SNAT (desde que você já esteja usando uma única instância de cliente em todo o aplicativo):

Adicione seu ponto de extremidade de serviço do Azure Cosmos DB à sub-rede de sua rede virtual de Máquinas Virtuais do Azure. Para obter mais informações, consulte Pontos de extremidade de serviço da Rede Virtual do Azure.

Quando o ponto de extremidade de serviço está habilitado, as solicitações não são mais enviadas de um IP público para o Azure Cosmos DB. Em vez disso, a rede virtual e a identidade da sub-rede são enviadas. Essa alteração pode resultar em quedas de firewall se apenas IPs públicos forem permitidos. Se você usar um firewall, ao habilitar o ponto de extremidade de serviço, adicione uma sub-rede ao firewall usando ACLs de Rede Virtual.
Atribua um IP público à sua VM do Azure.

Alta latência de rede

Consulte nosso guia de solução de problemas de latência para obter detalhes sobre a solução de problemas de latência.

Falhas de autenticação de proxy

Se você vir erros que mostram como HTTP 407:

Response status code does not indicate success: ProxyAuthenticationRequired (407);

Este erro não é gerado pelo SDK nem vem do Serviço Azure Cosmos DB. Este é um erro relacionado com a configuração de rede. É provável que esteja em falta a autenticação de proxy necessária num proxy na sua configuração de rede. Se não está à espera de utilizar um proxy, contacte a sua equipa de rede. Se você estiver usando um proxy, certifique-se de que está definindo a configuração WebProxy correta em CosmosClientOptions.WebProxy ao criar a instância do cliente.

Problemas comuns de consulta

As métricas de consulta ajudarão a determinar onde a consulta está gastando a maior parte do tempo. A partir das métricas de consulta, você pode ver quanto está sendo gasto no back-end versus o cliente. Saiba mais no guia de desempenho da consulta.

Se você encontrar o seguinte erro: Unable to load DLL 'Microsoft.Azure.Cosmos.ServiceInterop.dll' or one of its dependencies: e estiver usando o Windows, você deve atualizar para a versão mais recente do Windows.

Próximos passos

Saiba mais sobre as diretrizes de desempenho para o SDK do .NET
Saiba mais sobre as práticas recomendadas para o SDK do .NET

Partilhar via