Настройка ведения журнала в пакете SDK Azure для Java

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

• Встроенная платформа ведения журнала для временных целей отладки.
• Поддержка ведения журнала с помощью интерфейса SLF4J .

Используйте SLF4J, так как он хорошо известен в экосистеме Java и хорошо документирован. Дополнительные сведения см. в руководстве пользователя SLF4J .

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

Какую бы конфигурацию ведения журнала вы ни использовали, вы получаете один и тот же вывод журнала, поскольку весь вывод журналов в клиентских библиотеках Azure для Java проходит через абстракцию azure-core ClientLogger.

Остальная часть этой статьи содержит сведения о конфигурации всех доступных параметров ведения журнала.

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

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

Если вы используете OpenTelemetry, рекомендуется использовать распределенную трассировку вместо ведения журнала для HTTP-запросов. Дополнительные сведения см. в статье "Настройка трассировки" в пакете SDK Azure для Java.

Настройка ведения журнала HTTP с помощью переменной среды

AZURE_HTTP_LOG_DETAIL_LEVEL Используйте переменную среды для включения журналов HTTP для всех клиентов. Задайте для этой переменной одно из следующих значений:

• NONE: журналы HTTP отключены. Это значение по умолчанию.
• BASIC: журналы HTTP включают метод запроса, санизированный URL-адрес запроса, количество попыток, код ответа и длину содержимого для тел запроса и ответа.
• HEADERS: журналы HTTP включают все основные сведения и также включают заголовки, которые, как известно, безопасны для ведения журнала - то есть они не содержат секреты или конфиденциальную информацию. Полный список имен заголовков доступен в классе HttpLogOptions .
• BODY_AND_HEADERS: журналы HTTP включают все сведения, предоставляемые HEADERS уровнем, а также включают тела запросов и ответов, если они меньше 16 КБ и могут быть напечатаны.

Например, общий URL-адрес доступа с подписью (SAS) для хранилища BLOB-объектов Azure логируется в следующем формате: https://myaccount.blob.core.windows.net/pictures/profile.jpg?sv=REDACTED&st=REDACTED&se=REDACTED&sr=REDACTED&sp=REDACTED&rscd=REDACTED&rsct=REDACTED&sig=REDACTED

Настройте ведение журнала HTTP в коде

Построитель клиентов Azure, реализующий интерфейс HttpTrait<T> , поддерживает конфигурацию ведения журнала HTTP на основе кода. Конфигурация на основе кода применяется к отдельным экземплярам клиента и предоставляет дополнительные параметры и настройки по сравнению с конфигурацией переменной среды.

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

HttpLogOptions httpLogOptions = new HttpLogOptions()
        .setLogLevel(HttpLogDetailLevel.HEADERS)
        .addAllowedHeaderName("Accept-Ranges")
        .addAllowedQueryParamName("label");

ConfigurationClient configurationClient = new ConfigurationClientBuilder()
        .httpLogOptions(httpLogOptions)
        ...
        .buildClient();

Этот код включает http-журналы с заголовками и добавляет Accept-Ranges заголовок ответа и label параметр запроса в соответствующие списки разрешений. После этого изменения эти значения отображаются в созданных журналах.

Полный список параметров конфигурации см. в документации по HttpLogOptions.

Стандартный логгер (для временной отладки)

Как отмечалось, все клиентские библиотеки Azure используют SLF4J для ведения журнала, но есть резервный средство ведения журнала по умолчанию, встроенное в клиентские библиотеки Azure для Java. Этот средство ведения журнала по умолчанию предназначено для случаев, когда вы развертываете приложение и нуждаетесь в ведении журнала, но не сможете повторно развернуть приложение с включенным средство ведения журнала SLF4J. Чтобы включить этот средство ведения журнала, сначала убедитесь, что средство ведения журнала SLF4J не существует (так как оно имеет приоритет), а затем задайте AZURE_LOG_LEVEL переменную среды. В следующей таблице показаны значения, допустимые для этой переменной среды:

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

Ведение журнала SLF4J

По умолчанию настройте ведение журнала с помощью платформы ведения журналов, поддерживаемой SLF4J. Сначала включите соответствующую реализацию ведения журнала SLF4J в качестве зависимости от проекта. Дополнительные сведения см. в разделе "Объявление зависимостей проекта" для ведения журнала в руководстве пользователя SLF4J. Затем настройте средство ведения журнала для работы в вашей среде, например, установите уровни ведения журнала, настройте, какие классы регистрировать, а какие нет, и так далее. Некоторые примеры приведены по ссылкам в этой статье, но дополнительные сведения см. в документации по выбранной платформе ведения журнала.

Формат журнала

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

• Дата и время с точностью миллисекунда
• Уровень серьезности логов
• Имя логгера
• Имя потока
• Сообщение

Примеры см. в документации для используемой платформы ведения журнала.

Структурированное журналирование

Помимо ведения журнала распространенных свойств, упомянутых ранее, клиентские библиотеки Azure аннотируют сообщения журнала с дополнительной информацией, если это применимо. Например, можно увидеть журналы в формате JSON, содержащие az.sdk.message, причем контекст записан как другие корневые свойства, как показано в следующем примере:

16:58:51.038 INFO  c.a.c.c.i.C.getManifestProperties - {"az.sdk.message":"HTTP request","method":"GET","url":"<>","tryCount":"1","contentLength":0}
16:58:51.141 INFO  c.a.c.c.i.C.getManifestProperties - {"az.sdk.message":"HTTP response","contentLength":"558","statusCode":200,"url":"<>","durationMs":102}

При отправке журналов в Azure Monitor можно использовать язык запросов Kusto для их анализа. В следующем запросе приведен пример:

traces
| where message startswith "{\"az.sdk.message"
| project timestamp, logger=customDimensions["LoggerName"], level=customDimensions["LoggingLevel"], thread=customDimensions["ThreadName"], azSdkContext=parse_json(message)
| evaluate bag_unpack(azSdkContext)

Дальнейшие действия

Теперь, когда вы знаете, как работает ведение журнала в пакете SDK Azure для Java, рассмотрите возможность просмотра следующих статей. В этих статьях содержатся рекомендации по настройке некоторых наиболее популярных платформ ведения журнала Java для работы с SLF4J и клиентскими библиотеками Java:

• java.util.logging
• Обратный вход
• Log4J
• Трассировка