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

GILT FÜR: NoSQL

In diesem Artikel werden allgemeine Probleme, Problemumgehungen, Diagnoseschritte und Tools bei Verwendung des .NET SDK mit Azure Cosmos DB for NoSQL-Konten behandelt. Das .NET 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.

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 Diagnosezeichenfolge aus den Vorgängen und/oder Ausnahmen.

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.

Capture-Diagnose

Alle Antworten im SDK, einschließlich CosmosException, haben eine Diagnostics-Eigenschaft. In dieser Eigenschaft werden alle Informationen zu einer einzelnen Anforderung aufgezeichnet, unter anderem auch, ob es Wiederholungsversuche oder vorübergehende Fehler gab.

Die Diagnosen werden als Zeichenfolge zurückgegeben. Der String ändert sich mit jeder Version, da er für die Fehlersuche in verschiedenen Szenarien verbessert wurde. Mit jeder Version des SDK wird die Formatierung der Zeichenfolge geändert. Analysieren Sie die Zeichenfolge nicht, um Breaking Changes zu vermeiden. Das folgende Codebeispiel zeigt, wie Diagnoseprotokolle mit dem .NET SDK gelesen werden:

try
{
    ItemResponse<Book> response = await this.Container.CreateItemAsync<Book>(item: testItem);
    if (response.Diagnostics.GetClientElapsedTime() > ConfigurableSlowRequestTimeSpan)
    {
        // Log the response.Diagnostics.ToString() and add any additional info necessary to correlate to other logs 
    }
}
catch (CosmosException cosmosException)
{
    // Log the full exception including the stack trace with: cosmosException.ToString()
    
    // The Diagnostics can be logged separately if required with: cosmosException.Diagnostics.ToString()
}

// When using Stream APIs
ResponseMessage response = await this.Container.CreateItemStreamAsync(partitionKey, stream);
if (response.Diagnostics.GetClientElapsedTime() > ConfigurableSlowRequestTimeSpan || !response.IsSuccessStatusCode)
{
    // Log the diagnostics and add any additional info necessary to correlate to other logs with: response.Diagnostics.ToString()
}

Häufig auftretende Probleme und Problemumgehungen

Allgemeine Empfehlungen

  • Folgen Sie jedem aka.ms-Link, der in den Ausnahmedetails enthalten ist.
  • 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

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.

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.

SNAT

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

Weitere Informationen zur Problembehandlung bei Latenz finden Sie in unserem Leitfaden zur Fehlerbehebung bei Latenz.

Fehler bei der Proxyauthentifizierung

Bei Fehlern vom Typ „HTTP 407“:

Response status code does not indicate success: ProxyAuthenticationRequired (407);

Dieser Fehler wird weder vom SDK noch vom Azure Cosmos DB-Dienst verursacht. Dies ist ein Fehler im Zusammenhang mit der Netzwerkkonfiguration. In einem Proxy in Ihrer Netzwerkkonfiguration fehlt wahrscheinlich die erforderliche Proxyauthentifizierung. Wenn Sie nicht davon ausgehen, dass Sie einen Proxy verwenden, wenden Sie sich an Ihr Netzwerkteam. Wenn Sie einen Proxy verwenden, legen Sie beim Erstellen der Clientinstanz unbedingt die richtige WebProxy-Konfiguration für CosmosClientOptions.WebProxy fest.

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.

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

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