Всем привет! Меня зовут Сергей Черкасов. Я Developer Advocate в Axelix Labs и работаю над проектом Axelix. Это Java платформа с открытым исходным кодом, которая, среди прочего, позволяет отлаживать работающие приложения Spring Boot.

Я думаю любому знакомо - при расследовании инцидента логов уровня INFO часто недостаточно. Тогда для конкретного пакета или класса нужно временно включить DEBUG. Только на время инцидента или отладки, чтобы понять, в чём дело. Потом не забыть (давайте будем честны - мы 100% забудем 😁) выключить обартно.

Spring Boot позволяет изменить уровень логирования прямо в работающем процессе. Сделать это можно тремя способами. Отправить запрос в Actuator, воспользоваться интерфейсом Spring Boot Admin или управлять подключёнными сервисами через Axelix.

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

Для прямого управления обычно достаточно Actuator. Когда сервисов и реплик много, удобнее пользоваться централизованным интерфейсом.

Сравним эти подходы на одном примере. Временно включим DEBUG для пакета com.example.orderservice и восстановим предыдущий уровень после диагностики.

Как меняется уровень логирования на лету

Spring Boot задаёт начальные уровни логирования на основе параметров logging.level.* и конфигурации Logback, Log4j2 или другой поддерживаемой системы логирования. Во время работы приложения эти уровни можно менять через LoggingSystem. Новый уровень применяется к последующим событиям и хранится в памяти процесса. Файлы конфигурации остаются прежними, поэтому после перезапуска изменённое значение обычно теряется.

Каждый экземпляр приложения хранит уровень логирования отдельно. Прямой запрос к Actuator меняет его в одном экземпляре. Spring Boot Admin и Axelix позволяют изменить уровень логгера сразу во всех зарегистрированных экземплярах приложения за одну операцию.

1. Прямой запрос к приложению через Spring Boot Actuator

Эндпоинт /actuator/loggers показывает текущие уровни логгеров и позволяет менять их во время работы приложения. Для этого подключите к сервису spring-boot-starter-actuator и откройте HTTP-доступ к эндпоинту loggers.

management.endpoints.web.exposure.include=health,loggers

Теперь уровень логирования можно менять запросами к работающему приложению. В Actuator правила ролевого доступа (RBAC) к операциям с логгерами можно настроить через Spring Security. В примерах ниже предполагается, что интерфейс управления принимает токены Bearer.

# Получаем явно заданный и фактический уровни логирования.
curl -H 'Authorization: Bearer <token>' \
  'https://orderservice.example.internal/actuator/loggers/com.example.orderservice'

# Временно включаем DEBUG для пакета.
curl -X POST \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{"configuredLevel":"DEBUG"}' \
  'https://orderservice.example.internal/actuator/loggers/com.example.orderservice'

# Сбрасываем явно заданный уровень, чтобы логгер унаследовал уровень родителя.
curl -X POST \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{}' \
  'https://orderservice.example.internal/actuator/loggers/com.example.orderservice'

Если для логгера явно задан уровень INFO, ответ на запрос GET выглядит так.

{
  "configuredLevel": "INFO",
  "effectiveLevel": "INFO"
}

В configuredLevel указан уровень, заданный непосредственно для логгера. В effectiveLevel указан фактический уровень с учётом наследования. Если логгер наследует уровень, поле configuredLevel в ответе отсутствует.

Пустой объект {} сбрасывает явно заданный уровень, и логгер начинает наследовать уровень родителя. Допустим, в конфигурации приложения этому логгеру задан INFO, а его родителю — WARN. Если переключить логгер на DEBUG, а затем сбросить уровень, он будет работать на уровне WARN. Чтобы восстановить исходный INFO, сохраните значение configuredLevel перед изменением и отправьте ещё один запрос POST с этим значением.

2. Управление экземплярами через веб-интерфейс Spring Boot Admin

В Spring Boot Admin те же операции доступны через веб-интерфейс. Достаточно найти com.example.orderservice и выбрать DEBUG. Spring Boot Admin отправляет запросы к эндпоинтам Actuator нужных экземпляров.

При сбросе в Spring Boot Admin логгер переходит на уровень по умолчанию, определяемый LoggingSystem. В примере на видео логгер, для которого изначально был задан TRACE, после сброса перешёл на INFO. Это распространённое значение по умолчанию. Такое поведение может удивить, особенно если на уровне по умолчанию система пишет больше логов, чем на уровне, заданном в конфигурации.

Так работают сами эндпоинты Spring Boot Actuator. Spring Boot Admin выступает прокси и наследует их поведение.

На одной панели можно просматривать зарегистрированные экземпляры, искать логгеры и менять их уровни без прямых запросов к сервисам через curl. Для этого нужно развернуть и защитить Admin Server, зарегистрировать приложения и дать серверу доступ к их эндпоинтам Actuator. В Spring Boot Admin нет встроенных правил ролевого доступа к операциям с логгерами. Если нужен RBAC, его придётся добавить и поддерживать самостоятельно.

