Привод пружинной загрузки

1. обзор

В этой статье мы собираемся представить Spring Boot Actuator. We’ll cover the basics first, then discuss in detail what’s available in Spring Boot 1.x vs 2.x.с

Мы узнаем, как использовать, настраивать и расширять этот инструмент мониторинга в Spring Boot 1.x. Затем мы обсудим, как сделать то же самое с помощью Boot 2.x и WebFlux, используя преимущества модели реактивного программирования.

Spring Boot Actuator доступен с апреля 2014 года вместе с первым выпуском Spring Boot.

С помощьюrelease of Spring Boot 2 Actuator был переработан, и были добавлены новые интересные конечные точки.

Это руководство разделено на 3 основных раздела:

Что такое привод?
Привод Spring Boot 1.x
Привод Spring Boot 2.x

Дальнейшее чтение:

Настройте веб-приложение Spring Boot

Некоторые из наиболее полезных конфигов для приложения Spring Boot.

Создание собственного стартера с Spring Boot

Краткое и практическое руководство по созданию пользовательских стартеров Spring Boot.

Тестирование в Spring Boot

Узнайте, как Spring Boot поддерживает тестирование, чтобы эффективно писать модульные тесты.

2. Что такое привод?

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

Мониторинг нашего приложения, сбор показателей, понимание трафика или состояния нашей базы данных становится тривиальным делом с этой зависимостью.

Основным преимуществом этой библиотеки является то, что мы можем получить инструменты производственного класса без необходимости самим реализовывать эти функции.

Актуатор в основном используется дляexpose operational information about the running application - здоровье, показатели, информация, дамп, env и т. Д. Он использует конечные точки HTTP или компоненты JMX, чтобы мы могли взаимодействовать с ним.

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

2.1. Начиная

Чтобы включить Spring Boot Actuator, нам просто нужно добавить зависимостьspring-boot-actuator в наш менеджер пакетов. В Maven:


    org.springframework.boot
    spring-boot-starter-actuator

Обратите внимание, что это остается в силе независимо от версии загрузки, так как версии указаны в спецификации материалов Boot Spring.

3. Привод Spring Boot 1.x

В 1.x Actuator следует модели R / W, это означает, что мы можем либо читать из нее, либо писать в нее. E.g. мы можем получить показатели или состояние нашего приложения. В качестве альтернативы, мы можем корректно завершить работу нашего приложения или изменить конфигурацию ведения журнала.

Чтобы заставить его работать, Actuator требует, чтобы Spring MVC выставлял свои конечные точки через HTTP. Никакая другая технология не поддерживается.

3.1. Endpoints

В версии 1.x Actuator предлагает собственную модель безопасности. Он использует преимущества конструкций Spring Security, но его необходимо настраивать независимо от остальной части приложения.

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

Вот некоторые из наиболее распространенных конечных точек, которые Boot предоставляет из коробки:

