Compartilhar via

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

  • Aplica-se a: ✅ NoSQL

Importante

Este artigo aborda a solução de problemas somente para o SDK do Python do Azure Cosmos DB. Consulte as notas de versão do Readme do SDK do Python do Azure Cosmos DB, o Pacote (PyPI), o Pacote (Conda) e as dicas de desempenho para obter 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 o Azure Cosmos DB para contas NoSQL. O SDK do Azure Cosmos DB para Python fornece uma representação lógica no lado do cliente para acessar o Azure Cosmos DB para 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, que está disponível no GitHub. Ele tem uma seção de problemas que é monitorada ativamente. Verifique se você encontrar algum problema semelhante com uma solução alternativa já arquivada. Uma dica útil é filtrar problemas pela *Cosmos* marca.
  • Examine as dicas de desempenho do SDK do Python do Azure Cosmos DB e siga as práticas sugeridas.
  • Leia o restante deste artigo, se você não encontrou uma solução. Em seguida, registre um problema no GitHub. Se houver uma opção para adicionar tags ao problema no GitHub, adicione uma tag *Cosmos*.

Registrando e capturando o diagnóstico

Importante

É recomendável usar a versão mais recente do SDK do Python. Você pode verificar o histórico de lançamentos aqui

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

O log detalhado de nível DEBUG, incluindo 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, você pode registrar usando o CosmosHttpLoggingPolicy, que se estende do núcleo do azure HttpLoggingPolicy, passando seu logger para o argumento logger. Por padrão, ele usará o comportamento de HttpLoggingPolicy. Passar o enable_diagnostics_logging argumento habilitará o CosmosHttpLoggingPolicy e adicionará 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 logger para a requisição específica. No entanto, se você deseja usar o CosmosHttpLoggingPolicy para obter informações adicionais, o argumento enable_diagnostics_logging 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)

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 for de 50% ou mais, execute seu aplicativo em um host com uma configuração mais alta. 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 acontecer devido a um [limite de conexão em um computador host] ou ao esgotamento da porta do [PAT (SNAT) do Azure].

Limite de conexão em um computador 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, portanto, esse número também limita o número total de conexões. Execute o comando a seguir.

ulimit -a

O número máximo de arquivos abertos permitidos, 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 do Python do Azure Cosmos DB.

Esgotamento da porta do Azure SNAT (PAT)

Se seu aplicativo for implantado em Máquinas Virtuais do Azure sem um endereço IP público, por padrão, as portas SNAT do Azure estabelecerão conexões com qualquer ponto de extremidade fora da 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 SNAT do Azure:

  • 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 endpoint do 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 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, ao habilitar o ponto de extremidade de serviço, adicione uma sub-rede ao firewall usando as ACLs de Rede Virtual.

  • Atribua um IP público à 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 se 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, 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 está sendo gasto no back-end em comparação com o cliente. Saiba mais sobre o guia de desempenho da consulta.

Próximas etapas

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