Resolver problemas quando usa o Azure Cosmos DB Python SDK com API para contas NoSQL

Este artigo aborda questões comuns, soluções alternativas, passos de diagnóstico e ferramentas quando utiliza o Azure Cosmos DB Python SDK com o Azure Cosmos DB para contas NoSQL. O Azure Cosmos DB Python SDK fornece representação lógica do lado do cliente para aceder ao 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.
• Veja o SDK em Python no repositório central Azure Cosmos DB, que está disponível em open source no GitHub. Tem uma secção de problemas que é monitorizada ativamente. Verifique se há algum problema semelhante com uma solução alternativa já reportado. Uma dica útil é filtrar os problemas pela *Cosmos* etiqueta.
• Revise as dicas de desempenho do Azure Cosmos DB Python SDK e siga as práticas sugeridas.
• Leia o resto deste artigo, caso não tenha encontrado uma solução. Depois apresenta uma edição no GitHub. Se houver uma opção para adicionar etiquetas ao teu problema no GitHub, adiciona uma *Cosmos* etiqueta.

Registo e captura dos diagnósticos

Esta biblioteca utiliza a biblioteca padrão de logs para diagnósticos de registo de logs. A informação básica sobre sessões HTTP (URLs, cabeçalhos, etc.) é registada ao nível INFO.

Registos detalhados ao nível DEBUG, incluindo corpos de pedido/resposta e cabeçalhos não censurados, podem ser ativados num 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 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)

Alternativamente, pode registar-se usando o CosmosHttpLoggingPolicy, que se estende do HttpLoggingPolicy núcleo Azure, passando o seu logger para o argumento logger. Por padrão, irá usar o comportamento de HttpLoggingPolicy. Ao passar no argumento enable_diagnostics_logging, ativará 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)

De forma semelhante, o registo pode ser ativado para uma única operação ao passar um logger para o pedido singular. No entanto, se desejar usar o CosmosHttpLoggingPolicy para obter informações adicionais, o enable_diagnostics_logging argumento deve ser passado no construtor 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:

• Certifica-te de que a aplicação está a correr na mesma região da tua conta Azure Cosmos DB.
• Verifica a utilização da CPU no host onde a aplicação está a correr. Se o uso da CPU for de 50 por cento ou mais, execute a sua aplicação num host com uma configuração superior. Ou pode distribuir a carga em mais máquinas.
  • Se estiver a correr a sua aplicação no Azure Kubernetes Service, pode usar o Azure Monitor para monitorizar a utilização da CPU.

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 com limitação de taxa (código de status HTTP 429), indicando que a solicitação está a ser restringida, consulte a seção Taxa de solicitação muito grande.

Limitação da conexão

A limitação da ligação pode ocorrer devido a um [limite de conexões numa máquina anfitriã] ou [esgotamento das portas SNAT (PAT) do Azure].

Limite de ligação numa máquina anfitriã

Alguns sistemas Linux, como o Red Hat, têm um limite superior para o número total de ficheiros abertos. Os sockets no Linux são implementados como ficheiros, por isso este número limita também o número total de ligações. Execute o seguinte comando.

ulimit -a

O número máximo de ficheiros abertos permitidos, identificados como "nofile", tem de ser pelo menos o dobro do tamanho do teu pool de ligações. Para mais informações, consulte as dicas de desempenho do Azure Cosmos DB Python SDK.

Exaustão de portas Azure SNAT (PAT)

Se a sua aplicação estiver implementada em Máquinas Virtuais Azure sem um endereço IP público, por defeito as portas SNAT do Azure estabelecem ligações a qualquer endpoint 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 apenas quando a sua VM tem um endereço IP privado e um processo da VM tenta ligar-se a um endereço IP público. Existem 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 finais de serviço da Azure Virtual Network.

  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 utilizar um firewall, ao ativar o ponto de extremidade do serviço, adicione uma sub-rede ao firewall usando ACLs de Rede Virtual.

• Atribui um IP público à tua VM Azure.

Não consigo contactar o serviço - firewall

azure.core.exceptions.ServiceRequestError: indica que o SDK não consegue aceder ao serviço. Siga o limite de ligação numa máquina anfitriã.

Falha na ligação ao emulador Azure Cosmos DB

O certificado HTTPS do emulador de base de dados do Azure Cosmos é auto-assinado. Para o SDK Python funcionar com o emulador, importa o certificado do emulador. Para mais informações, consulte Exportar certificados do emulador de base de dados Azure Cosmos.

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 Python
• Saiba mais sobre as melhores práticas para o SDK Python