诊断和排查在使用 Azure Cosmos DB .NET SDK 时出现的问题

项目
04/22/2024

适用范围： NoSQL

本文介绍将 .NET SDK 与 Azure Cosmos DB for NoSQL 帐户配合使用时出现的常见问题、解决方法、诊断步骤和工具。 .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 虚拟机虚拟网络的子网添加 Azure Cosmos DB 服务终结点。有关详细信息，请参阅 Azure 虚拟网络服务终结点。

启用服务终结点后，不再从公共 IP 向 Azure Cosmos DB 发送请求，而是发送虚拟网络和子网标识。如果仅允许公共 IP，则此更改可能会导致防火墙丢失。如果使用防火墙，则在启用服务终结点后，请使用虚拟网络 ACL 将子网添加到防火墙。
将公共 IP 分配给 Azure VM。

网络延迟过高

有关延迟故障排除的详细信息，请参阅我们的延迟故障排除指南。

代理身份验证失败

如果看到显示为 HTTP 407 的错误：

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

此错误不由 SDK 生成，也不来自 Azure Cosmos DB 服务。该错误与网络配置相关。网络配置中的代理很可能缺少所需的代理身份验证。如果你不希望使用代理，请联系网络团队。如果使用代理，请确保在创建客户端实例时在 CosmosClientOptions.WebProxy 上设置正确的 WebProxy 配置。

常见查询问题

查询指标有助于确定查询在何处花费的时间最多。在查询指标中，可以查看查询在客户端与后端上花费的时间。详细了解查询性能指南。

如果遇到“Unable to load DLL 'Microsoft.Azure.Cosmos.ServiceInterop.dll' or one of its dependencies:”错误并且正在使用 Windows，则应升级到最新的 Windows 版本。

后续步骤

了解 .NET SDK 的性能准则
了解 .NET SDK 的最佳做法

通过