诊断和排查在使用 Azure Cosmos DB .NET SDK 时出现的问题
适用范围：
NoSQL
本文介绍将 .NET SDK 与 Azure Cosmos DB for NoSQL 帐户配合使用时出现的常见问题、解决方法、诊断步骤和工具。 .NET SDK 提供了客户端逻辑表示，以用于访问 Azure Cosmos DB for NoSQL。 本文介绍了在遇到任何问题时可以提供帮助的工具和方法。
问题排查清单
在将应用程序转移到生产环境之前，请考虑根据以下清单进行检查。 使用该清单有助于防止出现多个常见问题。 出现问题时可以快速诊断：
- 使用最新的 SDK。 不要将预览版 SDK 用于生产。 这样就可以避免遇到已更正的已知问题。
- 查看性能提示并按照建议的做法进行操作。 这有助于避免缩放、延迟和其他性能问题。
- 启用 SDK 日志记录以帮助排查问题。 启用日志记录可能会影响性能，因此，最好是只在排查问题时才启用日志记录。 可以启用以下日志：
请查看本文中的常见问题和解决方法部分。
查看我们积极关注的 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 将子网添加到防火墙。
网络延迟过高
有关延迟故障排除的详细信息，请参阅我们的延迟故障排除指南。
代理身份验证失败
如果看到显示为 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 版本。