Spring actuator что это
Изучение и анализ Spring Boot приложения с помощью Actuator и jq
Хотя Actuator в основном используется в производственной среде, он также может помочь нам во время разработки и сопровождения. Мы можем использовать его для изучения и анализа нового приложения Spring Boot.
Пример кода
Эта статья сопровождается примером рабочего кода на GitHub.
Зачем использовать Actuator для анализа и изучения приложения?
Представим, что мы впервые работаем над новой кодовой базой на основе Spring Boot. Мы, вероятно, изучим структуру папок, посмотрим на имена папок, проверим имена пакетов и имена классов, чтобы попытаться построить модель приложения в нашем уме. Мы могли бы сгенерировать некоторые UML диаграммы, чтобы помочь определить зависимости между модулями, пакетами, классами и т. д.
Хотя это важные шаги, они дают нам только статичное представление о приложении. Мы не можем получить полную картину, не понимая, что происходит во время выполнения. Например, что представляют собой все создаваемые Spring Beans? Какие конечные точки API доступны? Каковы все фильтры, через которые проходит запрос?
Построение этой мысленной модели формы выполнения приложения очень полезно. Она позволит глубже погрузиться в чтение и более эффективно понять важные части кода.
Общий обзор Spring Boot Actuator
Начнем с краткого обзора по Spring Boot Actuator.
На верхнем уровне, когда мы работаем с Actuator, мы делаем следующие шаги:
Добавляем Actuator как зависимость к нашему проекту
Включаем и открываем конечные точки
Защищаем и настраиваем конечные точки
Давайте кратко рассмотрим каждый из этих шагов.
Шаг 1. Добавьте Actuator зависимость
Добавление Actuator в наш проект похоже на добавление любой другой зависимости. Вот фрагмент для Maven pom.xml :
Если бы мы использовали Gradle, мы бы добавили в файл build.gradle следующий фрагмент :
Шаг 2. Включите и откройте конечные точки
Доступ к отключенной конечной точке возвращает ошибку HTTP 404:
Мы можем предоставить доступ к конечным точкам через HTTP и / или JMX. Хотя обычно используется HTTP, для некоторых приложений может быть предпочтительнее JMX.
Мы можем раскрыть конечные точки, установив management.endpoints.[web|jmx].exposure.include для списка идентификаторов конечных точек, которые мы хотим раскрыть. Вот как мы можем открыть metrics конечную точку, например:
Чтобы конечная точка была доступна, она должна быть включена и доступна.
Шаг 3. Защитите и настройте конечные точки
В этой статье мы не будем подробно рассматривать вопросы защиты конечных точек, поскольку мы в основном заинтересованы в использовании Spring Actuator для изучения приложения в нашей локальной среде разработки. Вы можете найти подробности в документации здесь.
Краткое введение в jq
jq представляет собой JSON-процессор командной строки. Он работает как фильтр, принимая входные данные и производя выходные данные. Доступно множество встроенных фильтров, операторов и функций. Мы можем комбинировать фильтры, направлять выходной сигнал одного фильтра в другой и т. д.
Предположим, у нас в файле есть следующий JSON sample.json :
Это объект, содержащий массив объектов «student» с некоторыми деталями для каждого ученика.
Рассмотрим jq команду, чтобы понять, что происходит:
перебирать массив students
вывод каждого student для следующего фильтра
выборка атрибута name из объекта student
Теперь давайте составим список студентов, изучающих такие предметы, как «экология», «обществоведение» и т. д.:
Рассмотрим команду еще раз:
перебирать массив students
вывод каждого student для следующего фильтра
выберите студента, если его массив subjects содержит элемент со строкой «наука»
С одним небольшим изменением мы можем снова собрать эти элементы в массив:
Все, что нам нужно было сделать, это заключить все выражение в квадратные скобки.
Мы можем использовать jq как для фильтрации, так и для изменения формы JSON:
Изучение приложения Spring Boot
В оставшейся части этой статьи мы будем использовать Actuator для изучения работающего приложения Spring Boot. Само приложение представляет собой очень упрощенный пример приложения для обработки заказов электронной коммерции. В нем есть только скелетный код, необходимый для иллюстрации идей.
Хотя доступно множество конечных точек Actuator, мы сосредоточимся только на тех, которые помогают нам понять структуру приложения во время выполнения.
се конечные точки, которые мы увидим, включены по умолчанию. Давйте откроем их:
Использование конечной точки отображения
Проверка доступных API-интерфейсов обычно является хорошим местом для начала знакомства с сервисом. Конечная точка отображения предоставляет все маршруты и обработчики, а также дополнительные сведения.
Давайте перейдем на конечную точку с помощью команды curl и направим ответ в jq, чтобы красиво его распечатать:
jq для дальнейшей фильтрации этой информации. Поскольку мы знаем имена пакетов из нашей службы, jq будет выбирать только те обработчики, которые содержат имя нашего пакета io.reflectoring.springboot.actuator:
Давайте воспользуемся jq для дальнейшей фильтрации этой информации. Поскольку мы знаем имена пакетов из нашей службы, jq select будет выбирать только те обработчики, которые содержат имя нашего пакета io.reflectoring.springboot.actuator :
Точно так же мы можем проверить, через какие фильтры проходят наши запросы, прежде чем они достигнут контроллеров:
Использование конечной точки beans
Теперь давайте посмотрим на список созданных bean-компонентов:
Опять же, мы можем использовать jq для фильтрации ответов и сосредоточиться на тех частях ответа, которые нам интересны:
Это дает представление обо всех компонентах приложения и их зависимостях с высоты птичьего полета.
Чем это полезно? Мы можем получить дополнительную информацию из этого типа представления: например, если мы видим некоторую зависимость, повторяющуюся в нескольких bean-компонентах, вероятно, в нем инкапсулированы важные функции, которые влияют на несколько потоков. Мы могли бы отметить этот класс как важный, который мы хотели бы понять, когда углубимся в код. Или, возможно, этот bean-компонент является God object, который требует некоторого рефакторинга, когда мы поймем кодовую базу.
Использование конечной точки startup
В отличие от других конечных точек, которые мы видели, для настройки конечной точки startup требуются некоторые дополнительные действия. Мы должны обеспечить реализацию ApplicationStartup для нашего приложения:
Как эта информация может помочь нам в исследовании приложения? Если мы знаем, какие шаги требуют больше времени при запуске, мы можем проверить эту область кодовой базы, чтобы понять, почему. Например, может случиться так, что, прогрев кэша выполняет предварительную выборку данных из базы данных или предварительное вычисление некоторых данных.
Поскольку приведенный выше ответ содержит много деталей, давайте сузим его, отфильтровав по spring.beans.instantiate шагу, а также отсортируем события по продолжительности в порядке убывания:
Что здесь произошло? Почему мы не получили ответа? Вызов конечной точки startup также очищает внутренний буфер. Повторим попытку после перезапуска приложения:
Команда jq здесь была немного сложнее по сравнению с предыдущими. Давайте разберемся, чтобы понять, что происходит:
.timeline.events | sort_by(.duration) | reverse
отсортируйте массив timeline.events по свойству duration и реверсируйте результат, чтобы он был отсортирован в порядке убывания
перебирать результирующий массив
выберите элемент объекта только в том случае, если свойство startupStep элемента name содержит текст «instantiate»
создать новый объект JSON со свойствами beanName и duration
Скобки над всем выражением указывают на то, что мы хотим собрать все созданные объекты JSON в массив.
Использование конечной точки env
Конечная точка env дает обобщенное представление всех свойств конфигурации приложения. Сюда входят конфигурации из application.properties файла, системные свойства JVM, переменные среды и т. д.
Мы можем использовать конечную точку env, чтобы увидеть, есть ли в приложении конфигурации, установленные с помощью переменных окружения, какие файлы jar находятся в его пути к классам и т. д.:
Использование конечной точки scheduledtasks
Эта конечная точка позволяет нам проверять, выполняет ли приложение какую-либо задачу периодически, используя @Scheduled аннотацию Spring :
Из ответа мы видим, что приложение генерирует некоторые отчеты каждый день в 12 часов дня и что существует фоновый процесс, который выполняет некоторую очистку каждые 15 минут. Затем мы могли бы прочитать код этих конкретных классов, если бы мы хотели знать, что это за отчеты, какие шаги необходимо предпринять для очистки брошенной корзины и т. д.
Использование конечной точки caches
Эта конечная точка перечисляет все кэши приложений:
Использование конечной точки health
Конечная точка health показывает информацию о здоровье приложения:
Обычно это неглубокая проверка здоровья. Хотя это полезно в производственной среде для частой проверки балансировщиком нагрузки, это не помогает нам в понимании приложения.
Многие приложения также реализуют глубокие проверки работоспособности, которые могут помочь нам быстро узнать, каковы внешние зависимости приложения, к каким базам данных и брокерам сообщений оно подключается и т. д.
Прочтите эту статью на Reflectoring, чтобы узнать больше о реализации проверок работоспособности с помощью Actuator.
Использование конечной точки metrics
Эта конечная точка перечисляет все метрики, сгенерированные приложением:
Затем мы можем получить данные отдельных показателей:
Особенно полезна проверка доступных пользовательских метрик API. Это может дать нам некоторое представление о том, что важно в этом приложении с точки зрения бизнеса. Например, из списка показателей мы можем видеть, что есть индикатор, orders.placed.counter который, вероятно, сообщает нам, сколько заказов было размещено за определенный период времени.
Заключение
Вы можете поиграть с полным приложением, иллюстрирующим эти идеи, используя код на GitHub.
Учебник по Spring Boot Admin
Контролируйте и управляйте своими приложениями Spring Boot с помощью приятного пользовательского интерфейса поверх конечных точек Spring Boot Actuator.
Spring Boot Actuator
Actuator: Spring Boot Production Monitoring and Management
Мониторинг и управление вашим работающим приложением с помощью Spring Boot Actuator 2.x. Соберите метрики или проверьте здоровье приложения.
Примечание переводчика. На Хабре есть аналогичная статья:
Введение в Spring Boot Actuator
Spring Boot Admin
Actuator является отличным и мощным инструментом, кроме того, его конечные точки легко и удобно использовать с помощью другого приложения — вы просто используете вызов REST-сервиса. Однако человеку использовать Actuator не очень удобно. Для пользователя гораздо проще иметь хороший пользовательский интерфейс, который можно использовать для просмотра всех данных мониторинга и управления вашим приложением. Это именно то, для чего служит Spring Boot Admin. Он предоставляет вам удобную прослойку пользовательского интерфейса поверх конечных точек Actuator с несколькими дополнительными функциями сверх того.
Spring Boot Admin не является модулем, предоставленным командой Spring, он был создан компанией под названием Codecentric. Тем не менее, его код общедоступен на Github и является бесплатным.
Клиент и сервер
В отличие от Actuator, Spring Boot Admin фактически состоит из двух частей — клиентской и серверной.
Серверная часть содержит пользовательский интерфейс администратора и работает независимо от отслеживаемых приложений. Клиентская часть находится в отслеживаемом приложении, которое регистрируется в серверной части.
Таким образом, даже если наше приложение не работает или не работает должным образом, сервер мониторинга все еще работает. Теперь представьте, что у вас есть несколько приложений (таких как микросервисы Spring Boot), и каждое из них может работать в нескольких экземплярах. С традиционным мониторингом Actuator это сложно, так как вам нужно получить доступ к каждому из них по отдельности, и вам нужно отслеживать, сколько экземпляров и где запущено.
При использовании Spring Boot Admin каждый экземпляр отслеживаемого приложения (клиента) регистрируется на сервере после его запуска. Тогда у вас есть единственная точка (Admin Server), где вы можете проверить их все.
Исходный код
Исходный код готового приложения можно найти в этом репозитории Github.
Настройка сервера
Давайте сначала рассмотрим, как настроить Spring Boot Admin Server. Начнем со нового Spring Boot приложения. Вы можете легко создать его, используя Spring Initializr. Обязательно включите web модуль.
После создания проекта, первое, что нам нужно, это добавить зависимость Spring Boot Admin Server:
Обратите внимание, что хотя этот проект не создан Pivotal, вы можете найти клиентский и серверный модули для Spring Boot Admin в Spring Initializr. Далее нам нужно включить Admin Server, аннотируя наш основной класс приложения с помощью аннотации @EnableAdminServer:
Вот и все. Теперь вы можете запустить свое приложение и после открытия страницы вы должны увидеть такой экран:
Сервер работает, но клиенты еще не зарегистрированы. Давайте исправим это.
Настройка клиента
Как и при настройке сервера, первый шаг — необходимо добавить правильную зависимость к существующему приложению:
Затем вам нужно определить URL, где работает ваш Admin Server. Добавьте эту строку в ваш файл application.properties:
Добавление Actuator
Теперь у вас должна быть возможность запустить и клиент, и сервер. Просто убедитесь, что нет конфликта портов, поскольку оба приложения по умолчанию используют 8080. В целях тестирования вы можете установить server.port = 0 в ваших application.properties, чтобы ваш клиент использовал случайный порт при запуске. Таким образом, вы можете протестировать запуск нескольких экземпляров, работающих на разных портах.
При открытии пользовательского интерфейса Admin Server вы должны увидеть свое приложение. Когда вы нажимаете на название приложения, должна появиться страница с информацией о приложении.
Если вы видите экран, подобный приведенному выше, с минимальным количеством информации, это означает, что в вашем проекте нет Actuator. Помните, что Spring Boot Admin использует конечные точки Actuator под капотом. К счастью, вам нужно просто добавить простую зависимость, а автоконфигурация позаботится обо всем остальном.
Однако большинство конечных точек по умолчанию не отображаются в Actuator. Вам нужно изменить свою конфигурацию в application.properties, чтобы выставить их:
После предоставления конечных точек Actuator вы должны увидеть гораздо больше информации в интерфейсе администратора:
Подробное руководство по настройке Spring Boot Actuator можно найти в этой статье.
Примечание переводчика. И в статье на Хабре.
Безопасность
Теперь, когда все работает, мы должны убедиться, что наши конечные точки Actuator и интерфейс администратора не доступны для всех.
Безопасность клиентов
Если вы уже используете Spring Security, вышеперечисленное не будет работать для вас, так как конечные точки привода по умолчанию защищены и ваш сервер администратора не сможет получить к ним доступ. Если вы еще не используете Spring Security, сначала нужно добавить зависимость:
В целях тестирования вы можете временно отключить безопасность конечных точек Actuator с помощью management.security.enabled = false. Однако мы хотим, чтобы безопасность была включена. Если вы используете обычную аутентификацию, вы можете просто указать имя пользователя и пароль в файле свойств. Эти учетные данные будут использоваться Admin Server для аутентификации на конечных точках привода клиента:
По умолчанию, если не настроено иначе, Spring Boot по умолчанию использует пользователя user и автоматически сгенерированный пароль при каждом запуске приложения. Вы можете проверить пароль в консоли во время запуска. Если вы хотите явно указать имя пользователя и пароль, необходимые для вашего приложения, вы можете указать их в своих свойствах:
Безопасность сервера
Как и в случае с клиентом, нам нужно добавить зависимость Spring Security:
Теперь давайте настроим имя пользователя и пароль, необходимые для входа на Admin Server в вашем application.properties:
Сейчас на вашем клиенте вам также необходимо добавить эти учетные данные, иначе он не сможет зарегистрироваться на сервере:
Теперь вернемся к серверной части. Последнее, что нам нужно, это добавить конфигурацию Spring Security для защиты пользовательского интерфейса администратора:
Это позволит обеспечить доступ к интерфейсу администратора только для аутентифицированных пользователей, использующих базовую аутентификацию HTTP для входа в систему. Сама страница входа и статические ресурсы пользовательского интерфейса, включая javascript, HTML и CSS, являются открытыми. В противном случае вы не сможете войти в систему. Тогда существует защита от подделки межсайтовых запросов (CSRF, Cross-Site Request Forgery) на основе файлов cookie. Вы можете видеть, что некоторые пути игнорируются в защите CSRF — это потому, что Admin Server в настоящее время не имеет надлежащей поддержки.
Теперь после перезагрузки вы должны увидеть красивый экран входа, защищающий ваш Admin Server:
Cloud Discovery
Клиент Spring Boot Admin — не единственный способ зарегистрировать ваши приложения на сервере. Admin Server также поддерживает Spring Cloud Service Discovery. Вы можете прочитать больше в официальной документации или в статье «Spring Cloud Discovery with Spring Boot Admin».
Уведомления
Как только у вас запущен мониторинг, вы хотите получать уведомления, когда что-то идет не так. Хорошая новость заключается в том, что Spring Admin предоставляет широкий спектр вариантов уведомлений.
Если вы посещаете страницу Admin Server в первый раз, она запрашивает разрешение на отображение push-уведомлений на вашем компьютере. Всякий раз, когда возникает проблема, вы получите всплывающее сообщение.
Другие уведомления нуждаются в простой настройке. Обычно это означает просто предоставить несколько записей в вашем application.properties. В настоящее время поддерживаются следующие сервисы:
Настройка почтовых уведомлений
Если вы хотите включить почтовые уведомления, вам нужно добавить Spring email зависимость в вашу серверную часть:
Затем вам нужно определить ваш SMTP-сервер, который будет использоваться для отправки уведомлений и учетных данных по электронной почте. Обновите свои application.properties вашего Admin Server.
Затем вам нужно определить получателей и отправителей.
Создание RESTful web-сервиса с Spring Boot Actuator
Spring Boot Actuator является подпроектом Spring Boot. Он добавляет несколько сервисов бизнес-уровня без особых усилий с вашей стороны. В этом уроке вы создадите приложение и увидите, как добавить эти сервисы.
Что вы создадите
В этом уроке освещаются шаги создания «hello world» RESTful Web Service c использованием Spring Boot Actuator. Вы создадите сервис, который принимает HTTP GET запрос:
А в ответ возвращает JSON:
Также есть некоторые возможности для вашего приложения «из коробки» управлять сервисом в рабочем (или других) окружениях. Бизнес логика сервиса построена так же, как в Создание RESTful Web-сервиса. Вам необязательно использовать это руководство для изучения, однако это может быть интересным, чтобы впоследствии сравнить результаты.
Что вам потребуется
Как проходить этот урок
Как и большинство уроков по Spring, вы можете начать с нуля и выполнять каждый шаг, либо пропустить базовые шаги, которые вам уже знакомы. В любом случае, вы в конечном итоге получите рабочий код.
Чтобы начать с нуля, перейдите в Настройка проекта.
Настройка проекта
Для начала вам необходимо настроить базовый скрипт сборки. Вы можете использовать любую систему сборки, которая вам нравится для сборки проетов Spring, но в этом уроке рассмотрим код для работы с Gradle и Maven. Если вы не знакомы ни с одним из них, ознакомьтесь с соответсвующими уроками Сборка Java-проекта с использованием Gradle или Сборка Java-проекта с использованием Maven.
Создание структуры каталогов
Создание файла сборки Gradle
Ниже представлен начальный файл сборки Gradle. Файл pom.xml находится здесь. Если вы используете Spring Tool Suite (STS), то можете импортировать урок прямо из него.
Spring Boot gradle plugin предоставляет множество удобных возможностей:
Запуск пустого сервиса
Ниже представлено пустое Spring MVC приложение.
Аннотация @EnableAutoConfiguration обеспечивает загрузку по умолчанию (подобно встроенному сервлет контейнеру) в зависимости от содержания вашего classpath и других вещей. Она также ключает Spring MVC @EnableWebMvc аннотацию для активации web компонентов.
Не все компоненты определены в этом приложении, но этого достаточно для запуска и просмотра некоторых возможностей Actuator’а. Команда SpringApplication.run() знает как запустить web приложение. Все, что вам нужно, это запустить команду:
Вы ещё не писали код, так что же случится? Подождите, пока сервер запустится, перейдите в терминал и попробуйте выполнить:
Вы получили «ОК», значит все хорошо.
Более подробную информацию смотрите на Spring Boot Actuator Project.
Создание класса представления
Для начала, давайте подумаем, как будет выглядеть ваше API.
Для моделирования представления сообщения, создайте класс представления:
Теперь вам нужно создать контроллер точки выхода, который будет обслуживать этот класс.
Создание контроллера ресурсов
Ключевое отличие между обычным(human-facing) контроллером и REST контроллером в том, как создан ответ. Вместо того, чтобы опираться на представление(такое как JSP) для отображения данных модели в HTML, REST контроллер просто возвращает данные, записанные прямо в тело ответа.
Аннотация @ResponseBody говорит Spring MVC не отображать модель в представлении, а писать возвращаемый объект в тело ответа. Делается это с помощью одного из ковертеров сообщений Spring. Т.к. Jackson 2 находится в classpath, то значит MappingJackson2HttpMessageConverter будет обрабатывать конвертацию Greeting в JSON при условии, что заголовок Accept запроса указывает, что необходимо вернуть JSON.
Создание выполняемым главный класс
Вы можете запустить приложение из собственного главного класса, либо мы можем сделать это напрямую из одного из конфигурационных классов. Самым простым способом является использование вспомогательного класса SpringApplication :
Сборка исполняемого JAR
Вы можете собрать единый исполняемый JAR-файл, который содержит все необходимые зависимости, классы и ресурсы. Это делает его легким в загрузке, версионировании и развертывании сервиса как приложения на протяжении всего периода разработки, на различных средах и так далее.
Затем вы можете запустить JAR-файл:
Запуск сервиса
Если вы используете Gradle, вы можете запустить ваш сервис из командной строки:
Как вариант, вы можете запустить ваш сервис напрямую из Gradle примерно так:
Переключение на другой порт сервера
Запустите сервер снова:
Поздравляем! Вы только что разработали простой RESTful сервис, используя Spring. Вы добавили некоторые полезные встроенные сервисы благодаря Spring Boot Actuator.