📈 Spring Boot Actuator Cheatsheet Completo 📈

Spring Boot Actuator es una característica de Spring Boot que proporciona puntos finales (“endpoints”) listos para la producción. Estos endpoints te permiten monitorear y gestionar tu aplicación, obteniendo información sobre el estado de salud, métricas, configuración, logs y mucho más, sin necesidad de escribir código adicional.

1. 🌟 Conceptos Clave

Endpoints: URLs o puntos de acceso JMX que exponen información operativa sobre la aplicación.
Monitoreo y Gestión: Permite observar el comportamiento y la salud de la aplicación en tiempo real.
Auditoría: Proporciona información sobre el estado interno de la aplicación.
Integración: Fácilmente integrable con herramientas de monitoreo externas.
Producción-Ready: Diseñado para ser seguro y útil en entornos de producción.

2. 🛠️ Configuración Inicial (Spring Boot)

Añadir dependencia en pom.xml (Maven):

<dependencies>
    &lt;!-- Incluye todas las funcionalidades de Actuator -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-actuator</artifactId>
    </dependency>
    &lt;!-- Opcional: Para métricas con Prometheus -->
    <dependency>
        <groupId>io.micrometer</groupId>
        <artifactId>micrometer-registry-prometheus</artifactId>
        <scope>runtime</scope>
    </dependency>
</dependencies>

Acceso por Defecto:
- Una vez que se añade la dependencia, Actuator se habilita automáticamente.
- Por defecto, solo los endpoints /health y /info son expuestos a través de HTTP.
- La base URL para los endpoints es /actuator/.
- Ej: http://localhost:8080/actuator/health, http://localhost:8080/actuator/info.

3. 📊 Endpoints Más Comunes

Accesibles por defecto vía HTTP en http://<host>:<port>/actuator/<endpoint-id>.

/health: Muestra el estado de salud de la aplicación (UP/DOWN).
- Muestra el estado de componentes clave como base de datos, disco, colas de mensajes, etc.
- show-details: Configurable para mostrar más o menos detalles.
  - management.endpoint.health.show-details=always (siempre muestra detalles)
  - management.endpoint.health.show-details=when_authorized (solo si está autenticado)
  - management.endpoint.health.show-details=never (nunca muestra detalles)
/info: Muestra información arbitraria de la aplicación.
- Puedes añadir información en application.properties (ej. info.app.name=MyApp, info.app.version=1.0.0).
- También puedes inyectar beans InfoContributor para proporcionar información dinámica.
/metrics: Muestra métricas detalladas del sistema y la aplicación.
- http://localhost:8080/actuator/metrics (lista todas las métricas disponibles).
- http://localhost:8080/actuator/metrics/jvm.memory.used (muestra una métrica específica).
- Integrado con Micrometer para métricas personalizadas.
/loggers: Permite ver y cambiar los niveles de logging en tiempo de ejecución.
- GET /actuator/loggers: Lista todos los loggers y sus niveles.
- POST /actuator/loggers/{name} con { "configuredLevel": "DEBUG" }: Cambia el nivel de un logger.
/env: Muestra las propiedades del entorno (variables de entorno, propiedades del sistema, etc.).
/beans: Muestra una lista de todos los beans configurados en tu ApplicationContext.
/mappings: Muestra un mapeo de todas las rutas HTTP de la aplicación.
/threaddump: Realiza un volcado de hilos (thread dump) de la JVM. Útil para depurar problemas de concurrencia.
/heapdump: Realiza un volcado del heap de la JVM. Se descarga como un archivo .hprof para análisis de memoria. (Por defecto, solo en JMX).

4. ⚙️ Configuración de Endpoints

Todas las configuraciones se realizan en application.properties o application.yml.

4.1. Exposición de Endpoints

Por defecto, solo health y info están expuestos por HTTP.
management.endpoints.web.exposure.include: Expone endpoints específicos.
- management.endpoints.web.exposure.include=*: Expone TODOS los endpoints (¡CUIDADO! No recomendado en producción sin seguridad).
- management.endpoints.web.exposure.include=health,info,metrics: Expone solo estos.
management.endpoints.web.exposure.exclude: Oculta endpoints específicos.
- management.endpoints.web.exposure.exclude=threaddump: Oculta threaddump.

4.2. Cambiar la Base URL

management.endpoints.web.base-path=/monitor: Cambia la base URL de /actuator a /monitor.
- Ej: http://localhost:8080/monitor/health

4.3. Cambiar el Puerto de Actuator (Separado)

management.server.port=8081: Ejecuta los endpoints de Actuator en un puerto diferente al de la aplicación.
- Ej: http://localhost:8081/actuator/health

4.4. Habilitar/Deshabilitar Endpoints Individualmente

management.endpoint.<id>.enabled=false: Deshabilita un endpoint específico.
- management.endpoint.shutdown.enabled=true: Habilita el endpoint /shutdown (deshabilitado por defecto por seguridad).

5. 🧑‍💻 Personalización

5.1. Información Personalizada (`/info`)

Desde application.properties:

info.app.name=MiAppGestion
info.app.description=Sistema de gestión de inventario
info.app.version=1.0.0-SNAPSHOT

Desde git.properties / build-info.properties: Spring Boot puede generar estos archivos con información del build y de Git.

Con InfoContributor:

import org.springframework.boot.actuate.info.Info;
import org.springframework.boot.actuate.info.InfoContributor;
import org.springframework.stereotype.Component;

