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

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

В этой статье представлен обзор включения ведения журнала в приложениях, использующих пакет SDK Azure для 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-адрес запроса санируется, то есть все значения параметров запроса редактируются, за исключением api-version значения. Отдельные клиентские библиотеки могут добавлять другие параметры запроса, которые, как известно, являются безопасными для списка разрешений.

Например, общий 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 переменную среды. В следующей таблице показаны значения, допустимые для этой переменной среды:

Уровень ведения журнала Допустимые значения переменной среды
МНОГОСЛОВНЫЙ 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 Application Insights предоставляет гарантии стабильности для телеметрии запросов и зависимостей. Дополнительные сведения см. в статье "Настройка трассировки" в пакете SDK Azure для Java.

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

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