Spring Boot 4 Migration: Actuator Health Package Guide

Nov 25, 2025 by Alex Johnson 55 views

Are you migrating to Spring Boot 4 and encountering issues with missing org.springframework.boot.actuate.health packages for your custom health endpoints? You're not alone! Many developers upgrading from Spring Boot 3.x are facing this challenge. This comprehensive guide will walk you through the changes in Spring Boot 4, explain why the health package is no longer available, and provide a step-by-step solution for implementing custom health indicators in your applications.

Understanding the Changes in Spring Boot 4

Spring Boot 4 brings significant updates and improvements, but with these come some breaking changes. One notable change is the restructuring of the Actuator Health API. The org.springframework.boot.actuate.health package, which was commonly used in Spring Boot 3.x for creating custom health indicators, has been removed. This means that code relying on classes like Health, Status, and AbstractHealthIndicator will no longer compile after upgrading.

Why Was the Health Package Removed?

The decision to remove the org.springframework.boot.actuate.health package was driven by the desire to simplify the Health API and align it with modern reactive programming paradigms. The old API was based on a blocking, imperative style, which didn't fit well with Spring's evolving support for reactive applications using Spring WebFlux. The new approach encourages the use of reactive types and asynchronous health checks.

Impact on Your Application

If you're upgrading from Spring Boot 3.x and your application uses custom health indicators implemented with the old org.springframework.boot.actuate.health package, you'll need to refactor your code to use the new API. This involves replacing the old classes and interfaces with their reactive counterparts.

Migrating Custom Health Indicators to Spring Boot 4

Now, let's dive into the steps required to migrate your custom health indicators to Spring Boot 4. We'll cover the key concepts and provide code examples to help you through the process.

Step 1: Update Dependencies

First, ensure that you have the necessary dependencies in your pom.xml or build.gradle file. You'll need the spring-boot-starter-actuator dependency, which provides the core Actuator functionality.

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

Make sure the version matches your Spring Boot 4 version.

Step 2: Replace `Health` and `Status` with Reactive Types

In Spring Boot 4, the Health and Status classes have been replaced with reactive types. Instead of using org.springframework.boot.actuate.health.Health, you'll now work with org.springframework.boot.actuate.health.ReactiveHealthIndicator and reactor.core.publisher.Mono<org.springframework.boot.actuate.health.Health>. The Status enum is also replaced with a builder pattern within the Health object.

Here’s how you can adapt your custom health indicator:

Old (Spring Boot 3.x):

import org.springframework.boot.actuate.health.AbstractHealthIndicator;
import org.springframework.boot.actuate.health.Health;
import org.springframework.boot.actuate.health.Status;

public abstract class AbstractCustomHealthIndicator extends AbstractHealthIndicator {

    @Override
    protected void doHealthCheck(Health.Builder builder) throws Exception {
        // Your health check logic here
    }
}

New (Spring Boot 4):

import org.springframework.boot.actuate.health.ReactiveHealthIndicator;
import org.springframework.boot.actuate.health.Health;
import org.springframework.stereotype.Component;
import reactor.core.publisher.Mono;

@Component
public class CustomHealthIndicator implements ReactiveHealthIndicator {

    @Override
    public Mono<Health> health() {
        return checkHealth().onErrorResume(e -> Mono.just(Health.down(e).build()));
    }

    private Mono<Health> checkHealth() {
        // Your asynchronous health check logic here
        return Mono.just(Health.up().withDetail("message", "Service is healthy").build());
    }
}

Step 3: Implement `ReactiveHealthIndicator`

In the new API, you need to implement the ReactiveHealthIndicator interface. This interface has a single method, health(), which returns a Mono<Health>. This Mono represents an asynchronous computation that will eventually produce a Health object.

The Health object is built using a builder pattern, allowing you to specify the status (UP, DOWN, etc.) and add details as key-value pairs. This approach provides more flexibility and clarity compared to the old Status enum.

Step 4: Handle Asynchronous Health Checks

One of the key benefits of the new API is its support for asynchronous health checks. This means you can perform non-blocking operations, such as database queries or external service calls, without tying up threads. Use reactor.core.publisher.Mono and reactor.core.publisher.Flux to manage asynchronous operations.