Если кто-то забудет вернуть исходный уровень, приложение может генерировать большой объём логов, пока это не заметят. Как мы уже видели, кнопка сброса не всегда позволяет вернуть прежнее значение.

Начиная с Spring Boot Admin 4.1.3 опциональный модуль MCP предоставляет ИИ-агентам экспериментальный доступ к тем же операциям Actuator. После включения модуля на Admin Server агенты могут получать список логгеров, проверять уровень логгера и менять его на выбранном экземпляре. По умолчанию инструменты MCP доступны всем без аутентификации.

Подробности приведены в документации Spring Boot Admin по MCP.

3. Управление через интерфейс Axelix и инструменты MCP

К каждому управляемому приложению нужно подключить легковесный Spring Boot Starter. Стартер добавляет специальный эндпоинт для работы с логгерами, который использует Axelix. Собственные эндпоинты Spring Actuator позволяют Axelix устранять ограничения стандартных эндпоинтов. Мы планируем отказаться от привязки к Actuator, в том числе для поддержки Micronaut, Quarkus и приложений без фреймворков.

Например, в Axelix Master есть встроенный настраиваемый RBAC. Все роли по умолчанию дают доступ к описанным здесь операциям с логгерами, включая изменение и сброс уровня.

При сбросе отдельного логгера в Axelix восстанавливается предыдущий уровень с учётом того, был ли он задан явно или унаследован.

Чтобы случайно не переполнить систему логами, в Axelix при смене уровня можно сразу задать таймер. По истечении указанного времени Axelix автоматически восстановит предыдущий уровень. Так меньше риск оставить DEBUG включённым после завершения диагностики.

Это особенно важно для производительности и расходов на облако, поскольку облачные провайдеры часто обрабатывают логи в своих сервисах, например в AWS CloudWatch.

Таймер работает внутри управляемого приложения и срабатывает, даже если Axelix Master потеряет связь со стартером.

Изменение уровня на всех экземплярах

В рабочей или тестовой среде часто запущено несколько экземпляров одного приложения. Например, у условного order-service может быть шесть реплик.

В Axelix можно выбрать экземпляры, на которых нужно изменить уровень логирования. По умолчанию выбраны все.

На странице логгеров Axelix откройте Instances рядом с полем поиска и выберите Select all other instances. Текущий экземпляр уже включён в выбор. Установите для логгера уровень DEBUG один раз, и изменение применится ко всем управляемым репликам. В том же списке можно выбрать только нужные реплики.

Попробуйте с ИИ-агентом

Все операции Axelix доступны пользователям через интерфейс, а ИИ-агентам — через встроенный MCP-сервер. Он входит в Axelix Master по умолчанию, поэтому достаточно установить Axelix Master.

Подключите MCP-клиент к Axelix Master и отправьте агенту такой запрос.

Проверь состояние задачи payment-processing. Почему она завершилась с ошибкой?

Агент может действовать по следующему сценарию.

  1. Получит логи нужного экземпляра приложения и определит, что в них не хватает данных для диагностики.

  2. Запросит временное изменение уровня логирования на период диагностики.

  3. Вызовет инструмент MCP для запуска задачи по расписанию. Такая операция тоже доступна в Axelix.

  4. Получит новые логи, найдёт причину сбоя и при необходимости внесёт изменения в код.

Доступ к MCP-серверу тоже регулируется через RBAC. Так можно задать, кому доступны конкретные операции.

Вывод

Для управления уровнями логирования можно обращаться к эндпоинтам Spring Boot Actuator напрямую или использовать инструменты с открытым исходным кодом, такие как Spring Boot Admin и Axelix.

Возможность

Spring Boot Actuator

Spring Boot Admin

Axelix

Веб-интерфейс для работы с логгерами

-

Да

Да

Интеграция с ИИ-агентами через MCP

-

Экспериментальный модуль, подключаемый отдельно с версии 4.1.3

Да

Управление доступом к операциям с логгерами

-

-

Встроенный RBAC

Зависимости управляемого приложения

Spring Boot Actuator

Spring Boot Actuator, Admin Client не обязателен при использовании обнаружения сервисов

Spring Boot Actuator, требуется Axelix Spring Boot Starter

Сброс уровня отдельного логгера

Возвращает уровень системы логирования по умолчанию

Возвращает уровень системы логирования по умолчанию

Восстанавливает исходный уровень

Автоматический сброс по таймеру

-

-

Да

Изменение уровня логгера на всех управляемых экземплярах за одну операцию

-

Да, в области Application с версии 2.2.0

Да, через интерфейс или API массовых операций

Важно: Для работы Axelix нужен Axelix Spring Boot Starter. Для Spring Boot Admin клиентская библиотека необязательна. Имейте это в виду.

Надеюсь, статья пригодилась. Если вас заинтересовал Axelix, исходный код доступен на GitHub.

Русскоязычное сообщество можно найти в Телеграме. Будут вопросы по установке - пишите, мы поможем!

Хорошего дня!