Общие сведения об устранении неполадок с пакетом SDK Azure для Java

Статья
10/23/2023

В этой статье представлено множество средств устранения неполадок, доступных при использовании пакета SDK Azure для Java, а также ссылки на другие статьи с дополнительными сведениями.

Пакет SDK Azure для Java состоит из множества клиентских библиотек — один или несколько для каждой службы Azure, которая существует. Мы убедитесь, что все клиентские библиотеки созданы в соответствии с согласованным, высоким стандартом, с общими шаблонами конфигурации, ведения журнала, обработки исключений и устранения неполадок. Дополнительные сведения см. в статье "Использование пакета SDK Azure для Java".

Так как устранение неполадок может охватывать такую широкую тему, мы разработали следующие руководства по устранению неполадок, которые могут потребоваться просмотреть:

Устранение неполадок проверки подлинности удостоверений Azure охватывает методы проверки подлинности, распространенные ошибки для типов учетных данных в клиентской библиотеке Java для удостоверений Azure и действия по устранению этих ошибок.
Устранение неполадок конфликтов версий зависимостей охватывает темы, связанные с диагностикой, устранением и минимизацией конфликтов зависимостей. Эти конфликты могут возникать при использовании клиентских библиотек Azure SDK для Java в системах, созданных с помощью таких средств, как Maven и Gradle.
Устранение проблем с сетью охватывает темы, связанные с отладкой HTTP за пределами клиентской библиотеки, используя такие инструменты, как Fiddler и Wireshark.

Вместе с этими общими руководствами по устранению неполадок мы также предоставляем руководства по устранению неполадок, относящихся к библиотеке. Сейчас доступны следующие руководства:

Помимо этих документов, следующее содержимое содержит рекомендации по использованию ведения журнала и обработки исключений, так как это относится к пакету SDK Azure для Java.

Использование ведения журнала в пакете SDK Azure для Java

В следующих разделах описывается включение различных типов ведения журнала.

Включение ведения журнала клиента

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

Включение ведения журнала HTTP-запросов и ответов

При устранении неполадок рекомендуется просматривать HTTP-запросы по мере их отправки и получения между службами Azure. Чтобы включить ведение журнала полезных данных HTTP-запроса и ответа, можно настроить почти все клиентские библиотеки Azure SDK для Java в своих построителях клиентов, как показано в следующем примере. В частности, обратите особое внимание на httpLogOptions метод в построителе клиентов и значения перечисления, доступные в HttpLogDetailLevel.

ConfigurationClient configurationClient = new ConfigurationClientBuilder()
        .connectionString(connectionString)
        .httpLogOptions(new HttpLogOptions().setLogLevel(HttpLogDetailLevel.BODY_AND_HEADERS))
        .buildClient();

Этот код изменяет ведение журнала HTTP-запросов и ответов для одного экземпляра клиента. Кроме того, можно настроить протоколирование HTTP-запросов и ответов для всего приложения, задав AZURE_HTTP_LOG_DETAIL_LEVEL переменную среды одному из значений в следующей таблице. Важно отметить, что это изменение включает ведение журнала для каждого клиента Azure, поддерживающего ведение журнала HTTP-запроса и ответа.

Значение	Уровень ведения журнала
`none`	Ведение журнала HTTP-запросов и ответов отключено.
`basic`	Регистрирует только URL-адреса, методы HTTP и время завершения запроса.
`headers`	Регистрирует все в BASIC, а также все заголовки запросов и ответов.
`body`	Записывает все данные в BASIC, а также весь текст запроса и ответа.
`body_and_headers`	Записывает все данные в заголовки и текст.

Примечание.

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

clientBuilder.httpLogOptions(new HttpLogOptions()
    .addAllowedHeaderName("safe-to-log-header-name")
    .addAllowedQueryParamName("safe-to-log-query-parameter-name"))

Обработка исключений в пакете SDK Azure для Java

Большинство методов службы клиента Azure SDK для Java вызывают httpResponseException или более конкретный подкласс при сбое. Тип HttpResponseException содержит подробный объект ошибки ответа, который предоставляет конкретные полезные сведения о том, что пошло не так, и включает в себя корректирующие действия для устранения распространенных проблем. Эти сведения об ошибке можно найти в свойстве HttpResponseException сообщения объекта. Так как эти исключения являются исключениями среды выполнения, справочная документация JavaDoc не вызывает их явным образом.

В следующем примере показано, как перехватывать это исключение с синхронным клиентом:

try {
    ConfigurationSetting setting = new ConfigurationSetting().setKey("myKey").setValue("myValue");
    client.getConfigurationSetting(setting);
} catch (HttpResponseException e) {
    System.out.println(e.getMessage());
    // Do something with the exception
}

С помощью асинхронных клиентов можно перехватывать и обрабатывать исключения в обратных вызовах ошибок, как показано в следующем примере:

ConfigurationSetting setting = new ConfigurationSetting().setKey("myKey").setValue("myValue");
asyncClient.getConfigurationSetting(setting)
    .doOnSuccess(ignored -> System.out.println("Success!"))
    .doOnError(
        error -> error instanceof ResourceNotFoundException,
        error -> System.out.println("Exception: 'getConfigurationSetting' could not be performed."));

Использование трассировки в пакете SDK Azure для Java

Пакет SDK Azure для Java обеспечивает полную поддержку трассировки, что позволяет просматривать поток выполнения с помощью кода приложения и клиентских библиотек, которые вы используете. Вы можете включить трассировку в клиентских библиотеках Azure с помощью пакета SDK OpenTelemetry или с помощью агента, совместимого с OpenTelemetry. OpenTelemetry — это популярная платформа наблюдаемости с открытым кодом для создания, записи и сбора данных телеметрии для ориентированного на облако программного обеспечения.

Дополнительные сведения о включении трассировки в пакете SDK Azure для Java см. в статье "Настройка трассировки" в пакете SDK Azure для Java.

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

Если рекомендации по устранению неполадок, описанные в этой статье, не помогают устранить проблемы при использовании клиентских библиотек пакета SDK Azure для Java, рекомендуется отправить проблему в репозитории Azure SDK для Java GitHub.

Поделиться через