Настройка ведения журнала в Azure SDK для Java
В этой статье содержатся общие сведения о настройке ведения журналов для приложений, использующих Azure SDK для Java. Клиентские библиотеки Azure для Java предоставляют два варианта ведения журнала:
- Встроенная платформа ведения журналов для временной отладки.
- Поддержка ведения журнала с помощью интерфейса SLF4J.
Мы рекомендуем использовать SLF4J, поскольку использование этого интерфейса в экосистеме Java широко известное и подробно описано в документации. Дополнительные сведения см. в руководстве по SLF4J для пользователей.
В этой статье приводятся ссылки на другие статьи, посвященные большинству популярных платформ ведения журналов Java. В них содержатся примеры конфигурации и описывается, как клиентские библиотеки Azure могут использовать платформы ведения журналов.
Какой бы ни была конфигурация ведения журнала, выходные данные одного и того же журнала будут доступны в любом случае, поскольку все выходные данные журнала в клиентских библиотеках Azure для Java направляются через абстракцию ClientLogger
azure-core.
В оставшейся части этой статьи подробно описывается настройка всех доступных параметров ведения журнала.
Включение ведения журнала 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-адрес запроса санируется, то есть все значения параметров запроса редактируются, за исключением api-version
значения. Отдельные клиентские библиотеки могут добавлять другие параметры запроса, которые, как известно, являются безопасными для списка разрешений.
Например, URL-адрес Хранилище BLOB-объектов Azure url-адрес подписанного URL-адреса urlhttps://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 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
переменную среды. В следующей таблице приведены значения, допустимые для этой переменной среды.
Уровень журнала | Разрешенные значения переменных среды |
---|---|
VERBOSE | verbose , debug |
ИНФОРМАЦИОННЫХ | info , , information informational |
ПРЕДУПРЕЖДЕНИЕ | warn , warning |
ОШИБКА | err , error |
Настроив переменную среды, перезапустите приложение, чтобы активировать ее. Этот средство ведения журнала регистрируется в консоли и не предоставляет расширенные возможности настройки реализации 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)
Примечание.
Журналы клиентской библиотеки Azure предназначены для нерегламентированной отладки. Мы не рекомендуем использовать формат журнала для оповещения или мониторинга приложения. Клиентские библиотеки Azure не гарантируют стабильность сообщений журнала или ключей контекста. В таких целях рекомендуется использовать распределенную трассировку. Агент Java Аналитика приложения предоставляет гарантии стабильности для телеметрии запросов и зависимостей. Дополнительные сведения см. в статье "Настройка трассировки" в пакете SDK Azure для Java.
Следующие шаги
Теперь, когда вы знаете, как работает ведение журнала в пакете SDK Azure для Java, рассмотрите возможность просмотра следующих статей. В этих статьях содержатся рекомендации по настройке некоторых наиболее популярных платформ ведения журнала Java для работы с SLF4J и клиентскими библиотеками Java: