Saltar al contenido principal

Capítulo 1: Introducción a Spring Boot Actuator

Introducción​

Spring Boot Actuator añade funcionalidades de monitoreo y gestión a su aplicación. Expone endpoints HTTP que permiten supervisar el estado de salud, las métricas y diagnosticar problemas.

🎯 Objetivos del Capítulo​

Al final de este capítulo, usted sabrá:

  1. ✅ Qué es Actuator y por qué usarlo
  2. ✅ Añadir Actuator a su proyecto
  3. ✅ Configurar los endpoints
  4. ✅ Proteger el acceso a los endpoints

1. ¿Qué es Actuator?​

Funcionalidades Principales​

Spring Boot Actuator proporciona:
├── Health Checks: ¿La aplicación está funcionando?
├── Métricas: Rendimiento, uso de memoria, solicitudes/segundo
├── Info: Información sobre la aplicación (versión, build)
├── Environment: Configuración y variables de entorno
├── Loggers: Modificar los niveles de log en caliente
├── Thread Dump: Analizar los threads
├── Heap Dump: Analizar la memoria
└── HTTP Trace: Historial de solicitudes

Casos de Uso​

1. Kubernetes: Probes de liveness/readiness
2. Load Balancer: Verificar si la instancia está sana
3. Prometheus: Recopilar métricas
4. Debugging: Diagnosticar en producción
5. DevOps: Automatizar los despliegues

2. Instalación​

Dependencia Maven​

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

Gradle​

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

3. Configuración Básica​

Activar los Endpoints​

Por defecto, solo /actuator/health está expuesto vía HTTP.

# application.properties

# Exponer todos los endpoints vía HTTP
management.endpoints.web.exposure.include=*

# O exponer solo ciertos endpoints
management.endpoints.web.exposure.include=health,info,metrics,prometheus

# Excluir endpoints sensibles
management.endpoints.web.exposure.exclude=env,beans

Verificar la Instalación​

# Iniciar la aplicación
mvn spring-boot:run

# Listar todos los endpoints disponibles
curl http://localhost:8080/actuator

Respuesta:

{
  "_links": {
    "self": {"href": "http://localhost:8080/actuator"},
    "health": {"href": "http://localhost:8080/actuator/health"},
    "info": {"href": "http://localhost:8080/actuator/info"},
    "metrics": {"href": "http://localhost:8080/actuator/metrics"},
    "loggers": {"href": "http://localhost:8080/actuator/loggers"}
  }
}

4. Puerto y Path Personalizados​

Separar el Puerto de Management​

# Puerto separado para Actuator (recomendado en producción)
management.server.port=8081

# La aplicación permanece en 8080
# Actuator accesible en 8081

Ventajas:

  • Aislar el tráfico de monitoreo
  • Configurar un firewall diferente
  • No exponer en Internet

Personalizar el Path​

# Cambiar el path base
management.endpoints.web.base-path=/admin/monitoring

# Los endpoints estarán bajo:
# /admin/monitoring/health
# /admin/monitoring/info
# etc.

5. Seguridad de los Endpoints​

Con Spring Security​

@Configuration
@EnableWebSecurity
public class SecurityConfig {

    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        http
            .authorizeHttpRequests(auth -> auth
                // Endpoints públicos
                .requestMatchers("/actuator/health").permitAll()
                .requestMatchers("/actuator/info").permitAll()
                
                // Endpoints para Prometheus (solo IP interna)
                .requestMatchers("/actuator/prometheus").permitAll()
                
                // Todos los demás endpoints Actuator: solo ADMIN
                .requestMatchers("/actuator/**").hasRole("ADMIN")
                
                // Resto de la aplicación
                .anyRequest().authenticated()
            )
            .httpBasic(Customizer.withDefaults());
        
        return http.build();
    }
}

Desactivar Endpoints​

# Desactivar completamente un endpoint
management.endpoint.shutdown.enabled=false
management.endpoint.env.enabled=false

# Desactivar todos, luego activar selectivamente
management.endpoints.enabled-by-default=false
management.endpoint.health.enabled=true
management.endpoint.info.enabled=true
management.endpoint.metrics.enabled=true

6. Endpoints Esenciales​

/actuator/health​

curl http://localhost:8080/actuator/health
{
  "status": "UP"
}

Con detalles:

management.endpoint.health.show-details=always
{
  "status": "UP",
  "components": {
    "db": {
      "status": "UP",
      "details": {
        "database": "H2",
        "validationQuery": "isValid()"
      }
    },
    "diskSpace": {
      "status": "UP",
      "details": {
        "total": 499963174912,
        "free": 234567891234,
        "threshold": 10485760
      }
    }
  }
}

/actuator/info​

# Añadir información personalizada
info.app.name=My Application
info.app.version=1.0.0
info.app.description=Aplicación de demo
info.contact.email=support@example.com

# Información Git (si spring-boot-maven-plugin está configurado)
management.info.git.mode=full
curl http://localhost:8080/actuator/info
{
  "app": {
    "name": "My Application",
    "version": "1.0.0",
    "description": "Aplicación de demo"
  },
  "contact": {
    "email": "support@example.com"
  }
}

/actuator/metrics​

# Listar todas las métricas
curl http://localhost:8080/actuator/metrics

# Una métrica específica
curl http://localhost:8080/actuator/metrics/jvm.memory.used
{
  "name": "jvm.memory.used",
  "measurements": [
    {"statistic": "VALUE", "value": 123456789}
  ],
  "availableTags": [
    {"tag": "area", "values": ["heap", "nonheap"]},
    {"tag": "id", "values": ["G1 Eden Space", "G1 Old Gen"]}
  ]
}

7. Configuración Completa Recomendada​

# ===== ACTUATOR =====

# Exponer los endpoints necesarios
management.endpoints.web.exposure.include=health,info,metrics,prometheus,loggers

# Puerto separado (opcional pero recomendado en producción)
# management.server.port=8081

# Health con detalles
management.endpoint.health.show-details=when_authorized
management.endpoint.health.show-components=when_authorized

# Info personalizada
info.app.name=@project.name@
info.app.version=@project.version@
info.app.encoding=@project.build.sourceEncoding@
info.java.version=@java.version@

# Activar la información de build
management.info.build.enabled=true
management.info.git.enabled=true
management.info.env.enabled=true

# Métricas
management.metrics.tags.application=${spring.application.name}

8. Resumen​

Instalación​

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

Configuración Mínima​

management.endpoints.web.exposure.include=health,info,metrics
management.endpoint.health.show-details=always

Endpoints Clave​

EndpointUso
/actuator/healthEstado de salud
/actuator/infoInformación de la aplicación
/actuator/metricsMétricas de rendimiento
/actuator/loggersNiveles de log
/actuator/envVariables de entorno

🎯 Próximo Paso​

Exploremos en detalle todos los endpoints disponibles.

➡️ Capítulo 2: Los Endpoints

⬅️ Volver al Módulo 11