Spring Boot Actuator su uso y configuración

En este artículo vamos a hablar sobre Spring Boot actuator, su uso y configuración. Vamos a ver como podemos crear un endpoint de actuator propio, o como implementar el endpoint de health modificando su comportamiento por defecto.

¿Por qué usar Spring Boot Actuator?

Spring Boot Actuator es un proyecto que pertenece a Spring Boot Framework. Incluyendo una serie de características que nos ayudaran a monitorizar y gestionar nuestra aplicación. Podemos usar tanto HTTP como JMX para gestionar y monitorizar la aplicación.

Simplemente añadiendo el starter que nos ofrece Spring Boot tendremos una serie de características en nuestra aplicación sobre su ejecución.

Añadir Spring Boot Actuator en la Aplicación

Para poder hacer uso de las funcionalidades que nos puede aportar Spring Boot Actuator será necesario, añadir su dependencia Maven en nuestra aplicación:

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

Principales Características

Actuator viene con la mayoría de los endpoints desactivados, lo únicos que por defecto vienen activados son /health e /info.

Una de las características más notables del Actuator de Spring es que es agnostico a la tecnología, con lo que se puede aprovechar tanto MVC como WebFlux como tecnologías subyacentes.

• Agnóstico a la tecnología
• Endpoints
• Métricas
• Auditoría

Agnóstico a la tecnología

Una de las características más notables del Actuator de Spring es que es agnostico a la tecnología, con lo que se puede aprovechar tanto MVC como WebFlux como tecnologías subyacentes.

Endpoints

Los endpoints de actuator nos permite monitorizar e interactuar con la aplicación. Además podemos crear más endpoints para nuestra aplicación según lo necesitemos, cada uno de estos endpoints pueden ser activados o desactivados de manera individual.  

Los endpoints van seguidos de el prefijo /actuator. Un ejemplo de endpoint es /heatlh, el cual nos proporciona información de estado básica de la aplicación.

Métricas

Spring Boot Actuator proporciona métricas al integrarse con micrometer. Es una biblioteca de instrumentación que impulsa la entrega de métricas de aplicaciones de Spring. Proporciona interfaces independientes del proveedor para temporizadores, medidores, contadores, resúmenes de distribución y temporizadores de tareas largas con un modelo de datos dimensionales.

Auditoría

Spring Boot nos proporciona un framework de auditoría que publica eventos a un AuditEventRepository. Si tenemos Spring Security publicará de manera automática todos los eventos de autenticación. 

Endpoints predefinidos de Spring Boot Actuator

A continuación se ofrece el listado de los endpoints que vienen ya predefinidos y nos muestran información sobre nuestra aplicación. Hay que tener en cuenta que lo primero es activar actuator.

• /auditevents: muestra un listado de los eventos relacionados con la auditoría de seguridad, como como el login.
• /beans: devuelve todos los beans que se encuentran en BeanFactory.
• /conditions: crea un informe de la condiciones.
• /configprops: nos permite obtener todos los beans de @ConfigurationProperties.
• /env:  devuelve el actual entorno de properties.
• /flyway: proporciona información sobre Flyway.
• /health: el estado de salud de nuestra aplicción.
• /heapdump: devuelve el head dump de nuestra JVM que es usada por la aplicación.
• /info: devuelve información general.
• /liquibase: se comporta como el endpoint de flyway pero para Liquibase
• /logfile: logs de aplicación.
• /loggers: nos permite consultar y modificar el nivel de logs.
• /metrics:  devuelve las métricas de nuestra aplicación.
• /prometheus: devuelve las métricas formateadas para prometheus.
• /scheduledtasks: proporciona información sobre las tasks de la aplicación.
• /sessions: devuelve las HTTP Session que estamos usando en Spring Session.
• /shutdown: apagado de la aplicación
• /threaddump: vuelva la información del hilo de JVM

Customizar endpoints

Customizar Endpoint Health

Desde la versión 1 de Spring Boot se puede customizar en endpoint de /health implementando la clase HealthIndicator. Sin embargo con la Versión 2, podemos también implementar con la clase ReactiveHealthIndicator, y aportar a nuestro /health características reactivas.

