Monitoring Spring Boot Apps with Actuator

1. Introducing Spring Boot Actuator

Spring Boot Actuator is a sub-project that brings production-ready features to your application. When you include it, you get a set of endpoints—accessible over HTTP or JMX—that provide a window into the inner workings of your running application.

Activating Actuator is as simple as adding a single dependency to your pom.xml file.

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

With this dependency on the classpath, Spring Boot automatically configures the Actuator endpoints.

The following video from a Spring I/O conference provides an excellent introduction. The speaker, Michael Vitz, introduces Actuator and demonstrates the initial setup.

2. Exposing and Securing Endpoints

For security reasons, Spring Boot takes a "secure by default" approach. Out of the box, only the /actuator/health endpoint is exposed over HTTP. All other endpoints, which might reveal sensitive internal information about your application's configuration or dependencies, are accessible only via JMX unless you explicitly expose them.

You can control which endpoints are exposed using properties in your application.properties file.

# Expose the health and info endpoints over the web
management.endpoints.web.exposure.include=health,info




# To expose all endpoints (use with caution, especially in production)
# management.endpoints.web.exposure.include=*

Given your background in system design, you'll appreciate the importance of securing these endpoints. The official Spring Boot documentation provides a clear, concise guide on how to configure endpoint exposure and the security implications.

In a production scenario, you would typically either place the application behind a firewall that restricts access to the actuator endpoints or run them on a separate management port (management.server.port) that isn't exposed publicly.

3. The health Endpoint: Your Application's Pulse

The health endpoint is arguably the most critical Actuator endpoint. It aggregates several health checks to provide a single, top-level status of your application. This is exactly what container orchestration systems like Kubernetes use for liveness and readiness probes to manage your application's lifecycle.

A simple GET request to /actuator/health will return:

{
  "status": "UP"
}

This is useful, but often you need more details. You can configure the endpoint to show the status of individual components:

# Show details when authorized, or use 'always' to show to all users.
management.endpoint.health.show-details=when_authorized

With this property set, the response becomes much more informative, showing the status of auto-configured HealthIndicators like diskSpace. If you had a database configured, you would see a db indicator here as well.

Custom Health Indicators

The true power of the health endpoint comes from its extensibility. You can create your own HealthIndicator beans to check the status of any downstream service or internal component that is critical to your application's operation.

To do this, you create a class that implements the HealthIndicator interface and override the health() method. Spring will automatically pick it up and include it in the /actuator/health aggregation.

Here is an example of a custom health indicator that checks a hypothetical external service:

import org.springframework.boot.actuate.health.Health;
import org.springframework.boot.actuate.health.HealthIndicator;
import org.springframework.stereotype.Component;

@Component
public class DownstreamServiceHealthIndicator implements HealthIndicator {

    @Override
    public Health health() {
        // In a real application, you would make an HTTP call or
        // otherwise check the status of the downstream service.
        int errorCode = checkService(); 
        
        if (errorCode != 0) {
            // If the service is down, return a 'DOWN' status with details.
            return Health.down()
                         .withDetail("Error Code", errorCode)
                         .withDetail("Service URL", "http://example.com/api")
                         .build();
        }
        
        // If everything is okay, return an 'UP' status.
        return Health.up().build();
    }

    private int checkService() {
        // Simulate a check. Return 0 for success, non-zero for failure.
        // In reality, this would involve actual logic.
        if (Math.random() > 0.5) {
            return 503; // Simulate a service unavailable error
        }
        return 0;
    }
}

The Spring I/O video provides an excellent practical demonstration of configuring the health endpoint and creating a custom indicator.

4. The info Endpoint: Your Application's ID Card

While the health endpoint reports on the operational status, the info endpoint is designed to expose arbitrary, static information about the application. This can include build information, the git commit hash it was built from, or any other custom data you want to expose. By default, this endpoint is empty.

There are two main ways to add information:

1. Using application.properties

You can add any properties prefixed with info. to your application.properties file.

# Enable the 'env' info contributor to expose these properties
management.info.env.enabled=true

info.app.name=My Awesome App
info.app.description=A microservice for doing great things.
info.app.version=1.0.0

2. Using InfoContributor Beans

For dynamic information, you can implement the InfoContributor interface. This is analogous to how HealthIndicator works for the health endpoint.

import org.springframework.boot.actuate.info.Info;
import org.springframework.boot.actuate.info.InfoContributor;
import org.springframework.stereotype.Component;
import java.util.Map;

@Component
public class CustomInfoContributor implements InfoContributor {

    @Override
    public void contribute(Info.Builder builder) {
        builder.withDetail("custom-info", 
            Map.of("active-profile", "production", "node", "node-123"));
    }
}

You can also automatically include build and git information by configuring plugins in your pom.xml. The spring-boot-maven-plugin can generate a build-info.properties file, and a common git-commit-id-plugin can generate a git.properties file. Actuator will automatically find and display information from these files.

This section from the official documentation provides a complete reference for all the ways you can populate the info endpoint.

Conclusion

In this lesson, you've learned how to integrate Spring Boot Actuator to gain crucial insights into your running application. This is a foundational practice for operating services in any environment, from a single VM to a large-scale Kubernetes cluster.

Key Takeaways:

• Spring Boot Actuator provides production-ready features through a set of endpoints, enabled by the spring-boot-starter-actuator dependency.
• Endpoints are secure by default, with only /actuator/health exposed over HTTP. You must explicitly expose others via the management.endpoints.web.exposure.include property.
• The /actuator/health endpoint aggregates status from multiple HealthIndicators to report the overall health of the application, which is vital for automated monitoring and orchestration.
• The /actuator/info endpoint provides a way to display static and dynamic application information, such as build version or custom metadata.
• Both endpoints are highly extensible, allowing you to write custom HealthIndicator and InfoContributor beans to integrate checks and information specific to your application's domain.

In our next and final practical lesson, we will build upon this foundation by exploring another powerful Actuator endpoint: /actuator/metrics. We will learn how to use Spring Boot Actuator to expose and interpret application metrics, which provide quantitative data about your application's behavior and performance.