For example, if you need to check the status of an external service, you can use Spring's WebClient in a reactive manner:

import org.springframework.boot.actuate.health.ReactiveHealthIndicator;
import org.springframework.boot.actuate.health.Health;
import org.springframework.stereotype.Component;
import org.springframework.web.reactive.function.client.WebClient;
import reactor.core.publisher.Mono;

@Component
public class ExternalServiceHealthIndicator implements ReactiveHealthIndicator {

    private final WebClient webClient;

    public ExternalServiceHealthIndicator(WebClient.Builder webClientBuilder) {
        this.webClient = webClientBuilder.baseUrl("https://example.com").build();
    }

    @Override
    public Mono<Health> health() {
        return webClient.get().uri("/status")
                .exchangeToMono(response -> {
                    if (response.statusCode().is2xxSuccessful()) {
                        return Mono.just(Health.up().withDetail("message", "External service is healthy").build());
                    }
                    return Mono.just(Health.down().withDetail("error", "External service is down").build());
                })
                .onErrorResume(e -> Mono.just(Health.down(e).build()));
    }
}

Step 5: Register Your Health Indicator

To register your custom health indicator, simply annotate it with @Component. Spring Boot will automatically discover and include it in the health endpoint.

import org.springframework.boot.actuate.health.ReactiveHealthIndicator;
import org.springframework.boot.actuate.health.Health;
import org.springframework.stereotype.Component;
import reactor.core.publisher.Mono;

@Component
public class CustomHealthIndicator implements ReactiveHealthIndicator {
    // ... implementation ...
}

Example: Migrating `AbstractCustomHealthIndicator`

Let's consider the example provided in the original question. The AbstractCustomHealthIndicator class needs to be refactored to use the new ReactiveHealthIndicator interface and reactive types.

Old (Spring Boot 3.x):

import org.springframework.boot.actuate.health.AbstractHealthIndicator;
import org.springframework.boot.actuate.health.Health;
import org.springframework.boot.actuate.health.Status;

public abstract class AbstractCustomHealthIndicator extends AbstractHealthIndicator {

    @Override
    protected void doHealthCheck(Health.Builder builder) throws Exception {
        doRealHealthCheck(builder);
    }

    protected abstract void doRealHealthCheck(Health.Builder builder) throws Exception;
}

New (Spring Boot 4):

import org.springframework.boot.actuate.health.Health;
import org.springframework.boot.actuate.health.ReactiveHealthIndicator;
import org.springframework.stereotype.Component;
import reactor.core.publisher.Mono;

@Component
public abstract class AbstractCustomReactiveHealthIndicator implements ReactiveHealthIndicator {

    @Override
    public Mono<Health> health() {
        return checkHealth().onErrorResume(e -> Mono.just(Health.down(e).build()));
    }

    protected abstract Mono<Health> checkHealth();
}

Now, a concrete implementation of this abstract class would look like this:

import org.springframework.boot.actuate.health.Health;
import org.springframework.stereotype.Component;
import reactor.core.publisher.Mono;

@Component
public class DatabaseHealthIndicator extends AbstractCustomReactiveHealthIndicator {

    @Override
    protected Mono<Health> checkHealth() {
        // Your database health check logic here
        return Mono.just(Health.up().withDetail("database", "connected").build());
    }
}

Key Considerations

Error Handling: Use onErrorResume to handle exceptions and return a Health.down() status. This ensures that your health endpoint doesn't crash if a health check fails.
Asynchronous Operations: Embrace reactive programming for non-blocking health checks. This improves the performance and scalability of your application.
Testing: Write unit tests for your health indicators to ensure they function correctly. Use Spring's testing support for Actuator endpoints.

Conclusion

Migrating to Spring Boot 4 requires adapting to the new Actuator Health API, but the benefits of reactive programming and simplified health checks are well worth the effort. By following this guide, you can successfully migrate your custom health indicators and ensure your application remains observable and resilient.

Remember, the key is to embrace the reactive paradigm and use ReactiveHealthIndicator along with Mono and Flux to perform asynchronous health checks. This not only aligns with Spring Boot's modern approach but also improves the performance and scalability of your applications.

For further reading and more detailed information, refer to the official Spring Boot documentation and Spring Boot Actuator Reference Documentation.