Spring Boot Actuator: Monitoring and Health Checks Explained

Date: October 20, 2024

In modern web applications, keeping an eye on your app’s health, metrics, and performance is crucial. Spring Boot Actuator is the go-to solution for adding powerful monitoring and management capabilities to your Spring Boot apps—without much hassle.

This post dives deep into Spring Boot Actuator, covering its core features, how to configure it, and how to customize health checks and metrics for your app.

What Is Spring Boot Actuator?

Spring Boot Actuator is a sub-project of Spring Boot that provides production-ready features out of the box. It exposes HTTP endpoints (or JMX) that let you:

Monitor app health
Track metrics like JVM memory, CPU usage, HTTP request counts, etc.
Access detailed info about app beans, environment, and configuration
Manage logging levels on the fly
Perform health checks and get readiness/liveness signals for orchestration tools like Kubernetes

Getting Started: Adding Actuator

Start by adding the dependency in your pom.xml or build.gradle:

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

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

By default, Actuator enables several endpoints at /actuator/*.

Key Actuator Endpoints

Here are some essential endpoints:

Endpoint	Purpose
`/actuator/health`	Shows overall health status
`/actuator/metrics`	Lists available metrics
`/actuator/metrics/{name}`	Details for a specific metric (e.g., `jvm.memory.used`)
`/actuator/env`	Displays environment properties
`/actuator/loggers`	View and change logging levels
`/actuator/info`	General application info (customizable)
`/actuator/threaddump`	JVM thread dump
`/actuator/httptrace`	Last few HTTP request traces

Example: Viewing Health Endpoint

Run your Spring Boot app, then open:

http://localhost:8080/actuator/health

Typical JSON response:

{
  "status": "UP",
  "components": {
    "db": {
      "status": "UP",
      "details": {
        "database": "PostgreSQL",
        "validationQuery": "isValid()"
      }
    },
    "diskSpace": {
      "status": "UP",
      "details": {
        "total": 499963174912,
        "free": 124982374912,
        "threshold": 10485760
      }
    }
  }
}

By default, Actuator includes health indicators for common components like databases and disk space.

Customizing Health Checks

You can add your own health checks by implementing HealthIndicator:

@Component
public class CustomHealthIndicator implements HealthIndicator {

    @Override
    public Health health() {
        boolean systemUp = checkSystemStatus();
        if (systemUp) {
            return Health.up().withDetail("CustomService", "Available").build();
        } else {
            return Health.down().withDetail("CustomService", "Not Available").build();
        }
    }

    private boolean checkSystemStatus() {
        // Custom logic here, e.g., ping an external API or check resource availability
        return true;
    }
}

Now, /actuator/health will include your custom health details.

Enabling/Disabling Endpoints

Not all endpoints are enabled by default for security reasons. Configure them in application.properties or application.yml:

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

Or to expose all endpoints (not recommended for production):

management.endpoints.web.exposure.include=*

Monitoring Metrics

Actuator collects tons of JVM and HTTP metrics automatically, accessible via /actuator/metrics.

Example: Check JVM memory usage

GET /actuator/metrics/jvm.memory.used

Response includes measurements with tags like heap vs non-heap, memory pool names, etc.

Integrating with Monitoring Systems

Actuator integrates seamlessly with external monitoring and visualization systems like:

Prometheus: Use micrometer-registry-prometheus to expose metrics in Prometheus format.
Grafana: Visualize Prometheus metrics.
Spring Boot Admin: A community project to monitor and manage Spring Boot applications via a nice UI.

Add Prometheus support:

<dependency>
  <groupId>io.micrometer</groupId>
  <artifactId>micrometer-registry-prometheus</artifactId>
</dependency>

Health Checks for Kubernetes

Kubernetes uses readiness and liveness probes to manage container lifecycle. Spring Boot Actuator can be configured to support these:

management.health.probes.enabled=true
management.endpoint.health.probes.enabled=true

You can then wire Kubernetes probes to endpoints like:

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

Summary

Spring Boot Actuator:

Provides easy-to-use monitoring & management endpoints.
Enables health checks essential for microservices and cloud environments.
Collects detailed JVM, HTTP, and custom application metrics.
Integrates smoothly with popular monitoring tools.
Supports readiness and liveness for Kubernetes and other orchestrators.

Adding Actuator to your Spring Boot projects equips you with powerful insights and control with minimal effort.

Next Steps

Try creating your own HealthIndicator for custom components.
Explore Micrometer to add application-specific metrics.
Set up Prometheus and Grafana dashboards.
Learn how to secure actuator endpoints in production.