Настройка ведения журнала в 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, , informationinformational
ПРЕДУПРЕЖДЕНИЕ 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: