Compartilhar via

Solucionar problemas ao usar o SDK do Python do Azure Cosmos DB com API para contas NoSQL

  • Artigo

APLICA-SE A: NoSQL

Importante

Este artigo aborda a solução de problemas apenas no SDK do Python do Azure Cosmos DB. Confira o Readme, as Notas sobre a versão, o Pacote (PyPI), o Pacote (Conda) e as dicas de desempenho do SDK do Azure Cosmos DB para Python para mais informações.

Este artigo aborda problemas comuns, soluções alternativas, etapas de diagnóstico e ferramentas ao usar o SDK do Python do Azure Cosmos DB com contas do Azure Cosmos DB for NoSQL. O SDK do Python do Azure Cosmos DB fornece 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.

Comece com esta lista:

  • Dê uma olhada na seção Problemas comuns e soluções alternativas neste artigo.
  • Examine o SDK do Python no repositório central do Azure Cosmos DB, disponível no software livre no GitHub. Ele tem um seção de problemas que está sendo ativamente monitorada. Verifique se você encontrar algum problema semelhante com uma solução alternativa já arquivada. Uma dica útil é filtrar os problemas pela tag *Cosmos*.
  • Consulte as dicas de desempenho do SDK do Python do Azure Cosmos DB e siga as práticas sugeridas.
  • Se você não encontrar uma solução, leia o restante deste artigo. Em seguida, arquive um problema do GitHub. Se houver uma opção para adicionar marcas ao problema do GitHub, adicione uma tag *Cosmos*.

Registrar e capturar o diagnóstico

Importante

É recomendável usar a versão mais recente do SDK do Python. Verifique o histórico de lançamentosaqui

Essa biblioteca usa a biblioteca de registro em log padrão para registrar diagnósticos. As informações básicas sobre as sessões HTTP (URLs, cabeçalhos etc.) são registradas em log no nível de INFO.

O log detalhado no nível de DEBUG, inclusive corpos de solicitação/resposta e cabeçalhos não redigidos, pode ser habilitado em um cliente com o argumento logging_enable:

import sys
import logging
from azure.cosmos import CosmosClient

# Create a logger for the 'azure' SDK
logger = logging.getLogger('azure')
logger.setLevel(logging.DEBUG)

# Configure a console output
handler = logging.StreamHandler(stream=sys.stdout)
logger.addHandler(handler)

# This client will log detailed information about its HTTP sessions, at DEBUG level
client = CosmosClient(URL, credential=KEY, logging_enable=True)

Da mesma forma, logging_enable pode habilitar o log detalhado para uma operação individual, mesmo quando ela não está habilitada para o cliente:

database = client.create_database(DATABASE_NAME, logging_enable=True)

Como alternativa, faça logon usando o CosmosHttpLoggingPolicy, que se estende do núcleo HttpLoggingPolicy do Azure, passando o agente para o argumento logger. Por padrão, ele usará o comportamento de HttpLoggingPolicy. Passar o argumento enable_diagnostics_logging habilitará o CosmosHttpLoggingPolicy e terá informações adicionais na resposta relevante para depurar problemas do Cosmos.

import logging
from azure.cosmos import CosmosClient

#Create a logger for the 'azure' SDK
logger = logging.getLogger('azure')
logger.setLevel(logging.DEBUG)

# Configure a file output
handler = logging.FileHandler(filename="azure")
logger.addHandler(handler)

# This client will log diagnostic information from the HTTP session by using the CosmosHttpLoggingPolicy.
# Since we passed in the logger to the client, it will log information on every request.
client = CosmosClient(URL, credential=KEY, logger=logger, enable_diagnostics_logging=True)

Da mesma forma, o registro em log pode ser habilitado para uma única operação passando um agente para a solicitação singular. No entanto,caso queira usar o CosmosHttpLoggingPolicy, para obter informações adicionais, o argumento enable_diagnostics_logging precisará ser passado no construtor do cliente.

# This example enables the `CosmosHttpLoggingPolicy` and uses it with the `logger` passed in to the `create_database` request.
client = CosmosClient(URL, credential=KEY, enable_diagnostics_logging=True)
database = client.create_database(DATABASE_NAME, logger=logger)

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.

Problemas comuns e soluções alternativas

Sugestões gerais

Para obter o melhor desempenho:

  • Verifique se o aplicativo está em execução na mesma região que sua conta do Azure Cosmos DB.
  • Verifique o uso da CPU no host em que o aplicativo está sendo executado. Se o uso da CPU estiver em 50% ou mais, execute seu aplicativo em um host com uma configuração superior. Ou você pode distribuir a carga em mais computadores.

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.

Limitação de conexão

A limitação de conexão pode ocorrer devido a um [limite de conexão no computador host] ou a [Esgotamento de porta do Azure SNAT (PAT)].

Limite de conexão no computador host

Alguns sistemas Linux, como Red Hat, têm um limite superior para o número total de arquivos abertos. Soquetes no Linux são implementados como arquivos, portanto, esse número limita o número total de conexões também. Execute o comando a seguir.

ulimit -a

O número de arquivos abertos máximos permitos, que são identificados como "nofile", devem ser pelo menos duas vezes o tamanho do pool de conexão. Para obter mais informações, consulte as dicas de desempenho do SDK do Python do Azure Cosmos DB.

Esgotamento da porta SNAT (PAT) do Azure

Se o seu aplicativo for desenvolvido nas Máquinas Virtuais do Microsoft Azure sem um endereço IP público, por padrão as portas do Azure SNAT estabelecem conexõ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.

As portas Azure SNAT são usadas somente quando sua VM do Azure tiver um endereço IP privado e um processo da VM tenta estabelecer uma conexão com um endereço IP público. Há duas soluções alternativas para evitar a limitação do Azure SNAT:

  • 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 à sua VM do Azure.

Não é possível acessar o serviço – firewall

azure.core.exceptions.ServiceRequestError: indica que o SDK não pode acessar o serviço. Siga o Limite de conexão em um computador host.

Falha ao conectar-se ao emulador do Azure Cosmos DB

O certificado HTTPS do Emulador do Azure Cosmos DB é autoassinado. Para que o SDK do Python funcione com o emulador, importe o certificado do emulador. Para obter mais informações, confira Exportar certificados do Emulador do Azure Cosmos DB.

Proxy HTTP

Se você usar um proxy HTTP, certifique-se que pode suportar o número de conexões configuradas no SDK ConnectionPolicy. Caso contrário, você enfrentará problemas de conexão.

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.

Próximas etapas