giuseppe-trisciuoglio/spring-boot-actuator

¿Qué hace spring-boot-actuator?

Proporciona patrones para configurar Spring Boot Actuator para monitoreo de nivel de producción, sondas de salud, endpoints de gestión seguros y métricas de Micrometer en servicios JVM. Úselo al configurar monitoreo, comprobaciones de salud o métricas para aplicaciones Spring Boot.

¿Por qué usar este skill?

Configurar Spring Boot Actuator correctamente es clave para operar aplicaciones Spring Boot en producción. Este skill centraliza las mejores prácticas para:

• Sondas de salud: Configurar endpoints /actuator/health/liveness y /actuator/health/readiness para que Kubernetes u otros orquestadores verifiquen la disponibilidad de la aplicación.
• Endpoints seguros: Exponer endpoints de gestión (info, health, metrics, env) solo a través de HTTP y con autenticación básica o de otro tipo.
• Métricas de Micrometer: Exportar métricas a sistemas de monitoreo como Prometheus, Graphite o Datadog mediante el registro adecuado.
• Health Indicators personalizados: Agregar indicadores de salud para dependencias específicas de la aplicación.
• Configuración mínima: Usar anotaciones y propiedades de application.yml para habilitar lo necesario sin sobrescribir la configuración por defecto.

Requisitos

• Aplicación Spring Boot 2.x o 3.x.
• Dependencia spring-boot-starter-actuator en el archivo pom.xml o build.gradle.
• (Opcional) Dependencia micrometer-registry-prometheus si se desea exportar métricas a Prometheus.

Cómo usar

1. Agregue la dependencia de Actuator a su proyecto:

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

2. Configure los endpoints de salud y métricas en application.yml:

   management:
     endpoints:
       web:
         exposure:
           include: health,info,metrics,env
     endpoint:
       health:
         show-details: when-authorized
         probes:
           enabled: true
       metrics:
         enabled: true
     metrics:
       export:
         prometheus:
           enabled: true
   

3. (Opcional) Proteja los endpoints con autenticación básica agregando dependencia de seguridad y configurando usuarios en application.yml:

   spring:
     security:
       user:
         name: admin
         password: secret
   management:
     endpoints:
       web:
         base-path: /actuator
         exposure:
           include: health,info,metrics,env
   

4. Para sondas de liveness/readiness, asegúrese de que management.endpoint.health.probes.enabled: true esté configurado. Luego, defina los endpoints en su Deployment de Kubernetes:

   livenessProbe:
     httpGet:
       path: /actuator/health/liveness
       port: 8080
     initialDelaySeconds: 10
     periodSeconds: 5
   readinessProbe:
     httpGet:
       path: /actuator/health/readiness
       port: 8080
     initialDelaySeconds: 5
     periodSeconds: 3
   

5. Para métricas personalizadas, agregue un MeterRegistry en su código:

   import io.micrometer.core.instrument.MeterRegistry;
   import org.springframework.stereotype.Component;
   
   @Component
   public class CustomMetrics {
       public CustomMetrics(MeterRegistry registry) {
           registry.counter("app.requests.count");
       }
   }
   

Ejemplo completo

Un archivo application.yml completo para una aplicación con monitoreo y métricas:

server:
  port: 8080

spring:
  application:
    name: mi-app
  security:
    user:
      name: admin
      password: ${ACTUATOR_PASSWORD:default}

management:
  endpoints:
    web:
      exposure:
        include: health,info,metrics,env, prometheus
      base-path: /actuator
  endpoint:
    health:
      show-details: when-authorized
      probes:
        enabled: true
    metrics:
      enabled: true
    prometheus:
      enabled: true
  metrics:
    export:
      prometheus:
        enabled: true
        step: 1m

Notas importantes

• Seguridad: Siempre proteja los endpoints sensibles (como env, configprops, dump) en entornos de producción. Use autenticación básica o tokens JWT.
• Sondas de salud: Asegúrese de que las sondas no dependan de bases de datos externas si la base de datos no es crítica para la operación inicial. Defina HealthIndicator personalizados si lo requiere.
• Métricas: Micrometer permite exportar a múltiples sistemas. Consulte la documentación oficial para más registros.

Recursos adicionales

• Documentación de Spring Boot Actuator
• Guía de Micrometer
• Sondas de salud en Kubernetes