Diagnosticar e solucionar problemas ao usar o SDK . NET para Azure Cosmos DB

APLICA-SE A: NoSQL

• SDK do Java v4
• SDK do Java Assíncrono v2
• .NET
• SDK do Python

Este artigo aborda problemas comuns, soluções alternativas, etapas de diagnóstico e ferramentas para o uso do SDK do .NET com as contas do Azure Cosmos DB for NoSQL. O SDK do .NET fornece uma representação lógica do lado do cliente para acessar o Azure Cosmos DB for NoSQL. Este artigo descreve as ferramentas e as abordagens para ajudá-lo se você tiver algum problema.

Lista de verificação para solucionar problemas

Considere a lista de verificação a seguir antes de migrar seu aplicativo para produção. O uso da lista de verificação impedirá vários problemas comuns que podem ser observados. Você também poderá diagnosticar rapidamente quando um problema ocorrerá:

• Use o SDK mais recente. SDKs de versão prévia não devem ser usados para produção. Isso evitará que você enfrente problemas conhecidos que já foram corrigidos.
• Examine dicas de desempenho e siga as práticas sugeridas. Isso ajudará a evitar o dimensionamento, a latência e outros problemas de desempenho.
• Habilite o log do SDK para ajudar você a solucionar um problema. A habilitação do log pode afetar o desempenho. Portanto, é melhor habilitá-lo somente ao solucionar problemas. Você pode habilitar os seguintes logs:
  • Registre em log as métricas usando o portal do Azure. As métricas do portal mostram a telemetria do Azure Cosmos DB, o que é útil para determinar se o problema corresponde ao Azure Cosmos DB ou se ele é proveniente 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 você encontrar algum problema semelhante com uma solução alternativa já arquivada. Caso não encontre uma solução, registre um problema do GitHub. Abra um tíquete de suporte em caso de problemas urgentes.

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()
}

Problemas comuns e soluções alternativas

Sugestões gerais

• Siga qualquer link aka.ms incluído nos detalhes da exceção.
• Execute seu aplicativo na mesma região do Azure da sua conta do Azure Cosmos DB, sempre que possível.
• Você poderá ter problemas de conectividade/disponibilidade devido à falta de recursos no computador cliente. Recomendamos monitorar a utilização da CPU nos nós que executam o cliente do Azure Cosmos DB e usar a escala vertical/horizontal se eles estão sendo executados com uma alta carga.

Verificar as métricas do portal

A verificação das métricas do portal ajudará a determinar se esse é um problema do lado do cliente ou se há um problema com o serviço. Por exemplo, se as métricas contêm uma alta taxa de solicitações com taxa limitada (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 alta.

Design para repetição

Confira nosso guia para obter diretrizes sobre como criar aplicativos resilientes com SDKs do Azure Cosmos DB e para saber qual é a semântica de repetição do SDK.

SNAT

Se o seu aplicativo foi implantado nas Máquinas Virtuais do Azure sem um endereço IP público, por padrão, as portas SNAT do Azure estabelecem conexões com 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 resultar na limitação ou no fechamento da conexão ou nos Tempos limite de solicitação mencionados acima.

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

• Adicione seu ponto de extremidade de serviço do Azure Cosmos DB para a sub-rede da sua rede virtual de Máquinas Virtuais do Azure. Para saber mais, consulte pontos de extremidade de serviço de Rede Virtual do Microsoft Azure.

  Quando o ponto de extremidade for 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 de sub-rede são enviadas. Essa alteração poderá resultar em quedas de firewall se apenas IPs públicos forem permitidos. Se você usar um firewall, quando você habilitar o ponto de extremidade de serviço, adicione uma sub-rede para o firewall usando as ACLs de Rede Virtual.

• Atribua um IP público à VM do Azure.

Alta latência de rede

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

Falhas na autenticação de proxy

Se você vir erros que aparecem como HTTP 407:

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

Esse erro não é gerado pelo SDK nem é proveniente do serviço do Azure Cosmos DB. Esse é um erro relacionado à configuração de rede. Um proxy na configuração de rede provavelmente não tem a autenticação de proxy necessária. Se você não espera usar um proxy, entre em contato com sua equipe de rede. Se você estiver usando um proxy, verifique se está definindo a configuração correta do WebProxy em CosmosClientOptions.WebProxy ao criar a instância do cliente.

Problemas comuns de consulta

As métricas de consulta ajudarão a determinar em que item a consulta está gastando a maior parte do tempo. Nas métricas de consulta, você pode ver quanto da consulta está sendo gasto no back-end em comparação com o cliente. Saiba mais sobre o guia de desempenho da consulta.

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

Próximas etapas

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