你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站,请访问 https://docs.azure.cn。
对将 Azure Cosmos DB Python SDK 与 API for NoSQL 帐户配合使用时出现的问题进行故障排除
适用范围: NoSQL
重要
本文仅介绍 Azure Cosmos DB Python SDK 的故障排除。 有关详细信息,请参阅 Azure Cosmos DB Python SDK 自述文件发行说明、包 (PyPI)、包 (Conda) 和性能提示。
本文介绍将 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*
标记。
重要
建议使用最新版本的 Python SDK。 可在此处查看版本历史记录
此库使用标准的日志记录库来记录诊断信息。 有关 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 系统(例如 Red Hat)的打开文件总数存在上限。 Linux 中的套接字以文件形式实现,因此,此上限也限制了连接总数。 运行以下命令。
ulimit -a
允许的最大打开文件数(标识为“nofile”)至少需要是连接池大小的两倍。 有关详细信息,请参阅 Azure Cosmos DB Python SDK 性能提示。
如果应用部署在没有公共 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 模拟器 HTTPS 证书是自签名证书。 要使 Python SDK 能够正常使用模拟器,请导入模拟器证书。 有关详细信息,请参阅导出 Azure Cosmos DB 模拟器证书。
如果使用 HTTP 代理,请确保它支持 SDK ConnectionPolicy
中配置的连接数。
否则,将遇到连接问题。
查询指标有助于确定查询在何处花费的时间最多。 在查询指标中,可以查看查询在客户端与后端上花费的时间。 详细了解查询性能指南。
- 了解 Python SDK 的性能准则
- 了解 Python SDK 的最佳做法