@Component
public class ServiceHealthIndicator implements ReactiveHealthIndicator {

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

  private Mono<Health> webFluxServiceHealth() {
    return Mono.just(new Health.Builder().up().build());
  }
}

Como podemos ver en el fragmento de código anterior hemos implementado un nuevo Health indicator sobre escribiendo los métodos de ReactiveHealthIndicator, de esta forma ahora nuestro /heatlh endpoint será reactivo.

Customizar Endpoint info

En el endpoint /info podemos añadir detalles de git mediante la siguiente dependencia:

<dependency>
  <groupId>pl.project13.maven</groupId>
  <artifactId>git-commit-id-plugin</artifactId>
</dependency>

También podríamos incluir información de compilación que incluya nombre, grupo y versión utilizando el complemento Maven

<plugin>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-maven-plugin</artifactId>
    <executions>
        <execution>
            <goals>
                <goal>build-info</goal>
            </goals>
        </execution>
    </executions>
</plugin>

Crear endpoint customizado

Como hemos comentado anteriormente, Spring Boot Actuator nos da la posibilidad de crear nuevos endpoints.

Para poder generar un nuevo endpoint, vamos a crear una nueva clase que cree un bean y además informaremos que es una clase que creará un nuevo endpoint mediante la anotación @Endpoint.

La ruta del endpoint vendrá definido por el parámetro id de la anotación @Endpoint.

Dentro de nuestro endpoint, como en cualquier API, podremos definir diferentes verbos, a través de @ReadOperation (HTTP GET), @WriteOperation (HTTP POST) y @DeleteOperation (HTTP DELETE).

Vamos a verlo mejor con un ejemplo:

@Component
@Endpoint(id = "my-health")
public class MyHealthEndpoint {
 
      Map<String, Object> healthMap = new LinkedHashMap<>();

    @ReadOperation
    public Map<String, Object> health() {
        healthMap.put("MyHealth", "Working");
        return healthMap;
    }

    @ReadOperation
    public String getHealth(@Selector String name) {
        return healthMap.get(name);
    }

    @WriteOperation
    public void writeOperation(@Selector String name) {
        //TODO this write operation
    }
    @DeleteOperation
    public void deleteOperation(@Selector String name){
        //TODO delete operation
    }
}

Vamos a acceder a nuestro endpoint:  http://host:port/actuator/my-health y la salida será:

{ "MyHealth":"Working" }

Crear endpoint customizado en controladores

Aparte de la manera anterior de crear endpoints, tenemos una manera alternativa de crear endpoints propios. Para ellos vamos a usar la anotación @ControllerEndpoint o @RestControllerEndpoint. Con esta aproximación usaremos las anotaciones normales que usamos en los controladores como @RequestMapping o @GetMapping.

@Component
@RestControllerEndpoint(id = "controller-end-point")
public class CustomEndPoint {

    @GetMapping("/my-endpoint")
    public @ResponseBody ResponseEntity customEndPoint(){
        return  new ResponseEntity<>("Something from my controller", HttpStatus.OK);
    }
}

Para llamar al nuevo endpoint lo podemos hacer así: http://host:port/actuator/controller-end-point/my-endpoint

Extender endpoints existentes

Podemos extender el comportamiento de un endpoint predefinidio usando la anotación @EndpointExtension.

@Component
@EndpointWebExtension(endpoint = InfoEndpoint.class)
public class InfoWebExtension {
//TODO do something
}

Activar todos los endpoints

Como ya hemos comentado anteriormente no todos los endpoints de Spring Boot Actuator para su uso y configuración se encuentran definidos, únicamente /health e /info están activados. Por lo que para activarlos haremos lo siguiente:

Si queremos activar todos añadiremos:

management.endpoints.web.exposure.include=*

Si queremos un endpoint específico:

management.endpoint.flyway.enabled=true

Por otro lado, también podemos activar todos los endpoints menos uno, por ejemplo flyway.

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

Conclusión

En esta entrada hemos visto un poco del funcionamiento de Spring Boot Actuator, su uso y configuración, viendo como podemos extender algunos endpoints para añadir más información o como podemos crear nuestro endpoint propio de dos maneras diferentes.