import java.util.Collections;

@Component
public class CustomInfoContributor implements InfoContributor {
    @Override
    public void contribute(Info.Builder builder) {
        builder.withDetail("buildTime", System.currentTimeMillis())
               .withDetail("features", Collections.singletonMap("payments", true));
    }
}

5.2. Chequeos de Salud Personalizados (`/health`)

Implementa la interfaz HealthIndicator.

import org.springframework.boot.actuate.health.Health;
import org.springframework.boot.actuate.health.HealthIndicator;
import org.springframework.stereotype.Component;

@Component("myCustomService") // ID del componente de salud
public class MyCustomHealthIndicator implements HealthIndicator {
    @Override
    public Health health() {
        // Lógica para comprobar la salud de tu servicio/componente
        if (isMyServiceHealthy()) {
            return Health.up().withDetail("reason", "Todo ok con el servicio personalizado").build();
        } else {
            return Health.down().withDetail("error", "Servicio personalizado no disponible").build();
        }
    }

    private boolean isMyServiceHealthy() {
        // Simula una comprobación compleja
        return Math.random() > 0.1; // 90% de probabilidad de estar UP
    }
}

5.3. Métricas Personalizadas (`/metrics`)

Utiliza Micrometer (parte del ecosistema de Spring Boot).

import io.micrometer.core.instrument.Counter;
import io.micrometer.core.instrument.Gauge;
import io.micrometer.core.instrument.MeterRegistry;
import org.springframework.stereotype.Component;

import java.util.concurrent.atomic.AtomicInteger;

@Component
public class CustomMetrics {
    private final Counter processCounter;
    private final AtomicInteger activeUsers = new AtomicInteger(0);

    public CustomMetrics(MeterRegistry meterRegistry) {
        // Contador (Counter): solo incrementa
        this.processCounter = meterRegistry.counter("my_app_process_total", "type", "business_logic");

        // Gauge: mide un valor actual
        meterRegistry.gauge("my_app_active_users", activeUsers);
    }

    public void incrementProcessCount() {
        processCounter.increment();
    }

    public void setActiveUsers(int count) {
        activeUsers.set(count);
    }
}
// Puedes acceder a estas métricas en /actuator/metrics/my_app_process_total, etc.

7. 🔒 Seguridad

¡CRÍTICO en Producción!
Por defecto, Spring Security (si está en el classpath) asegurará automáticamente todos los endpoints de Actuator.
Necesitarás un usuario/contraseña para acceder a la mayoría de los endpoints.

Puedes configurar reglas de autorización en tu SecurityConfig de Spring Security.

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.web.SecurityFilterChain;
import org.springframework.boot.actuate.autoconfigure.security.servlet.EndpointRequest;
import org.springframework.security.config.Customizer;

@Configuration
public class ActuatorSecurityConfig {
    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            .authorizeHttpRequests(authorize -&gt; authorize
                .requestMatchers(EndpointRequest.to("health", "info")).permitAll() // Health/Info públicos
                .requestMatchers(EndpointRequest.toAnyEndpoint()).hasRole("ADMIN") // Otros Actuator requieren ADMIN
                .anyRequest().authenticated() // El resto de la app requiere autenticación
            )
            .httpBasic(Customizer.withDefaults()); // O .formLogin()
        return http.build();
    }
}

8. 📊 Integración con Herramientas de Monitoreo

Prometheus: Expone métricas en un formato que Prometheus puede rastrear (/actuator/prometheus).
Grafana: Utiliza Grafana para visualizar las métricas recolectadas por Prometheus.
Spring Boot Admin: Proporciona una interfaz de usuario centralizada para monitorear múltiples aplicaciones Spring Boot con Actuator.
JMX: También puedes acceder a los endpoints a través de JMX (Java Management Extensions) usando herramientas como JConsole o VisualVM.

9. 💡 Buenas Prácticas y Consejos

Prioriza la Seguridad: Nunca expongas todos los endpoints de Actuator (exposure.include=*) públicamente en producción sin una seguridad robusta. Controla estrictamente qué endpoints son accesibles y por quién.
Entiende cada Endpoint: Familiarízate con la información que cada endpoint proporciona para depurar y monitorear eficazmente.
Personaliza health e info: Añade chequeos de salud e información de la aplicación específicos para tu negocio.
Métricas Personalizadas: Instrumenta tu código con métricas personalizadas (Contadores, Gauges, Timers) usando Micrometer para obtener visibilidad sobre la lógica de negocio clave.
Despliegue Separado: Para entornos críticos, considera ejecutar Actuator en un puerto diferente al de la aplicación (management.server.port) y restringir el acceso a ese puerto solo desde redes de monitoreo.
Logging: Combina los datos de Actuator con un sistema de logging centralizado para una visión completa del estado de la aplicación.
Ambientes (Profiles): Usa perfiles de Spring para configurar la exposición de Actuator de forma diferente para desarrollo, staging y producción.
No para Todo: Actuator es excelente para monitoreo y gestión básicos. Para monitoreo a gran escala, combínalo con herramientas dedicadas de la industria (Prometheus, Grafana, ELK Stack, etc.).

Este cheatsheet te proporciona una referencia completa de Spring Boot Actuator, cubriendo sus conceptos esenciales, cómo configurarlo, los endpoints clave, la personalización, la seguridad y las mejores prácticas para monitorear y gestionar tus aplicaciones Spring Boot de manera efectiva.