/health - показывает информацию о состоянии приложения (простой‘status' при доступе через неаутентифицированное соединение или полные данные сообщения при аутентификации); по умолчанию он не чувствителен
/info – Отображает информацию о произвольном приложении; не чувствителен по умолчанию
/metrics – Показывает информацию «метрики» для текущего приложения; он также чувствителен по умолчанию
/trace – Отображает информацию трассировки (по умолчанию последние несколько HTTP-запросов)

Мы можем найти полный список существующих конечных точек вon the official docs.

3.2. Настройка существующих конечных точек

Каждую конечную точку можно настроить с помощью свойств в следующем формате:endpoints.[endpoint name].[property to customize]

Доступны три свойства:

id –, с помощью которого эта конечная точка будет доступна через HTTP
enabled - если true, то к нему можно получить доступ, иначе нет
sensitive - если истина, то требуется авторизация для отображения важной информации по HTTP

Например, добавление следующих свойств будет настраивать конечную точку /beans:

endpoints.beans.id=springbeans
endpoints.beans.sensitive=false
endpoints.beans.enabled=true

**3.3. /health Конечная точка**

The /health endpoint is used to check the health or state of the running application. Обычно это осуществляется мониторингом программного обеспечения, чтобы предупредить нас, если работающий экземпляр выходит из строя или становится неработоспособным по другим причинам. E.g. Проблемы с подключением к нашей БД, нехватка места на диске…

По умолчанию только информация о работоспособности отображается для несанкционированного доступа по HTTP:

{
    "status" : "UP"
}

Эта информация о работоспособности собирается из всех bean-компонентов, реализующих интерфейсHealthIndicator, настроенный в контексте нашего приложения.

Некоторая информация, возвращаемаяHealthIndicator, является конфиденциальной по своей природе, но мы можем настроитьendpoints.health.sensitive=false для предоставления более подробной информации, такой как дисковое пространство, подключение брокера обмена сообщениями, пользовательские проверки и т. Д.

Мы также могли быimplement our own custom health indicator - который может собирать любые типы пользовательских данных о работоспособности, специфичных для приложения, и автоматически предоставлять их через конечную точку/health:

@Component
public class HealthCheck implements HealthIndicator {

    @Override
    public Health health() {
        int errorCode = check(); // perform some specific health check
        if (errorCode != 0) {
            return Health.down()
              .withDetail("Error Code", errorCode).build();
        }
        return Health.up().build();
    }

    public int check() {
        // Our logic to check health
        return 0;
    }
}

Вот как будет выглядеть результат:

{
    "status" : "DOWN",
    "myHealthCheck" : {
        "status" : "DOWN",
        "Error Code" : 1
     },
     "diskSpace" : {
         "status" : "UP",
         "free" : 209047318528,
         "threshold" : 10485760
     }
}

**3.4. /info Конечная точка**

Мы также можем настроить данные, отображаемые конечной точкой/info, например:

info.app.name=Spring Sample Application
info.app.description=This is my first spring boot application
info.app.version=1.0.0

И пример вывода:

{
    "app" : {
        "version" : "1.0.0",
        "description" : "This is my first spring boot application",
        "name" : "Spring Sample Application"
    }
}

**3.5. /metrics Конечная точка**

The metrics endpoint publishes information about OS, JVM as well as application level metrics. После включения мы получаем такую информацию, как память, куча, процессоры, потоки, загруженные классы, выгруженные классы, пулы потоков, а также некоторые HTTP-метрики.

Вот как выглядят выходные данные этой конечной точки из коробки:

{
    "mem" : 193024,
    "mem.free" : 87693,
    "processors" : 4,
    "instance.uptime" : 305027,
    "uptime" : 307077,
    "systemload.average" : 0.11,
    "heap.committed" : 193024,
    "heap.init" : 124928,
    "heap.used" : 105330,
    "heap" : 1764352,
    "threads.peak" : 22,
    "threads.daemon" : 19,
    "threads" : 22,
    "classes" : 5819,
    "classes.loaded" : 5819,
    "classes.unloaded" : 0,
    "gc.ps_scavenge.count" : 7,
    "gc.ps_scavenge.time" : 54,
    "gc.ps_marksweep.count" : 1,
    "gc.ps_marksweep.time" : 44,
    "httpsessions.max" : -1,
    "httpsessions.active" : 0,
    "counter.status.200.root" : 1,
    "gauge.response.root" : 37.0
}

Для сбора специальных показателей у нас есть поддержка «датчиков», то есть снимков данных с одним значением, и «счетчиков», т. Е. incrementing/decrementing metrics.

Давайте внедрим наши собственные метрики в конечную точку/metrics. Например, мы настроим процесс входа в систему для записи успешной и неудачной попытки входа:

@Service
public class LoginServiceImpl {

    private final CounterService counterService;

    public LoginServiceImpl(CounterService counterService) {
        this.counterService = counterService;
    }

    public boolean login(String userName, char[] password) {
        boolean success;
        if (userName.equals("admin") && "secret".toCharArray().equals(password)) {
            counterService.increment("counter.login.success");
            success = true;
        }
        else {
            counterService.increment("counter.login.failure");
            success = false;
        }
        return success;
    }
}

Вот как может выглядеть результат:

{
    ...
    "counter.login.success" : 105,
    "counter.login.failure" : 12,
    ...
}

Обратите внимание, что попытки входа в систему и другие связанные с безопасностью события доступны в Actuator как события аудита.

3.6. Создание новой конечной точки

Помимо использования существующих конечных точек, предоставляемых Spring Boot, мы также можем создать совершенно новую.

Во-первых, нам нужно, чтобы новая конечная точка реализовывала интерфейсEndpoint<T>:

@Component
public class CustomEndpoint implements Endpoint> {

    @Override
    public String getId() {
        return "customEndpoint";
    }

    @Override
    public boolean isEnabled() {
        return true;
    }

    @Override
    public boolean isSensitive() {
        return true;
    }

    @Override
    public List invoke() {
        // Custom logic to build the output
        List messages = new ArrayList();
        messages.add("This is message 1");
        messages.add("This is message 2");
        return messages;
    }
}

Чтобы получить доступ к этой новой конечной точке, ееid используется для ее отображения, т.е. мы могли бы использовать его, ударив/customEndpoint.

Выход:

[ "This is message 1", "This is message 2" ]

3.7. Дальнейшая настройка

В целях безопасности мы можем выбрать доступ к конечным точкам исполнительного механизма через нестандартный порт - свойствоmanagement.port можно легко использовать для настройки этого.

Также, как мы уже упоминали, в 1.x. Actuator настраивает свою собственную модель безопасности, основанную на Spring Security, но независимую от остальной части приложения. Следовательно, мы можем изменить свойствоmanagement.address, чтобы ограничить доступ к конечным точкам из сети:

#port used to expose actuator
management.port=8081

#CIDR allowed to hit actuator
management.address=127.0.0.1

#Whether security should be enabled or disabled altogether
management.security.enabled=false

Кроме того, все встроенные конечные точки, кроме/info, по умолчанию чувствительны. Если приложение использует Spring Security - мы можем защитить эти конечные точки, определив свойства безопасности по умолчанию - имя пользователя, пароль и роль - в файле application.properties:

security.user.name=admin
security.user.password=secret
management.security.role=SUPERUSER

4. Привод Spring Boot 2.x

В 2.x Actuator сохраняет свои основные намерения, но упрощает свою модель, расширяет свои возможности и использует лучшие значения по умолчанию.

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

Наконец, среди различных изменений важно помнить, что некоторые из них ломаются. Это включает в себя HTTP-запросы / ответы, а также API-интерфейсы Java.

Кроме того, последняя версия теперь поддерживает модель CRUD, в отличие от старой модели RW (чтение / запись).

4.1. Технологическая поддержка

С его второй основной версией, Actuator теперь не зависит от технологий, тогда как в 1.x он был привязан к MVC, следовательно, к Servlet API.

В 2.x Actuator определяет свою модель, подключаемую и расширяемую, не полагаясь на MVC для этого.

Следовательно, с этой новой моделью мы можем использовать преимущества MVC, а также WebFlux в качестве базовой веб-технологии.

Более того, будущие технологии могут быть добавлены путем внедрения правильных адаптеров.

Наконец, JMX по-прежнему поддерживается для предоставления конечных точек без какого-либо дополнительного кода.

4.2. Важные изменения

В отличие от предыдущих версий,Actuator comes with most endpoints disabled.

Таким образом, по умолчанию доступны только два варианта:/health и/info.

Если бы мы хотели включить их все, мы могли бы установитьmanagement.endpoints.web.exposure.include=*.. В качестве альтернативы мы могли бы указать конечные точки, которые должны быть включены.

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

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

@Bean
public SecurityWebFilterChain securityWebFilterChain(
  ServerHttpSecurity http) {
    return http.authorizeExchange()
      .pathMatchers("/actuator/**").permitAll()
      .anyExchange().authenticated()
      .and().build();
}

Мы можем найти более подробную информацию оbrand new Actuator official docs.

Такжеby default, all Actuator endpoints are now placed under the /actuator path.

Как и в предыдущей версии, мы можем настроить этот путь, используя новое свойствоmanagement.endpoints.web.base-path.

4.3. Предопределенные конечные точки

Давайте посмотрим на некоторые доступные конечные точки, большинство из них были доступны уже в 1.x.

Тем не менееsome endpoints have been added, some removed and some have been restructured:

/auditevents – перечисляет события, связанные с аудитом безопасности, такие как вход / выход пользователя. Кроме того, мы можем фильтровать по принципу или типу среди других полей
/beans – rустанавливает все доступные bean-компоненты в нашемBeanFactory. В отличие от/auditevents, он не поддерживает фильтрацию.
/conditions –, ранее известный как /autoconfig, создает отчет об условиях автоматической настройки
/configprops – позволяет нам получать все bean-компоненты@ConfigurationProperties
/env – возвращает текущие свойства среды. Кроме того, мы можем получить отдельные свойства
/flyway – предоставляет подробную информацию о миграции нашей базы данных Flyway.
/health – показывает состояние работоспособности нашего приложения.
/heapdump – создает и возвращает дамп кучи из JVM, используемой нашим приложением
/info – возвращает общую информацию. Это могут быть пользовательские данные, информация о сборке или сведения о последнем коммите.
/liquibase – bаналогичен/flyway, но для Liquibase
/logfile – возвращает обычные журналы приложений
/loggers – позволяет нам запрашивать и изменять уровень ведения журнала нашего приложения.
/metrics – подробно описывает показатели нашего приложения. Это может включать в себя общие метрики, а также пользовательские
/prometheus – возвращает метрики, подобные предыдущему, но отформатированные для работы с сервером Prometheus
/scheduledtasks – предоставляет подробную информацию о каждой запланированной задаче в нашем приложении.
/sessions – перечисляет HTTP-сеансы, если мы используем Spring Session
/shutdown – выполняет плавное завершение работы приложения
/threaddump – выгружает информацию о потоках базовой JVM

4.4. Индикаторы здоровья

Как и в предыдущей версии, мы можем легко добавлять пользовательские индикаторы. В отличие от других API, абстракции для создания пользовательских конечных точек работоспособности остаются неизменными. Однакоa new interface ReactiveHealthIndicator has been added to implement reactive health checks.

Давайте посмотрим на простую настраиваемую реактивную проверку работоспособности:

@Component
public class DownstreamServiceHealthIndicator implements ReactiveHealthIndicator {

    @Override
    public Mono health() {
        return checkDownstreamServiceHealth().onErrorResume(
          ex -> Mono.just(new Health.Builder().down(ex).build())
        );
    }

    private Mono checkDownstreamServiceHealth() {
        // we could use WebClient to check health reactively
        return Mono.just(new Health.Builder().up().build());
    }
}

A handy feature of health indicators is that we can aggregate them as part of a hierarchy. Следовательно, следуя предыдущему примеру, мы могли бы сгруппировать все последующие сервисы в категориюdownstream-services. Эта категория будет здоровой, пока все вложенныеservice доступны.

Составные проверки работоспособности присутствуют в версиях от 1.x доCompositeHealthIndicator.. Кроме того, в 2.x мы могли бы использоватьCompositeReactiveHealthIndicator для его реактивного аналога.

В отличие от Spring Boot 1.x, флагendpoints. .sensitive был удален. Чтобы скрыть полный отчет о работоспособности, мы можем воспользоваться новым параметромmanagement.endpoint.health.show-details.. Этот флаг по умолчанию ложен.

4.5. Метрики в Spring Boot 2

In Spring Boot 2.0, the in-house metrics were replaced with Micrometer support. Таким образом, можно ожидать критических изменений. Если в нашем приложении использовались метрические службы, такие какGaugeService or CounterService, они больше не будут доступны.

Вместо этого ожидается, что мы будем напрямую взаимодействовать сMicrometer. В Spring Boot 2.0 мы получим компонент типаMeterRegistry, автоматически настроенный для нас.

Кроме того, Micrometer теперь является частью зависимостей Actuator. Следовательно, мы должны хорошо идти, пока зависимость Actuator находится в пути к классам.

Более того, мы получим совершенно новый ответ от конечной точки/metrics:

{
  "names": [
    "jvm.gc.pause",
    "jvm.buffer.memory.used",
    "jvm.memory.used",
    "jvm.buffer.count",
    // ...
  ]
}

Как мы можем наблюдать в предыдущем примере, реальных метрик нет, как мы получили в 1.x.

Чтобы получить фактическое значение конкретной метрики, теперь мы можем перейти к нужной метрике, то есть/actuator/metrics/jvm.gc.pause, и получить подробный ответ:

{
  "name": "jvm.gc.pause",
  "measurements": [
    {
      "statistic": "Count",
      "value": 3.0
    },
    {
      "statistic": "TotalTime",
      "value": 7.9E7
    },
    {
      "statistic": "Max",
      "value": 7.9E7
    }
  ],
  "availableTags": [
    {
      "tag": "cause",
      "values": [
        "Metadata GC Threshold",
        "Allocation Failure"
      ]
    },
    {
      "tag": "action",
      "values": [
        "end of minor GC",
        "end of major GC"
      ]
    }
  ]
}

Как мы видим, метрики сейчас намного тщательнее. Включая не только разные значения, но и некоторые связанные метаданные.

4.6. Настройка конечной точки/info

Конечная точка/info остается неизменной. As before, we can add git details using the Maven or Gradle respective dependency:


    pl.project13.maven
    git-commit-id-plugin

Аналогичноwe could also include build information including name, group, and version using the Maven or Gradle plugin:


    org.springframework.boot
    spring-boot-maven-plugin
    
        
            
                build-info

4.7. Создание настраиваемой конечной точки

Как мы указывали ранее, мы можем создавать собственные конечные точки. Однако Spring Boot 2 изменил способ достижения этой цели, чтобы поддержать новую технологически независимую парадигму.

Let’s create an Actuator endpoint to query, enable and disable feature flags in our application:

@Component
@Endpoint(id = "features")
public class FeaturesEndpoint {

    private Map features = new ConcurrentHashMap<>();

    @ReadOperation
    public Map features() {
        return features;
    }

    @ReadOperation
    public Feature feature(@Selector String name) {
        return features.get(name);
    }

    @WriteOperation
    public void configureFeature(@Selector String name, Feature feature) {
        features.put(name, feature);
    }

    @DeleteOperation
    public void deleteFeature(@Selector String name) {
        features.remove(name);
    }

    public static class Feature {
        private Boolean enabled;

        // [...] getters and setters
    }

}

Чтобы получить конечную точку, нам нужен бин. В нашем примере для этого используется@Component. Также нам нужно украсить этот bean-компонент@Endpoint.

Путь к нашей конечной точке определяется параметромid для@Endpoint, в нашем случае он направляет запросы на/actuator/features.

Когда все будет готово, мы можем начать определять операции, используя:

@ReadOperation – будет отображаться в HTTPGET
@WriteOperation - будет отображаться в HTTPPOST
@DeleteOperation - будет отображаться в HTTPDELETE

Когда мы запускаем приложение с предыдущей конечной точкой в нашем приложении, Spring Boot зарегистрирует его.

Быстрый способ убедиться в этом - проверить журналы:

[...].WebFluxEndpointHandlerMapping: Mapped "{[/actuator/features/{name}],
  methods=[GET],
  produces=[application/vnd.spring-boot.actuator.v2+json || application/json]}"
