Partilhar via

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

  • Artigo

APLICA-SE A: NoSQL

Importante

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

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

Comece com esta lista:

  • Dê uma olhada na seção Problemas comuns e soluções alternativas neste artigo.
  • Observe o SDK do Python no repositório central do Azure Cosmos DB, que está disponível em código aberto no GitHub. Ele tem uma seção de problemas que é monitorada ativamente. Verifique se algum problema semelhante com uma solução alternativa já foi arquivado. Uma dica útil é filtrar os *Cosmos* problemas pela tag .
  • Analise as dicas de desempenho para o SDK Python do Azure Cosmos DB e siga as práticas sugeridas.
  • Leia o resto deste artigo, se não encontrou uma solução. Em seguida, registre um problema no GitHub. Se houver uma opção para adicionar tags ao seu problema no GitHub, adicione uma *Cosmos* tag.

Registrando e capturando o diagnóstico

Importante

Recomendamos usar a versão mais recente do python SDK. Você pode conferir o histórico de lançamentos aqui

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

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

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 registro detalhado para uma única operação, mesmo quando ele não está habilitado para o cliente:

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

Como alternativa, você pode registrar usando o CosmosHttpLoggingPolicy, que se estende do núcleo HttpLoggingPolicyazure , passando seu logger para o logger argumento. Por padrão, ele usará o comportamento de HttpLoggingPolicy. Passar o enable_diagnostics_logging argumento habilitará o CosmosHttpLoggingPolicy, e terá informações adicionais na resposta relevantes 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 registrador para a solicitação singular. No entanto, se você deseja usar o CosmosHttpLoggingPolicy para obter informações adicionais, o enable_diagnostics_logging argumento precisa 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)

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.

Problemas comuns e soluções

Sugestões gerais

Para o melhor desempenho:

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

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 .

Limitação de conexão

A limitação de conexão pode acontecer devido a um [limite de conexão em uma máquina host] ou [esgotamento da porta SNAT do Azure (PAT)].

Limite de conexão em uma máquina host

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

ulimit -a

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

Exaustão da porta do Azure SNAT (PAT)

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.

As portas SNAT do Azure são usadas somente quando sua VM tem um endereço IP privado e um processo da VM tenta se conectar a 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 à 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.

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 uma máquina host.

Falha ao conectar 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, consulte Exportar certificados do emulador do Azure Cosmos DB.

Proxy HTTP

Se você usar um proxy HTTP, verifique se ele 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 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.

Próximos passos

  • Saiba mais sobre as diretrizes de desempenho para o SDK do Python
  • Saiba mais sobre as práticas recomendadas para o SDK do Python