使用 Azure Cosmos DB .NET SDK 時診斷和疑難解答問題

發行項
08/15/2024

適用於：NoSQL

本文說明搭配 Azure Cosmos DB for NoSQL 帳戶使用 .NET SDK 時的常見問題、因應措施、診斷步驟與工具。 .NET SDK 提供用戶端邏輯表示法來存取 Azure Cosmos DB for NoSQL。此文章所說明的工具和方法，可以在您遇到任何問題時提供協助。

疑難排解問題的檢查清單

將您的應用程式移至實際執行環境之前，請考慮下列檢查清單。使用檢查清單會防止您可能看到的幾個常見問題。您也可以在問題發生時快速診斷：

請使用最新的 SDK。不應針對實際執行環境使用預覽 SDK。這樣可以防止發生已修正的已知問題。
檢閱效能祕訣並遵循建議的做法。這有助於防止調整、延遲和其他效能問題。
啟用 SDK 記錄以協助您針對問題進行疑難排解。啟用記錄可能會影響效能，因此最好只有在針對問題進行疑難排解時才啟用。您可以啟用下列記錄：
- 記錄計量，透過使用 Azure 入口網站。入口網站計量會顯示 Azure Cosmos DB 遙測，這有助於判斷問題是否對應到 Azure Cosmos DB 或來自用戶端。
- 記錄來自作業和/或例外狀況的診斷字串。

查看此文章的常見問題和因應措施一節。

檢查受到主動監視的 GitHub 問題區段。查看您是否有任何含有已提出因應措施的類似問題。如果您找不到解決方案，請提出 GitHub 問題。您可以開啟緊急問題的支援票證。

擷取診斷

SDK 中的所有回應 (包括 CosmosException) 都具有 Diagnostics 屬性。此屬性記錄與單一要求相關的所有資訊，包括是否有重試或任何暫時性失敗。

診斷以字串形式傳回。每個版本會改進以針對不同情節進行疑難排解，所以此字串也隨之變更。在每一版的 SDK 中，此字串的格式都有重大變更。請勿剖析此字串，以免造成重大變更。下列程式碼範例示範如何透過使用 .NET SDK 來讀取診斷記錄：

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()
}

常見問題和因應措施

一般建議

遵循例外狀況詳細資料中包含的任何 aka.ms 連結。
盡可能在與 Azure Cosmos DB 帳戶相同的 Azure 區域中執行您的應用程式。
由於用戶端電腦上的資源不足，您可能會遇到連線能力/可用性問題。建議您在執行 Azure Cosmos DB 用戶端的節點上監視 CPU 使用率，並在高負載執行時相應增加/相應放大。

檢查入口網站計量

檢查入口網站計量有助於判斷是否為用戶端問題，或者服務是否有問題。例如，如果計量包含高比率的速率限制要求 (HTTP 狀態碼 429)，這表示要求正在進行節流處理，然後檢查要求率太大區段。

重試設計

如需如何設計具復原性應用程式的指導，並瞭解 SDK 的重試語意，請參閱使用 Azure Cosmos DB SDK 設計具復原性的應用程式指南。

SNAT

如果您的應用程式部署於不具公用 IP 位址的 Azure 虛擬機器上，則 Azure SNAT 連接埠預設會建立與您 VM 外部任何端點的連線。從 VM 到 Azure Cosmos DB 端點所允許的連線數目會受到 Azure SNAT 設定所限制。這種情況會導致連線節流、連線關閉，或上述的要求逾時。

只有當您的 VM 有私人 IP 位址連線到公用 IP 位址時，才會使用 Azure SNAT 連接埠。有兩種因應措施可避免 Azure SNAT 限制 (前提是您已在整個應用程式中使用單一用戶端執行個體)：

將 Azure Cosmos DB 服務端點新增至您的 Azure 虛擬機器虛擬網路。如需詳細資訊，請參閱 Azure 虛擬網路服務端點。

啟用服務端點時，要求不再會從公用 IP 傳送到 Azure Cosmos DB。改為傳送虛擬網路和子網路身分識別。如果只允許公用 IP，此變更可能會導致防火牆卸除。如果您使用防火牆，當您啟用服務端點時，請使用虛擬網路 ACL 將子網路新增至防火牆。
指派公用 IP 給您的 Azure VM。

高網路延遲

如需延遲疑難排解的詳細資訊，請參閱我們的延遲疑難排解指南。

Proxy 驗證失敗

如果您看到顯示為 HTTP 407 的錯誤：

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

此錯誤並非由 SDK 產生，也不是來自 Azure Cosmos DB 服務。這是與網路設定相關的錯誤。您網路設定中的 Proxy 很可能缺少必要的 Proxy 驗證。如果您不想要使用 Proxy，請連絡您的網路小組。如果您使用 Proxy，在建立用戶端執行個體時，請務必在 CosmosClientOptions.WebProxy 上設定正確的 WebProxy 設定。

常見的查詢問題

查詢計量有助於判斷查詢耗費大部分時間的位置。您可以從查詢計量查看在後端與用戶端花費多少時間。深入了解查詢效能指南。

如果您遇到下列錯誤：Unable to load DLL 'Microsoft.Azure.Cosmos.ServiceInterop.dll' or one of its dependencies: 而且是使用 Windows，您應該升級至最新的 Windows 版本。

下一步

了解 .NET SDK 的效能指導方針
了解 .NET SDK 的最佳做法

共用方式為