[...].WebFluxEndpointHandlerMapping : Mapped "{[/actuator/features],
  methods=[GET],
  produces=[application/vnd.spring-boot.actuator.v2+json || application/json]}"
[...].WebFluxEndpointHandlerMapping : Mapped "{[/actuator/features/{name}],
  methods=[POST],
  consumes=[application/vnd.spring-boot.actuator.v2+json || application/json]}"
[...].WebFluxEndpointHandlerMapping : Mapped "{[/actuator/features/{name}],
  methods=[DELETE]}"[...]

В предыдущих журналах мы видели, как WebFlux представляет нашу новую конечную точку. Перейдем ли мы на MVC, он просто делегирует эту технологию без необходимости изменять какой-либо код.

Кроме того, у нас есть несколько важных соображений, которые следует учитывать при использовании этого нового подхода:

Нет никаких зависимостей с MVC
Все метаданные, представленные как методы до (sensitive, enabled…), больше не существуют. Однако мы можем включить или отключить конечную точку с помощью@Endpoint(id = “features”, enableByDefault = false)
В отличие от 1.x, больше нет необходимости расширять данный интерфейс.
В отличие от старой модели чтения / записи, теперь мы можем определять операцииDELETE, используя@DeleteOperation

4.8. Расширение существующих конечных точек

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

