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

適用於: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 版本。

下一步