Diagnostizieren und Behandeln von Problemen bei Verwendung des .NET SDK für Azure Cosmos DB

GILT FÜR: SQL-API

Dieser Artikel behandelt allgemeine Probleme, Problemumgehungen, Diagnoseschritte und Tools bei der Verwendung des .NET SDK mit Azure Cosmos DB-SQL-API-Konten. Das .NET SDK bietet eine clientseitige logische Darstellung für den Zugriff auf die Azure Cosmos DB-SQL-API. Dieser Artikel beschreibt hilfreiche Tools und Vorgehensweisen für Problemfälle.

Checkliste für die Problembehandlung

Gehen Sie die folgende Prüfliste durch, bevor Sie Ihre Anwendung in die Produktion überführen. Mithilfe der Prüfliste werden einige häufige Probleme vermieden, die möglicherweise auftreten. Sie können ein Problem auch schnell diagnostizieren, sobald es auftritt:

  • Verwenden Sie das neueste SDK. SDKs in der Vorschauversion sollten nicht für die Produktion verwendet werden. Dadurch wird verhindert, dass bekannte Probleme, die bereits behoben wurden, erneut auftreten.
  • Überprüfen Sie die Leistungstipps, und implementieren Sie die Empfehlungen. Dadurch können Skalierungs-, Latenz- und andere Leistungsprobleme vermieden werden.
  • Aktivieren Sie die SDK-Protokollierung, um die Problembehandlung zu unterstützen. Die Aktivierung der Protokollierung kann die Leistung beeinträchtigen, weshalb es am besten ist, sie nur für die Problembehandlung zu aktivieren. Sie können die folgenden Protokolle aktivieren:
  • Protokollmetriken im Azure-Portal. Metriken im Portal zeigen die Azure Cosmos DB-Telemetriedaten, die hilfreich sind, um festzustellen, ob das Problem im Zusammenhang mit Azure Cosmos DB steht oder ob es von der Clientseite kommt.
  • Protokollieren Sie die DiagnosticsString-Eigenschaft im V2 SDK oder die Diagnostics-Eigenschaft im V3 SDK in den Antworten der Punktoperationen.
  • Protokollieren Sie in allen Abfrageantworten die SQL-Abfragemetriken.
  • Führen Sie das Setup für die SDK-Protokollierung aus.

Sehen Sie sich den Abschnitt Häufig auftretende Probleme und Problemumgehungen in diesem Artikel an.

Überprüfen Sie den Problemabschnitt auf GitHub, der aktiv überwacht wird. Überprüfen Sie, ob Sie ein ähnliches Problem finden, für das bereits eine Problemumgehung dokumentiert wurde. Wenn Sie keine Lösung gefunden haben, legen Sie ein GitHub-Problem an. Bei dringenden Problemen können Sie ein Supportticket öffnen.

Häufig auftretende Probleme und Problemumgehungen

Allgemeine Empfehlungen

  • Führen Sie Ihre App nach Möglichkeit in der gleichen Azure-Region wie Ihr Azure Cosmos DB-Konto aus.
  • Aufgrund fehlender Ressourcen auf Ihrem Clientcomputer kann es zu Verbindungs-/Verfügbarkeitsproblemen kommen. Wir empfehlen, die CPU-Auslastung auf Knoten zu überwachen, auf denen der Azure Cosmos DB-Client ausgeführt wird, und hoch bzw. zentral zu skalieren, wenn ihre Last hoch ist.

Überprüfen der Metriken im Portal

Das Überprüfen der Metriken im Portal hilft festzustellen, 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.

Wiederholungslogik

