2.5 Actuator and Production Monitoring

In production, you need to expose your application’s health and metrics for load balancers, APM, and orchestration. Spring Boot Actuator provides a standard set of HTTP (or JMX) endpoints for monitoring and management.

Reference: Spring Boot 3.2.x, spring-boot-starter-actuator

1. What is Actuator?

Actuator is a set of health, metrics, and management endpoints for a Spring Boot application. It is commonly used for load balancer health checks, APM integration, and Kubernetes liveness/readiness probes.

2. Dependency and Basic Configuration

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-actuator'
}

Restricting which endpoints are exposed in application.yml is recommended for security. In production, often only health and info are exposed.

management:
  endpoints:
    web:
      exposure:
        include: health,info,metrics
      base-path: /actuator
  endpoint:
    health:
      show-details: when-authorized

3. Main Endpoints

Endpoint	Description	Use case
/actuator/health	Application, DB, disk, etc.	Load balancer health check, K8s probes
/actuator/info	Build/version info (you configure)	Deployment verification
/actuator/metrics	JVM, HTTP, connection pool metrics	APM, Grafana
/actuator/metrics/{name}	Specific metric values	Detailed monitoring

Health response example

With show-details: always, the response can look like:

{
  "status": "UP",
  "components": {
    "db": {
      "status": "UP",
      "details": {
        "database": "MySQL",
        "validationQuery": "isValid()"
      }
    },
    "diskSpace": {
      "status": "UP",
      "details": {
        "total": 500000000000,
        "free": 250000000000,
        "threshold": 10485760
      }
    }
  }
}

4. Custom Health Indicator

You can add health checks for critical external systems (payment gateway, cache, etc.) by implementing HealthIndicator.

@Component
public class CustomPaymentHealthIndicator implements HealthIndicator {

    private final PaymentGatewayClient paymentClient;

    @Override
    public Health health() {
        try {
            boolean reachable = paymentClient.ping();
            return reachable
                ? Health.up().withDetail("payment", "available").build()
                : Health.down().withDetail("payment", "unreachable").build();
        } catch (Exception e) {
            return Health.down(e).build();
        }
    }
}

5. Graceful Shutdown

For zero-downtime deployments, enable graceful shutdown so the application finishes in-flight requests before exiting.

server:
  shutdown: graceful

spring:
  lifecycle:
    timeout-per-shutdown-phase: 30s

Spring Boot will stop accepting new requests and wait up to timeout-per-shutdown-phase for existing requests to complete before shutting down.

6. Exposing build info in /actuator/info

Add the following to build.gradle and rebuild; then /actuator/info can expose git and build metadata.

springBoot {
    buildInfo()
}

---

tip

In production, keep management.endpoints.web.exposure.include minimal and restrict /actuator to internal networks or VPN. You can also secure Actuator endpoints with Spring Security.