Risolvere i problemi relativi all'uso di Azure Cosmos DB Python SDK con account API per NoSQL

SI APPLICA A: NoSQL

• Python SDK
• Java SDK v4
• Async Java SDK v2
• .NET

Importante

Questo articolo illustra la risoluzione dei problemi solo per Python SDK di Azure Cosmos DB. Per altre informazioni, vedere note sulla versione leggimi di Python SDK di Azure Cosmos DB, Package (PyPI), Package (Conda) e suggerimenti sulle prestazioni.

Questo articolo illustra i problemi comuni, le soluzioni alternative, i passaggi di diagnostica e gli strumenti quando si usa Azure Cosmos DB Python SDK con gli account Azure Cosmos DB per NoSQL. Azure Cosmos DB Python SDK fornisce una rappresentazione logica lato client per accedere ad Azure Cosmos DB per NoSQL. Questo articolo descrive strumenti e approcci utili ad affrontare eventuali problemi.

Iniziamo con un elenco:

• Diamo un'occhiata alla sezione Problemi e soluzioni alternative comuni in questo articolo.
• Esaminare Python SDK nel repository centrale di Azure Cosmos DB, disponibile open source in GitHub. Include una sezione per i problemi monitorata attivamente. Verificare se è già stato pubblicato un problema simile con una soluzione alternativa. Un suggerimento utile è filtrare i problemi in base al tag *Cosmos*.
• Esaminare i suggerimenti sulle prestazioni per Azure Cosmos DB Python SDK e seguire le procedure consigliate.
• Leggere la parte restante di questo articolo, se non si trova una soluzione. Registrare poi un problema in GitHub. Se è disponibile un'opzione che consente di aggiungere tag al problema di GitHub, aggiungere un tag *Cosmos*.

Registrazione e acquisizione della diagnostica

Importante

È consigliabile usare la versione più recente di Python SDK. È possibile controllare la cronologia delle versioni qui

Questa libreria usa la libreria di registrazione standard per la diagnostica della registrazione. Le informazioni di base sulle sessioni HTTP (URL, intestazioni e così via), vengono registrate a livello di informazioni.

La registrazione dettagliata del livello DEBUG, inclusi i corpi di richiesta/risposta e le intestazioni non contrassegnate, può essere abilitata in un client con l'argomento 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)

Analogamente, logging_enable può abilitare la registrazione dettagliata per una singola operazione, anche quando non è abilitata per il client:

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

In alternativa, è possibile registrare usando CosmosHttpLoggingPolicy, che si estende dal core HttpLoggingPolicydi Azure , passando il logger all'argomento logger . Per impostazione predefinita, userà il comportamento di HttpLoggingPolicy. Il passaggio dell'argomento enable_diagnostics_logging abiliterà CosmosHttpLoggingPolicye avrà informazioni aggiuntive nella risposta relativa al debug dei problemi di 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)

Analogamente, la registrazione può essere abilitata per una singola operazione passando un logger alla singola richiesta. Tuttavia, se si desidera utilizzare CosmosHttpLoggingPolicy per ottenere informazioni aggiuntive, l'argomento enable_diagnostics_logging deve essere passato nel costruttore client.

# 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)

Riprovare a progettare

Vedere la guida per la progettazione di applicazioni resilienti con Azure Cosmos DB SDK per indicazioni su come progettare applicazioni resilienti e conoscere la semantica di retry dell'SDK.

Problemi comuni e soluzioni alternative

Suggerimenti generici

Per prestazioni ottimali:

• Assicurarsi che l'app sia in esecuzione nella stessa area dell'account Azure Cosmos DB.
• Controllare l'utilizzo della CPU nell'host in cui viene eseguita l'app. Se l'utilizzo della CPU è 50% o oltre, eseguire l'app in un host con una configurazione superiore oppure distribuire il carico su più computer.
  • Se si esegue l'applicazione nel servizio Azure Kubernetes, è possibile usare Monitoraggio di Azure per monitorare l'utilizzo della CPU.

Controllare le metriche del portale

Controllare le metriche del portale per determinare se si tratta di un problema sul lato client o se si è verificato un problema con il servizio. Ad esempio, se le metriche contengono una frequenza elevata di richieste a velocità limitata (codice di stato HTTP 429), significa che la richiesta viene limitata. Controllare la sezione Frequenza richieste troppo grande.

Limitazione della connessione

La limitazione delle connessioni può verificarsi a causa di un [limite di connessione in un computer host] o di [esaurimento delle porte SNAT (PAT) di Azure].

Limite di connessioni nel computer host

Alcuni sistemi Linux, come Red Hat, prevedono un limite massimo per il numero totale di file aperti. I socket in Linux vengono implementati come file, per cui questo numero limita anche il numero totale di connessioni. Esegui il comando seguente:

ulimit -a

Il numero massimo consentito di file aperti, identificati come "nofile", deve essere almeno il doppio della dimensione del pool di connessioni. Per altre informazioni, vedere i suggerimenti sulle prestazioni di Python SDK per Azure Cosmos DB.

Esaurimento delle porte SNAT (PAT) di Azure

Se l'app viene distribuita in macchine virtuali di Azure senza un indirizzo IP pubblico, per impostazione predefinita le porte SNAT di Azure stabiliscono le connessioni a qualsiasi endpoint all'esterno della macchina virtuale. Il numero di connessioni consentite dalla macchina virtuale all'endpoint di Azure Cosmos DB è limitato dalla configurazione SNAT di Azure.

Le porte SNAT di Azure vengono usate solo quando la macchina virtuale ha un indirizzo IP privato e un processo dalla macchina virtuale prova a connettersi a un indirizzo IP pubblico. Esistono due soluzioni alternative per evitare la limitazione per le porte SNAT di Azure:

• Aggiungere l'endpoint del servizio Azure Cosmos DB alla subnet della rete virtuale di macchine virtuali di Azure. Per altre informazioni, vedere Endpoint servizio di rete virtuale di Azure.

  Quando l'endpoint del servizio è abilitato, le richieste non vengono più inviate da un indirizzo IP pubblico ad Azure Cosmos DB. Vengono invece inviate le identità di rete virtuale e subnet. Questa modifica può comportare blocchi del firewall se sono consentiti solo indirizzi IP pubblici. Se si usa un firewall, quando si abilita l'endpoint del servizio, aggiungere una subnet al firewall tramite ACL di rete virtuale.

• Assegnare un indirizzo IP pubblico alla macchina virtuale di Azure.

Non è possibile raggiungere il servizio - Firewall

azure.core.exceptions.ServiceRequestError: indica che l'SDK non riesce a raggiungere il servizio. Seguire il limite di connessione in un computer host.

Errore di connessione all'emulatore di Azure Cosmos DB

Il certificato HTTPS dell'emulatore di Azure Cosmos DB è autofirmato. Affinché Python SDK funzioni con l'emulatore, importare il certificato dell'emulatore. Per altre informazioni, vedere Esportare i certificati dell'emulatore di Azure Cosmos DB.

Proxy HTTP

Se si usa un proxy HTTP, assicurarsi che possa supportare il numero di connessioni configurate in ConnectionPolicy dell'SDK. In caso contrario, verranno riscontrati problemi di connessione.

Problemi di query comuni

Le metriche di query consentono di determinare dove la query sta spendendo la maggior parte del tempo. Dalle metriche di query è possibile visualizzare la quantità di spesa per il back-end rispetto al client. Per altre informazioni, vedere la guida alle prestazioni delle query.

Passaggi successivi

• Informazioni sulle linee guida sulle prestazioni per Python SDK
• Informazioni sulle procedure consigliate per Python SDK