We can easily extend the behavior of a predefined endpoint using the @EndpointExtension annotations или его более конкретные специализации@EndpointWebExtension или@EndpointJmxExtension:

@Component
@EndpointWebExtension(endpoint = InfoEndpoint.class)
public class InfoWebEndpointExtension {

    private InfoEndpoint delegate;

    // standard constructor

    @ReadOperation
    public WebEndpointResponse info() {
        Map info = this.delegate.info();
        Integer status = getStatus(info);
        return new WebEndpointResponse<>(info, status);
    }

    private Integer getStatus(Map info) {
        // return 5xx if this is a snapshot
        return 200;
    }
}

4.9. Включить все конечные точки

In order to access the actuator endpoints using HTTP, we need to both enable and expose them. По умолчанию все конечные точки, кроме/shutdown, включены. По умолчанию доступны только конечные точки/health и/info.

Нам нужно добавить следующую конфигурацию, чтобы выставить все конечные точки:

management.endpoints.web.exposure.include=*

Чтобы явно включить конкретную конечную точку (например,/shutdown), we, используйте:

management.endpoint.shutdown.enabled=true

Чтобы открыть все включенные конечные точки, кроме одной (например,/loggers), мы используем:

management.endpoints.web.exposure.include=*
management.endpoints.web.exposure.exclude=loggers

5. Резюме

В этой статье мы говорили о Spring Boot Actuator. Мы начали определять, что означает Actuator и что он делает для нас.

Далее мы сосредоточились на Actuator для текущей версии Spring Boot, 1.x. обсуждая, как его использовать, настройте его и расширьте.

Затем мы обсудили Actuator в Spring Boot 2. Мы сосредоточились на том, что нового, и воспользовались WebFlux, чтобы раскрыть нашу конечную точку.

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

Наконец, мы продемонстрировали, как настроить и расширить Actuator.

Как всегда, мы можем найти код, использованный в этой статье, на GitHub как дляSpring Boot 1.x, так и дляSpring Boot 2.x.

TOC

Привод пружинной загрузки