Das Cosmos DB SDK versucht bei jedem E/A-Fehler, den fehlgeschlagenen Vorgang zu wiederholen, sofern eine Wiederholung im SDK möglich ist. Es ist eine bewährte Methode, einen Wiederholungsversuch für jeden Fehler durchzuführen, doch müssen insbesondere Schreibfehler behandelt/wiederholt werden. Es wird empfohlen, das neueste SDK zu verwenden, da die Wiederholungslogik kontinuierlich verbessert wird.

  1. E/A-Fehler bei Lese- und Abfragevorgängen werden vom SDK wiederholt, ohne dass sie dem Endbenutzer angezeigt werden.
  2. Schreibvorgänge (Erstellen, Aktualisieren/Einfügen, Ersetzen, Löschen) sind nicht idempotent, und daher kann das SDK die fehlgeschlagenen Schreibvorgänge nicht immer blind wiederholen. Es ist erforderlich, dass die Anwendungslogik des Benutzers den Fehler behandelt und den Wiederholungsversuch durchführt.
  3. Unter Beheben von Problemen bei der Verfügbarkeit von SDKs werden Wiederholungen für Cosmos DB-Konten in mehreren Regionen erläutert.

Wiederholungsentwurf

Die Anwendung sollte so konzipiert sein, dass sie bei jeder Ausnahme einen Wiederholungsversuch ausführt, sofern es sich nicht um ein bekanntes Problem handelt, bei dem Wiederholungen nicht helfen. Anforderungstimeouts vom Typ 408 können beispielsweise vorübergehend sein, sodass Wiederholungsversuche möglicherweise erfolgreich sind. Bei diesen Fehlern sollte die Anwendung den Vorgang wiederholen. Bei Fehlern vom Typ 400 sollte die Anwendung dagegen keinen Wiederholungsversuch ausführen, da bei diesen Fehlern in der Regel ein Problem mit der Anforderung vorliegt, das zuerst gelöst werden muss. Wenn Sie für einen Fehler vom Typ 400 einen Wiederholungsversuch ausführen, wird das Problem nicht behoben, und derselbe Fehler tritt erneut auf. In der folgenden Tabelle sind bekannte Fehler aufgeführt, und in der Spalte „Wiederholbar“ ist angegeben, für welche Fehler Wiederholungsversuche ausgeführt sollten.

Allgemeine Fehlerstatuscodes

Statuscode Wiederholbar BESCHREIBUNG
400 Nein Ungültige Anforderung (d. h. ungültiger JSON-Code, falsche Header, falscher Partitionsschlüssel im Header)
401 Nein Nicht autorisiert
403 Nein Verboten
404 Nein Ressource nicht gefunden
408 Ja Timeout bei der Anforderung
409 Nein Konflikt: Die ID, die bei einem Schreibvorgang für eine Ressource angegeben wurde, wird bereits von einer vorhandenen Ressource verwendet. Verwenden Sie eine andere ID für die Ressource, um dieses Problem zu beheben. Die ID muss in allen Dokumenten mit demselben Partitionsschlüsselwert eindeutig sein.
410 Ja Frühere Ausnahmen (vorübergehender Fehler, der nicht gegen die SLA verstößt)
412 Nein Fehler bei Vorbedingung: Bei dem Vorgang wurde ein ETag angegeben, das sich von der auf dem Server verfügbaren Version unterscheidet. Es liegt also ein Fehler mit optimistischer Nebenläufigkeit vor. Wiederholen Sie die Anforderung nach dem Lesen der neuesten Version der Ressource und dem Aktualisieren des eTag für die Anforderung.
413 Nein Anforderungsentität zu groß
429 Ja Bei einem Fehler vom Typ 429 kann der Vorgang sicher wiederholt werden. Sie können diesen Fehler vermeiden, indem Sie dem Link für Zu viele Anforderungen folgen.
449 Ja Vorübergehender Fehler, der nur bei Schreibvorgängen auftritt und bei dem der Vorgang sicher wiederholt werden kann. Dieser Fehler kann auf ein Entwurfsproblem hinweisen, bei dem zu viele gleichzeitige Vorgänge versuchen, dasselbe Objekt in Cosmos DB zu aktualisieren.
500 Ja Der Vorgang war aufgrund eines unerwarteten Dienstfehlers fehlerhaft. Senden Sie eine Azure-Supportanfrage, um den Support zu kontaktieren.
503 Ja Dienst nicht verfügbar

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. Diese Situation kann zu einer Bandbreiteneinschränkung der Verbindung, zum Beenden der Verbindung oder den oben erwähnten Timeouts von Anforderungen führen.

