Behandeln von Problemen beim Verwenden des Azure Cosmos DB Python SDK mit API für NoSQL-Konten

In diesem Artikel werden häufige Probleme, Problemumgehungen, Diagnoseschritte und Tools behandelt, wenn Sie Azure Cosmos DB Python SDK mit Azure Cosmos DB für NoSQL-Konten verwenden. Azure Cosmos DB Python SDK bietet clientseitige logische Darstellung für den Zugriff auf die Azure Cosmos DB für 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.
• Schauen 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 Abschnitt mit Problemen , der aktiv überwacht wird. Ü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 *Cosmos* Tag.
• Lesen Sie die Leistungstipps für Azure Cosmos DB Python SDK, und befolgen Sie die vorgeschlagenen Methoden.
• Lesen Sie den Rest dieses Artikels, wenn Sie keine Lösung gefunden haben. Führen Sie dann ein GitHub-Problem aus. Wenn ihrem GitHub-Problem eine Option zum Hinzufügen von Tags hinzugefügt werden kann, fügen Sie ein *Cosmos* Tag hinzu.

Protokollierung und Erfassung der Diagnose

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

Detaillierte DEBUG-Ebenenprotokollierung, einschließlich Anforderungs-/Antworttexte und unredigierte Header, kann auf einem Client mit dem logging_enable Argument 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 dem CosmosHttpLoggingPolicy den Vorgang protokollieren, der sich vom Azure Core HttpLoggingPolicy erstreckt, indem Sie Ihren Logger an das logger-Argument übergeben. Standardmäßig verwendet es das Verhalten von HttpLoggingPolicy. Wenn Sie das enable_diagnostics_logging Argument übergeben, wird das CosmosHttpLoggingPolicyArgument aktiviert und enthält zusätzliche Informationen in der Antwort, die für das Debuggen von Cosmos-Problemen relevant ist.

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 man einen Logger an die einzelne Anforderung übergibt. Wenn Sie jedoch das CosmosHttpLoggingPolicy verwenden möchten, um zusätzliche Informationen abzurufen, muss das enable_diagnostics_logging-Argument beim Client-Konstruktor ü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:

• Stellen Sie sicher, dass die App in derselben Region wie Ihr Azure Cosmos DB-Konto ausgeführt wird.
• Ü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. Oder Sie können die Last auf mehr Computern verteilen.
  • Wenn Sie Ihre Anwendung auf Azure Kubernetes Service ausführen, können Sie Azure Monitor verwenden, um die CPU-Auslastung zu überwachen.

Ü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

Die Verbindungsdrosselung kann aufgrund einer [Verbindungsgrenze auf einem Hostcomputer] oder [Azure SNAT (PAT)-Portausschöpfung auftreten].

Verbindungslimit auf einem Hostcomputer

Einige Linux-Systeme, z. B. Red Hat, haben eine obere Grenze für die Gesamtanzahl der geöffneten Dateien. Sockets in Linux werden als Dateien implementiert, sodass diese Zahl auch die Gesamtanzahl der Verbindungen einschränkt. Führen Sie den folgenden Befehl aus.

ulimit -a

Die Anzahl der maximal zulässigen geöffneten Dateien, die als "nofile" identifiziert werden, muss mindestens doppelt ihre Größe des Verbindungspools aufweisen. Weitere Informationen finden Sie in den Leistungstipps zum Azure Cosmos DB Python SDK.

Azure SNAT (PAT)-Portausschöpfung

Wenn Ihre App auf virtuellen Azure-Computern ohne öffentliche IP-Adresse bereitgestellt wird, richten Azure SNAT-Ports standardmäßig Verbindungen zu einem beliebigen Endpunkt außerhalb Ihrer VM ein. 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 Ihre VM über eine private IP-Adresse verfügt und ein Prozess von der VM versucht, eine Verbindung mit einer öffentlichen IP-Adresse herzustellen. Es gibt zwei Problemumgehungen, um die Azure SNAT-Einschränkung 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 Ihrer Azure-VM eine öffentliche IP zu.

Der Dienst kann nicht erreicht werden – Firewall

azure.core.exceptions.ServiceRequestError: gibt an, dass das SDK den Dienst nicht erreichen kann. Folgen Sie dem Verbindungsgrenzwert auf einem Hostcomputer.

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

Das HTTPS-Zertifikat des Azure Cosmos DB-Emulators ist selbstsigniert. Damit das Python SDK mit dem Emulator funktioniert, importieren Sie das Emulatorzertifikat. Weitere Informationen finden Sie unter Exportieren von Azure Cosmos DB-Emulatorzertifikaten.

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

• Informationen zu Leistungsrichtlinien für das Python SDK
• Erfahren Sie mehr über die bewährten Methoden für das Python SDK