通过

你当前正在访问 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 上提供开放源代码。 它有一个积极监控的问题部分。 检查是否已提交包含解决方法的任何类似问题。 一个有用的提示是按 *Cosmos* 标记筛选问题。
  • 查看 Azure Cosmos DB Python SDK 的性能提示 ，并遵循建议的做法。
  • 如果找不到解决方案，请阅读本文的其余部分。 然后提交 GitHub 问题。 如果有向 GitHub 问题添加标记的选项，请添加标记 *Cosmos* 。

捕获和记录诊断信息

重要

建议使用最新版本的 python SDK。 可以在此处查看发布历史记录

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

可以在具有 logging_enable 参数的客户端上启用详细的 DEBUG 级别日志记录，包括请求/响应正文和未处理标头：

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% 或更多，请在配置较高的主机上运行应用。 或者，可以在更多计算机上分配负载。

检查门户指标

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

连接节流

连接限制可能是因为[主机的连接限制]或 [Azure SNAT （PAT） 端口耗尽]。

主机上的连接限制

某些 Linux 系统（如 Red Hat）对打开的文件总数有上限。 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 Cosmos DB 服务终结点添加到 Azure 虚拟机虚拟网络的子网中。 有关详细信息，请参阅 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 中配置的连接数。 否则，将遇到连接问题。

常见查询问题

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

后续步骤

  • Last updated on