Behandeln von Problemen bei der Verwendung des Azure Cosmos DB Python SDK mit der API für NoSQL-Konten

GILT FÜR: NoSQL

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

Wichtig

In diesem Artikel wird nur die Problembehandlung für das Azure Cosmos DB Python SDK behandelt. Weitere Informationen finden Sie in den Ressourcen für das Azure Cosmos DB Python-SDK: Infodatei, Versionshinweise, Paket (PyPI), Paket (Conda) und Leistungstipps.

In diesem Artikel werden häufig auftretende Probleme, Problemumgehungen, Diagnoseschritte und Tools bei der Verwendung des Azure Cosmos DB Python SDK mit Azure Cosmos DB for NoSQL-Konten behandelt. Das Azure Cosmos DB Python SDK bietet eine clientseitige logische Darstellung für den Zugriff auf Azure Cosmos DB for NoSQL. Dieser Artikel beschreibt hilfreiche Tools und Vorgehensweisen für Problemfälle.

Beginnen Sie mit dieser Liste:

• Sehen Sie sich den Abschnitt Häufig auftretende Probleme und Problemumgehungen in diesem Artikel an.
• Sehen Sie sich das Python SDK im zentralen Azure Cosmos DB-Repository an, das Open Source auf GitHub verfügbar ist. Es verfügt über einen aktiv überwachten Problemabschnitt. Überprüfen Sie, ob Sie ein ähnliches Problem finden, für das bereits eine Problemumgehung dokumentiert wurde. Ein hilfreicher Tipp ist das Filtern von Problemen nach dem Tag *Cosmos*.
• Sehen Sie sich die Leistungstipps für das Azure Cosmos DB Python SDK an, und befolgen Sie die empfohlenen Methoden.
• Lesen Sie den Rest dieses Artikels, falls Sie keine Lösung gefunden haben. Reichen Sie anschließend ein GitHub-Problem ein. Wenn es eine Option zum Hinzufügen von Tags zu Ihrem GitHub-Issue gibt, fügen Sie das Tag *Cosmos* hinzu.

Protokollierung und Erfassung der Diagnose

Wichtig

Es wird empfohlen, die neueste Version des Python SDK zu verwenden. Sie können den Versionsverlauf hier einsehen

Diese Bibliothek verwendet für die Protokollierung der Diagnose die Standardprotokollierungsbibliothek. Grundlegende Informationen zu HTTP-Sitzungen (URLs, Header usw.) werden auf der INFO-Ebene protokolliert.

Eine ausführliche Protokollierung auf der DEBUG-Ebene, einschließlich Anforderungs-/Antworttexten und vollständiger Header, kann auf einem Client mit dem Argument logging_enable aktiviert werden:

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)

Ebenso kann über logging_enable die ausführliche Protokollierung für einen einzelnen Vorgang aktiviert werden, auch wenn diese Funktion für den Client nicht aktiviert ist:

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

Alternativ können Sie mit der CosmosHttpLoggingPolicy protokollieren, die sich vom Azure-Kern HttpLoggingPolicy aus erstreckt, indem Sie Ihren Logger an das Argument logger übergeben. Standardmäßig wird es das Verhalten von HttpLoggingPolicy verwenden. Wenn Sie das Argument enable_diagnostics_logging übergeben, wird die CosmosHttpLoggingPolicy aktiviert und werden zusätzliche Informationen in der Antwort vorhanden sein, die für das Debuggen von Cosmos-Problemen relevant sind.

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)

Ebenso kann die Protokollierung für einen einzelnen Vorgang aktiviert werden, indem ein Logger an die einzelne Anforderung übergeben wird. Wenn Sie jedoch die CosmosHttpLoggingPolicy verwenden möchten, um zusätzliche Informationen zu erhalten, muss das Argument enable_diagnostics_logging an den Clientkonstruktor übergeben werden.

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

Wiederholungsentwurf

In unserem Leitfaden zum Entwerfen von resilienten Anwendungen mit Azure Cosmos DB SDKs finden Sie entsprechende Anleitungen und lernen die Wiederholungssemantiken des SDK kennen.

Häufig auftretende Probleme und Problemumgehungen

Allgemeine Empfehlungen

Für eine optimale Leistung:

• Vergewissern Sie sich, dass die App in der gleichen Region ausgeführt wird, in der sich auch Ihr Azure Cosmos DB-Konto befindet.
• Überprüfen Sie die CPU-Auslastung auf dem Host, auf dem die App ausgeführt wird. Wenn die CPU-Auslastung 50 Prozent oder mehr beträgt, führen Sie Ihre App auf einem Host mit einer höheren Konfiguration aus. Alternativ können Sie die Last auf mehrere Computer verteilen.
  • Wenn Sie Ihre Anwendung in Azure Kubernetes Service ausführen, können Sie Azure Monitor zum Überwachen der CPU-Auslastung verwenden.