Azure SNAT-Ports werden nur verwendet, wenn Ihr virtueller Computer eine private IP-Adresse besitzt und eine Verbindung mit einer öffentlichen IP-Adresse hergestellt wird. Es gibt zwei Problemumgehungen, um die Azure-SNAT-Einschränkung zu vermeiden (vorausgesetzt, dass Sie bereits eine einzelne Clientinstanz für die gesamte Anwendung verwenden):

  • 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.

Hohe Netzwerklatenz

Eine hohe Netzwerklatenz kann mithilfe der DiagnosticsString-Eigenschaft im V2 SDK oder der Diagnostics-Eigenschaft im V3 SDK ermittelt werden.

Wenn keine Timeouts vorliegen und die Diagnose einzelne Anforderungen zeigt, in denen die hohe Latenz ersichtlich ist.

Die Diagnose kann aus jeder beliebigen ResponseMessage, ItemResponse, FeedResponse oder CosmosException durch die Eigenschaft Diagnostics abgerufen werden:

ItemResponse<MyItem> response = await container.CreateItemAsync<MyItem>(item);
Console.WriteLine(response.Diagnostics.ToString());

Netzwerkinteraktionen in der Diagnose sind beispielsweise:

{
    "name": "Microsoft.Azure.Documents.ServerStoreModel Transport Request",
    "id": "0e026cca-15d3-4cf6-bb07-48be02e1e82e",
    "component": "Transport",
    "start time": "12: 58: 20: 032",
    "duration in milliseconds": 1638.5957
}

Gibt an, wo der Wert duration in milliseconds die Latenz zeigt.

Diese Latenz kann mehrere Ursachen haben:

Häufige Probleme bei Abfragen

Anhand der Metriken zu Abfragen können Sie bestimmen, wo die Abfrage die meiste Zeit verbringt. Sie können erkennen, wie viel Zeit im Back-End und auf dem Client verbracht wird. Weitere Informationen zur Behandlung von Problemen bei der Abfrageleistung.

  • Wenn die Back-End-Abfrage schnell zurückgegeben wird und viel Zeit auf den Client verbringt, überprüfen Sie die Last auf dem Computer. Es ist wahrscheinlich, dass nicht genügend Ressourcen vorhanden sind und das SDK darauf wartet, dass Ressourcen für die Bearbeitung der Antwort verfügbar werden.

  • Wenn die Back-End-Abfrage langsam ist, versuchen Sie, die Abfrage zu optimieren, und sehen Sie sich die aktuelle Indizierungsrichtlinie an.

    Hinweis

    Für eine bessere Leistung wird die Windows-64-Bit-Hostverarbeitung empfohlen. Das SQL SDK enthält die native Datei „ServiceInterop.dll“, um Abfragen lokal zu analysieren und zu optimieren. „ServiceInterop.dll“ wird nur auf der Windows x64-Plattform unterstützt. Bei Linux und anderen nicht unterstützten Plattformen, bei denen die Datei „ServiceInterop.dll“ nicht verfügbar ist, erfolgt ein zusätzlicher Netzwerkaufruf an das Gateway, um die optimierte Abfrage zu erhalten.

Wenn der Fehler Unable to load DLL 'Microsoft.Azure.Cosmos.ServiceInterop.dll' or one of its dependencies: auftritt und Sie Windows verwenden, sollten Sie ein Upgrade auf die neueste Windows-Version ausführen.

Nächste Schritte