Устранение неполадок при использовании пакета Python SDK для Azure Cosmos DB с API для учетных записей NoSQL

ОБЛАСТЬ ПРИМЕНЕНИЯ: NoSQL

В этой статье рассматриваются распространенные проблемы, обходные пути, этапы диагностики и средства при использовании Python SDK с Azure Cosmos DB для работы с учетными записями NoSQL. Пакет SDK для Python для Azure Cosmos DB предоставляет логическое представление на стороне клиента для доступа к Azure Cosmos DB для NoSQL. В этой статье описываются средства и подходы, которые помогут вам, если вы столкнетесь с проблемами.

Начните с этого списка:

• Ознакомьте с разделом Распространенные проблемы и их обходные решения в этой статье.
• Просмотрите пакет SDK для Python в центральном репозитории Azure Cosmos DB, который доступен с открытым исходным кодом на сайте GitHub. Он имеет раздел проблем, который активно отслеживается. Проверьте, подана ли уже заявка на похожую проблему с обходным решением. Одним из полезных советов является фильтрация проблем по тегу *Cosmos* .
• Ознакомьтесь с советами по производительности пакета SDK для Python для Azure Cosmos DB и следуйте рекомендациям.
• Следуйте указаниям в оставшейся части этой статьи, если решение не нашлось. Затем сообщите о проблеме в GitHub. Если есть возможность добавить теги в проблему GitHub, добавьте *Cosmos* тег.

Ведение журнала и сбор диагностики

Эта библиотека использует стандартную библиотеку логирования для диагностики. Основные сведения о сеансах HTTP (URL-адресах, заголовках и т. д.) регистрируются на уровне INFO.

Подробное ведение журнала уровня отладки, включая тела запросов и ответов и неотредактированные заголовки, можно включить на клиенте с аргументом 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)

Кроме того, вы можете выполнить журнал с помощью CosmosHttpLoggingPolicyфункции , которая расширяется от ядра HttpLoggingPolicyAzure, передавая средство ведения журнала в logger аргумент. По умолчанию оно будет использовать поведение из 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.
• Проверьте использование ЦП на узле, где выполняется приложение. Если используются 50 или более процентов ЦП, запустите приложение на узле с лучшей конфигурацией. Можно также распределить нагрузку на большее число компьютеров.
  • Если приложение запущено в службе Azure Kubernetes, вы можете использовать Azure Monitor для мониторинга использования ЦП.

Проверка метрик портала

Проверка метрик портала поможет определить, связана ли проблема с клиентом или со службой. Например, если метрики содержат большое количество запросов с кодом состояния HTTP 429 (означающим ограничение), это означает, что запросы ограничиваются. В этом случае просмотрите сведения в разделе Слишком высокая частота запросов.

Регулирование подключения

Регулирование подключений может произойти из-за [ограничения подключения на хост-компьютере] или [исчерпания портов SNAT (PAT) Azure].

Ограничение числа подключений на узле

Некоторые системы Linux (например, Red Hat) имеют ограничение на общее число открытых файлов. Сокеты в Linux реализованы как файлы, поэтому это число также существенно ограничивает общее число подключений. Выполните следующую команду.

ulimit -a

Максимальное разрешенное количество открытых файлов, которые определены как "nofile", должно быть по крайней мере вдвое больше, чем размер пула подключений. Дополнительные сведения см. в советах по производительности пакета SDK для Python для Azure Cosmos DB.

Нехватка портов SNAT (PAT) Azure

Если ваше приложение развернуто в службе "Виртуальные машины Azure" без общедоступного IP-адреса, по умолчанию порты Azure SNAT используются для установления подключений к любой конечной точке вне вашей виртуальной машины. Количество разрешенных подключений от виртуальной машины к конечной точке Azure Cosmos DB ограничивается конфигурацией Azure SNAT.

Порты Azure SNAT используются, только если у виртуальной машины есть частный IP-адрес и процесс на виртуальной машине пытается установить подключение к общедоступному IP-адресу. Избежать ограничений Azure SNAT можно двумя способами:

• Добавьте конечную точку службы Azure Cosmos DB к подсети виртуальной сети для службы "Виртуальные машины Azure". Дополнительные сведения см. в статье Конечные точки служб для виртуальной сети Azure.

  При включении конечной точки службы запросы больше не отправляются с общедоступного IP-адреса в Azure Cosmos DB. Вместо этого отправляются идентификаторы виртуальной сети и подсети. Это изменение может привести к сбою брандмауэра, если разрешены только общедоступные IP-адреса. Если вы используете брандмауэр, при включении конечной точки службы добавьте подсеть в брандмауэре с помощью списков управления доступом для виртуальных сетей.

• Назначьте общедоступный IP-адрес виртуальной машине Azure.

Не удается связаться со службой — брандмауэр

azure.core.exceptions.ServiceRequestError: указывает, что пакет SDK не может связаться со службой. Следуйте ограничению подключения на хост-компьютере.

Ошибка подключения к эмулятору Azure Cosmos DB

Сертификат HTTPS эмулятора для Azure Cosmos DB является самозаверяющим. Чтобы пакет SDK Python работал с эмулятором, импортируйте сертификат эмулятора. Дополнительные сведения см. в статье Экспорт сертификатов эмулятора для Azure Cosmos DB.

Прокси-сервер HTTP

При использовании прокси-сервера HTTP убедитесь, что он может поддерживать число подключений, указанное в свойстве ConnectionPolicy пакета SDK. В противном случае возникнут проблемы с подключением.

Типичные проблемы с запросами

Метрики запроса помогут определить, на что запрос тратит больше всего времени. С помощью метрик запроса можно узнать, какая часть работы выполняется во внутренней службе, а какая в клиенте. Дополнительные сведения см. в руководстве по повышению производительности запросов.

Следующие шаги

• Сведения о рекомендациях по производительности пакета SDK для Python
• Узнайте о лучших практиках для Python SDK