Диагностика и устранение неполадок при использовании пакета SDK Azure Cosmos DB для .NET

  • Статья

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

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

Контрольный список для устранения неполадок

Перед тем как переносить приложение в рабочую среду, примените этот контрольный список. Использование этого контрольного списка поможет предотвратить несколько распространенных проблем. Кроме того, с ним вы сможете быстрее диагностировать причины возникновения проблем.

  • Используйте пакет SDK последней версии. Предварительные версии пакетов SDK не следует использовать для приложений в рабочей среде. Это предотвратит проявление известных проблем, которые уже исправлены.
  • Просмотрите советы по повышению производительности и следуйте рекомендациям. Это поможет предотвратить проблемы с масштабированием, задержками и производительностью в целом.
  • Включите ведение журнала для пакета SDK. Это поможет устранить неполадки. Ведение журнала может ухудшить производительность, поэтому мы рекомендуем включать его только на время устранения неполадок. Вы можете включить следующие журналы:
    • Журнал метрик на портале Azure. В метриках портала отображаются данные телеметрии для Azure Cosmos DB. Это позволяет разделить проблемы, возникающие на стороне Azure Cosmos DB и на стороне клиента.
    • В журнал заносятся строки диагностики для операций и (или) исключений.

Ознакомьте с разделом Распространенные проблемы и их обходные решения в этой статье.

Проверьте раздел проблем на GitHub, который активно отслеживается. Вы можете там найти уже готовое обходное решение похожей проблемы. Если вы не нашли решение, создайте запрос на сайте GitHub. Если проблема срочная, можете создать запрос в службу поддержки.

Сбор диагностических данных

Для всех ответов в пакете SDK, включая CosmosException, доступно свойство Diagnostics. В это свойство записываются все сведения, связанные с одним запросом, в том числе сведения о повторных попытках и временных сбоях.

Система возвращает данные свойства в виде строки. От версии к версии содержимое этой строки изменяется. Это связано с совершенствованием программного обеспечения для улучшения процесса устранения неполадок в различных сценариях. В каждой версии пакета SDK будут критические изменения форматирования этой строки. Не анализируйте эту строку, чтобы избежать проблем, связанных с критическими изменениями. В следующем примере кода показано, как выполнять чтение данных из журналов диагностики с помощью пакета SDK для .NET.

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, где расположена учетная запись Azure Cosmos DB.
  • Вы можете столкнуться с проблемами подключения или доступности из-за недостатка ресурсов на клиентском компьютере. Мы рекомендуем отслеживать нагрузку на ЦП в узлах, где выполняется клиент Azure Cosmos DB, и выполнять вертикальное или горизонтальное масштабирование при чрезмерно высокой нагрузке.

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

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

Повторная попытка разработки

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

SNAT.

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

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

Большие задержки в сети

Дополнительные сведения об устранении неполадок с задержками см. в этом руководстве.

Сбой при проверке подлинности прокси-сервера

Если отображаются такие ошибки, как HTTP 407:

Response status code does not indicate success: ProxyAuthenticationRequired (407);

Эта ошибка не создается пакетом SDK и не поступает из службы Azure Cosmos DB. Это ошибка, связанная с конфигурацией сети. Для прокси-сервера в конфигурации сети, скорее всего, отсутствует требуемая проверка подлинности прокси-сервера. Если вы не планируете использовать прокси-сервер, обратитесь к своей команде, ответственной за работу сети. Если вы используете прокси-сервер, убедитесь, что при создании экземпляра клиента настроена правильная конфигурация WebProxy в CosmosClientOptions.WebProxy.

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

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

Если при работе в среде Windows произойдет ошибка Unable to load DLL 'Microsoft.Azure.Cosmos.ServiceInterop.dll' or one of its dependencies:, следует обновить систему до последней версии Windows.

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