Лекция 113: Конфигурация Actuator через application.properties

По умолчанию Spring Boot Actuator предоставляет множество полезных данных. Однако это не значит, что всё и всегда должно быть доступно во внешнем интерфейсе. Чем больше данных вы показываете, тем больше рисков — ведь "дружелюбный" хакер, увидев /env, может узнать куда больше, чем вам хотелось бы. Поэтому для Actuator очень важно настроить доступ, видимость и даже сами эндпоинты. Здесь на помощь приходит конфигурационный файл application.properties или его YAML-аналог application.yml.

Настройка Actuator эндпоинтов

Активируем Actuator в проекте

Если вдруг вы забыли, как добавить Actuator, напомню: достаточно подключить зависимость в вашем pom.xml (Maven) или build.gradle (Gradle).

Maven:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>

Gradle:

implementation 'org.springframework.boot:spring-boot-starter-actuator'

Включение/отключение эндпоинтов

Spring Boot Actuator предоставляет множество стандартных эндпоинтов, например /health, /metrics, /env, /loggers и т.д. Многие из них включены по умолчанию, но если вы хотите включить или выключить какие-то конкретные эндпоинты, можно сделать это через application.properties.

Пример конфигурации, включающей только эндпоинты /health и /metrics:

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

Или, наоборот, исключить несколько эндпоинтов:

management.endpoints.web.exposure.exclude=env,beans

Скрываем или показываем все эндпоинты Если вы хотите скрыть ВСЕ эндпоинты и выбрать только те, которые нужны:

management.endpoints.web.exposure.include=none

И добавляете вручную нужные:

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

Изменение базового пути эндпоинтов

По умолчанию Actuator эндпоинты доступны по пути /actuator. Однако иногда вам может понадобиться это изменить: например, из соображений безопасности или просто для красоты.

Изменить базовый путь можно с помощью следующей настройки:

management.endpoints.web.base-path=/monitoring

Теперь, вместо /actuator/health, ваш эндпоинт для проверки состояния будет доступен по /monitoring/health.

Настройка доступа и безопасности

Большинство эндпоинтов Actuator изначально доступны для всех (кроме /shutdown, который по умолчанию выключен). Но в реальных приложениях лучше ограничить доступ к метрикам и конфигурациям, чтобы злоумышленники не воспользовались этой информацией.

Для начала активируем Spring Security, если он еще не подключен: Maven:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-security</artifactId>
</dependency>

Gradle:

implementation 'org.springframework.boot:spring-boot-starter-security'

Теперь, чтобы управлять доступом к эндпоинтам:

management.endpoint.health.roles=ADMIN,USER
management.endpoint.metrics.roles=ADMIN

Здесь мы указали, что доступ к /health могут получить пользователи с ролями ADMIN или USER, а метрики /metrics доступны только для ADMIN.

Отключение эндпоинтов

Если вам совсем не нужен какой-то эндпоинт, вы можете его полностью отключить:

management.endpoint.env.enabled=false

Теперь эндпоинт /env полностью исчезнет из приложения.

Дополнительные настройки

Если вам нужно детализировать информацию для отладки, то для эндпоинтов Actuator можно настроить дополнительные уровни логирования.

Добавьте следующую строку в ваш application.properties:

logging.level.org.springframework.boot.actuate=DEBUG

Теперь Actuator будет выводить больше информации в консоль, что может быть полезно для анализа.

Настройка кастомных метрик (базово)

Кастомные метрики нужны, чтобы отслеживать специфичные аспекты вашего приложения. Например, вы хотите видеть количество активных пользователей или частоту выполнения определенной бизнес-операции. Мы изучим это подробнее в следующих лекциях, но для начала можно настроить базовые метрики через Actuator.

Пример настройки кастомной метрики в application.properties

management.metrics.tags.application=MyApplication

Этот тег добавляет пользовательскую метрику application, которая будет привязана ко всем вашим метрикам. Например, в /metrics вы начнете видеть значения с ключом application=MyApplication.

Практическое задание

Часть I: Настройка эндпоинтов

1. Включите только эндпоинты /health, /info и /metrics.
2. Измените базовый путь эндпоинтов на /monitoring.

Часть II: Управление доступом

1. Настройте доступ к /health для всех ролей, а /metrics сделайте закрытым для пользователей без роли ADMIN.
2. Полностью отключите эндпоинт /env.

Часть III: Проверка

1. Используйте Postman или браузер, чтобы проверить доступность эндпоинтов.
2. Попробуйте отправить запросы без авторизации и проверьте, какие эндпоинты доступны.

Частые ошибки

На практике часто встречаются следующие ошибки:

• "Почему у меня не включаются нужные эндпоинты?" Проверьте настройки management.endpoints.web.exposure.include. Если ничего не указано, Spring Boot включает только /health и /info.
• "Эндпоинты недоступны после изменения базового пути." Если вы изменили базовый путь, убедитесь, что теперь обращаетесь к эндпоинтам с новым префиксом. Например, вместо /actuator/health используйте /monitoring/health.
• "Незащищенные эндпоинты." Если вы забыли включить Spring Security или настроить роли, это может привести к утечке информации. Обязательно проверяйте настройки management.endpoint.<name>.roles.

Полезные ссылки

• Официальная документация Spring Boot Actuator
• Работа с Spring Security