Spring Boot Actuator, How to Monitor Application Health with actuator-health

Spring Boot Actuator provides a wide range of features to monitor and manage your application when it's deployed in a production environment. These features can be accessed via HTTP endpoints or JMX, and they automatically enable capabilities such as auditing, health checks, and metrics collection in your application.

Actuator is essential in cloud-native and microservice architectures, allowing real-time monitoring of application status, metrics, and traffic data. In particular, the /actuator/health endpoint offers a basic mechanism to check if the application is running properly, making it crucial for integration with load balancers, Kubernetes, and other orchestration tools.

Spring Boot Actuator Setup

1. Add Actuator Dependency

• pom.xml (maven)

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

2. Configure application.yaml

management:
  endpoints:
    web:
      exposure:
        include: health,info  # expose only selected endpoints
  endpoint:
    health:
      show-details: always   # 'always' for dev, 'never' for production

If you don't specify management.server.port, actuator endpoints will run on the main application port (e.g., 8080).

Enable Liveness & Readiness Probes

• Spring Boot 2.3.2+ allows you to enable Kubernetes-compatible health probes:

management:
  endpoint:
    health:
      probes:
        enabled: true
  health:
    livenessState:
      enabled: true
    readinessState:
      enabled: true

From Spring Boot 2.3, Actuator automatically provides /actuator/health/liveness and /actuator/health/readiness endpoints.

• The liveness probe checks only if the JVM is alive, while the readiness probe includes dependencies like databases to determine if the app is ready to receive traffic.
• This separation prevents unnecessary container restarts due to temporary dependency issues (e.g., database downtime).
• Kubernetes also supports a startup probe, but Actuator does not provide a dedicated endpoint for this. It is common to reuse the liveness endpoint for startup probes.

4. Security Configuration

• By default, Spring Boot Actuator is protected. To allow access to /actuator/health, update your Spring Security config:

http
	.authorizeHttpRequests(auth -> auth
		.requestMatchers(
		  "/api/v1/public/", // public API
		  "/actuator/**",    // allow actuator access
		).permitAll()
	.requestMatchers(  
		  "/api/v1/users/**",
	).authenticated()  
	.anyRequest().authenticated()

Note: If permitAll() is not specified, the endpoint will require authentication and result in a 403 Forbidden error.

Key Actuator Endpoints

Spring Boot Actuator exposes several endpoints, each serving specific monitoring or management purposes. Common endpoints include:

Endpoint	Purpose
/actuator/health	Shows application health status
/actuator/health/liveness	Checks if JVM is alive (K8s liveness probe)
/actuator/health/readiness	Checks if app is ready for traffic (K8s readiness probe)
/actuator/info	Displays application info
/actuator/metrics	Exposes performance and system metrics
/actuator/env	Displays environment properties
/actuator/loggers	Shows and modifies logger configuration
/actuator/beans	Lists all Spring beans
/actuator/prometheus	For Prometheus metrics scraping (requires Micrometer)

Endpoints are exposed under the /actuator base path by default.

Deep Dive: /actuator/health

The /actuator/health endpoint is the simplest and most essential way to confirm your application is running correctly. It can show not only the overall status but also details such as database connections, disk space, and other dependencies.

Health Status Types

• UP: Component or subsystem is working as expected
• DOWN: Component is not functioning
• OUT_OF_SERVICE: Temporarily unavailable
• UNKNOWN: Status cannot be determined

Example:

$ curl http://your-domain.com:port/actuator/health

{
  "status": "UP"
}

Real-World Use Cases

1. Cloud & On-Premise Monitoring

• In cloud (GCP, AWS, Azure) and on-premise environments, /actuator/health is used to periodically verify application health.
• It also integrates well with monitoring tools like Prometheus, Grafana, and Datadog for real-time status visibility.

2. Kubernetes Integration: Liveness & Readiness Probes

Since Spring Boot 2.3, Actuator supports Kubernetes-native probes, enhancing cloud-native operations.

• Readiness Probe: Indicates if the app is ready to handle traffic.
• Liveness Probe: Indicates if the app is still alive and whether the container needs to be restarted.

These are exposed as:

• /actuator/health/liveness
• /actuator/health/readiness

Example configuration for Kubernetes:

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

3. Incident Detection & Alerts

• When /actuator/health returns DOWN or OUT_OF_SERVICE, you can integrate with Datadog, Zabbix, Opsgenie, etc., to send alerts via Slack, email, or SMS.

4. CI/CD Automation

• After deployment, if /actuator/health returns 200 OK with "status": "UP", the deployment is considered successful; otherwise, the pipeline can trigger an automatic rollback.

Common Errors & How to Fix Them

❗403 Forbidden

• Cause: Missing security configuration (permitAll not set)
• Log example:

o.s.s.w.a.Http403ForbiddenEntryPoint : Pre-authenticated entry point called. Rejecting access

• Solution: Allow public access to /actuator/** in your Spring Security configuration.

❗404 Not Found

• Causes:

  1. Actuator dependency is missing.
  2. Endpoint not exposed in application.yaml.
  3. Endpoint misrouted to static resources.

• Log example:

org.springframework.web.servlet.resource.NoResourceFoundException: No static resource actuator/health.

• Solution:

  • Check dependencies, exposure settings, and endpoint paths.
  • Remember that all actuator endpoints are exposed under the /actuator base path.