Überprüfen der Metriken im Portal

Indem Sie die Portalmetriken überprüfen, können Sie feststellen, ob es sich um ein Problem auf Clientseite handelt oder ob es ein Problem mit dem Dienst gibt. Wenn die Metriken beispielsweise viele Anforderungen mit Ratenbegrenzungen aufweisen (HTTP-Statuscode 429), bedeutet dies, dass die Anforderung gedrosselt wird. Siehe dann den Abschnitt Anforderungsrate zu hoch.

Verbindungsdrosselung

Eine Verbindungsdrosselung kann entweder aufgrund eines [Verbindungslimits auf dem Hostcomputer] oder aufgrund von [Azure SNAT-Portauslastung (PAT)] auftreten.

Verbindungslimit auf einem Hostcomputer

Bei einigen Linux-Systemen (beispielsweise Red Hat) gilt eine Obergrenze für die Gesamtzahl geöffneter Dateien. Da Sockets in Linux als Dateien implementiert werden, schränkt dies auch die Gesamtanzahl von Verbindungen ein. Führen Sie den folgenden Befehl aus.

ulimit -a

Die maximal zulässige Anzahl geöffneter Dateien (nofile) muss mindestens doppelt so hoch sein wie die Größe Ihres Verbindungspools. Weitere Informationen finden Sie im Artikel Leistungstipps für das Azure Cosmos DB Python SDK.

Azure SNAT-Portauslastung (PAT)

Wenn Ihre App auf einem virtuellen Azure-Computer ohne öffentliche IP-Adresse bereitgestellt wird, werden standardmäßig Azure SNAT-Ports verwendet, um Verbindungen mit beliebigen Endpunkten außerhalb Ihres virtuellen Computers herzustellen. Die Anzahl zulässiger Verbindungen des virtuellen Computers mit dem Azure Cosmos DB-Endpunkt wird durch die Azure SNAT-Konfiguration eingeschränkt.

Azure SNAT-Ports werden nur verwendet, wenn Ihr virtueller Computer eine private IP-Adresse besitzt und ein Prozess auf dem virtuellen Computer versucht, eine Verbindung mit einer öffentlichen IP-Adresse herzustellen. Es gibt zwei Problemumgehungen, um die Einschränkung durch Azure SNAT zu vermeiden:

• Fügen Sie Ihren Azure Cosmos DB-Dienstendpunkt dem Subnetz Ihres virtuellen Netzwerks von Azure Virtual Machines hinzu. Weitere Informationen finden Sie unter Azure Virtual Network-Dienstendpunkte.

  Wenn der Dienstendpunkt aktiviert ist, werden die Anforderungen nicht mehr von einer öffentlichen IP-Adresse an Azure Cosmos DB gesendet. Stattdessen wird die Identität des virtuellen Netzwerks und des Subnetzes gesendet. Diese Änderung kann zu Firewallproblemen führen, wenn nur öffentliche IP-Adressen zulässig sind. Wenn Sie eine Firewall verwenden und den Dienstendpunkt aktivieren, fügen Sie der Firewall mithilfe von VNET-ACLs ein Subnetz hinzu.

• Weisen Sie Ihrem virtuellen Azure-Computer eine öffentliche IP-Adresse zu.

Dienst nicht erreichbar – Firewall

azure.core.exceptions.ServiceRequestError: gibt an, dass das SDK den Dienst nicht erreichen kann. Befolgen Sie die Anweisungen unter Verbindungslimit auf einem Hostcomputer.

Fehler beim Herstellen einer Verbindung mit dem Azure Cosmos DB-Emulator

Das HTTPS-Zertifikat des Azure Cosmos DB-Emulators ist selbstsigniert. Importieren Sie das Emulatorzertifikat, damit das Python SDK mit dem Emulator verwendet werden kann. Weitere Informationen finden Sie unter Exportieren der Azure Cosmos DB-Emulatorzertifikate.

HTTP-Proxy

Wenn Sie einen HTTP-Proxy verwenden, vergewissern Sie sich, dass er die Anzahl von Verbindungen unterstützt, die in ConnectionPolicy des SDK konfiguriert ist. Andernfalls treten Verbindungsprobleme auf.

Häufige Probleme bei Abfragen

Anhand der Metriken zu Abfragen können Sie bestimmen, wo die Abfrage die meiste Zeit verbringt. An den Abfragemetriken können Sie erkennen, wie viel Zeit im Back-End und auf dem Client verbracht wird. Weitere Informationen finden Sie im Leitfaden zur Abfrageleistung.

Nächste Schritte

• Weitere Informationen zu den Leistungsrichtlinien für das Python SDK
• Weitere Informationen zu den bewährten Methoden für das Python SDK