对将 Azure Cosmos DB Python SDK 与 API for NoSQL 帐户配合使用时出现的问题进行故障排除

适用范围： NoSQL

本文介绍将 Azure Cosmos DB Python SDK 与 Azure Cosmos DB for NoSQL 帐户配合使用时遇到的常见问题、解决方法、诊断步骤和工具。 Azure Cosmos DB Python SDK 提供客户端逻辑表示来访问 Azure Cosmos DB for NoSQL。 本文介绍了在遇到任何问题时可以提供帮助的工具和方法。

从本列表开始：

• 请查看本文中的常见问题和解决方法部分。
• 查看 Azure Cosmos DB 中央存储库中的 Python SDK，该存储库在 GitHub 上是开源的。 该 SDK 拥有受到主动监视的问题部分。 检查是否已提交包含解决方法的任何类似问题。 一个有用的提示是按 *Cosmos* 标记筛选问题。
• 查看 Azure Cosmos DB Python SDK 的性能提示并按照建议的做法进行操作。
• 阅读本文的其余部分，如果找不到解决方案， 则提交 GitHub 问题。 如过存在向 GitHub 问题添加标记的选项，请添加 *Cosmos* 标记。

记录和捕获诊断信息

此库使用标准的日志记录库来记录诊断信息。 有关 HTTP 会话（URL、标头等）的基本信息记录在信息级别。

使用 logging_enable 参数可在客户端上启用详细的“调试”级别日志记录（包括请求/响应正文和未编辑的标头）：

import sys
import logging
from azure.cosmos import CosmosClient

# Create a logger for the 'azure' SDK
logger = logging.getLogger('azure')
logger.setLevel(logging.DEBUG)

# Configure a console output
handler = logging.StreamHandler(stream=sys.stdout)
logger.addHandler(handler)

# This client will log detailed information about its HTTP sessions, at DEBUG level
client = CosmosClient(URL, credential=KEY, logging_enable=True)

同样，即使没有为客户端启用详细日志记录，logging_enable 也可以为单个操作启用：

database = client.create_database(DATABASE_NAME, logging_enable=True)

或者，可以通过将记录器传递给 logger 参数，使用从 Azure 核心 HttpLoggingPolicy 扩展的 CosmosHttpLoggingPolicy 进行日志记录。 默认情况下，它将使用 HttpLoggingPolicy 的行为。 传入 enable_diagnostics_logging 参数会启用 CosmosHttpLoggingPolicy，并且响应中将包含与调试 Cosmos 问题相关的其他信息。

import logging
from azure.cosmos import CosmosClient

#Create a logger for the 'azure' SDK
logger = logging.getLogger('azure')
logger.setLevel(logging.DEBUG)

# Configure a file output
handler = logging.FileHandler(filename="azure")
logger.addHandler(handler)

# This client will log diagnostic information from the HTTP session by using the CosmosHttpLoggingPolicy.
# Since we passed in the logger to the client, it will log information on every request.
client = CosmosClient(URL, credential=KEY, logger=logger, enable_diagnostics_logging=True)

类似地，可以通过将记录器传递给单个请求来为单个操作启用日志记录。 但是，如果你希望使用 CosmosHttpLoggingPolicy 获取更多信息，则需要在客户端构造函数中传入 enable_diagnostics_logging 参数。

# This example enables the `CosmosHttpLoggingPolicy` and uses it with the `logger` passed in to the `create_database` request.
client = CosmosClient(URL, credential=KEY, enable_diagnostics_logging=True)
database = client.create_database(DATABASE_NAME, logger=logger)

重试设计

有关如何设计可复原的应用程序的指导并了解哪些是 SDK 的重试语义，请参阅使用 Azure Cosmos DB SDK 设计可复原的应用程序指南。

常见问题和解决方法

常规建议

为获得最佳性能：

• 确保应用与 Azure Cosmos DB 帐户在同一区域运行。
• 检查运行应用的主机 CPU 使用情况。 如果 CPU 使用率为 50% 或更高，请在具有更高配置的主机上运行应用。 或者，可将负载分发到更多计算机。
  • 如果在 Azure Kubernetes 服务上运行应用程序，则可以使用 Azure Monitor 监视 CPU 使用率。

检查门户指标

检查门户指标有助于确定问题是否与客户端相关，或者服务是否有问题。 例如，如果指标中包含较高比率的速率受限请求（HTTP 状态代码 429，表示请求受到限制），请查看请求速率过大部分。

连接限制

连接限制可能会因 [主机上的连接限制] 或 [Azure SNAT (PAT) 端口耗尽] 而发生。

主机上的连接限制

某些 Linux 系统（例如 CentOS）对打开的文件的总数设置了上限。 Linux 中的套接字以文件形式实现，因此，此上限也限制了连接总数。 运行以下命令。

ulimit -a

允许的最大打开文件数（标识为“nofile”）至少需要是连接池大小的两倍。 有关详细信息，请参阅 Azure Cosmos DB Python SDK 性能提示。

Azure SNAT (PAT) 端口耗尽

如果应用部署在没有公共 IP 地址的 Azure 虚拟机上，则默认情况下，Azure SNAT 端口用于建立与 VM 外部任何终结点的连接。 从 VM 到 Azure Cosmos DB 终结点，允许的连接数受 Azure SNAT 配置的限制。

仅当 VM 具有专用 IP 地址且来自 VM 的进程尝试连接到公共 IP 地址时，才会使用 Azure SNAT 端口。 有两种解决方法可以避免 Azure SNAT 限制：

• 向 Azure 虚拟机虚拟网络的子网添加 Azure Cosmos DB 服务终结点。 有关详细信息，请参阅 Azure 虚拟网络服务终结点。

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

• 将公共 IP 分配给 Azure VM。

无法访问服务 - 防火墙

azure.core.exceptions.ServiceRequestError: 指示 SDK 无法访问服务。 遵循主机上的连接限制。

连接到 Azure Cosmos DB 仿真器时出现故障

Azure Cosmos DB 模拟器 HTTPS 证书是自签名证书。 要使 Python SDK 能够正常使用模拟器，请导入模拟器证书。 有关详细信息，请参阅导出 Azure Cosmos DB 模拟器证书。

HTTP 代理

如果使用 HTTP 代理，请确保它支持 SDK ConnectionPolicy 中配置的连接数。 否则，将遇到连接问题。

常见查询问题

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

后续步骤

• 了解 Python SDK 的性能准则
• 了解 Python SDK 的最佳做法