Custom Actuator Endpoints in Spring Boot 3

Spring Boot Actuator provides several out-of-the-box endpoints like /actuator/health, /metrics, and /info. But what if you need application-specific diagnostics?

That’s where Custom Actuator Endpoints in Spring Boot come into play. You can easily create your own endpoints to expose internal state, cache info, system checks, and more.

In this tutorial, you’ll learn:

  • How to create a custom actuator endpoint
  • Different types of endpoints (read-only, write, delete)
  • How to expose and secure them
  • How to integrate with Spring Boot 3 changes
Custom Actuator Endpoints in Spring Boot 3

🧱 Step 1: Add Required Dependencies

Make sure you include the Actuator module:



    org.springframework.boot
    spring-boot-starter-actuator

Optionally, you may include Spring Security if you plan to secure it:



    org.springframework.boot
    spring-boot-starter-security

🛠️ Step 2: Create a Custom Actuator Endpoint

Spring Boot 3 uses @Endpoint, @ReadOperation, @WriteOperation, and @DeleteOperation.

📁 Example: Cache Monitoring Endpoint


package com.kscodes.springboot.actuator;

import org.springframework.boot.actuate.endpoint.annotation.Endpoint;
import org.springframework.boot.actuate.endpoint.annotation.ReadOperation;
import org.springframework.stereotype.Component;

import java.util.HashMap;
import java.util.Map;

@Component
@Endpoint(id = "cache-stats")
public class CacheStatsEndpoint {

    @ReadOperation
    public Map getCacheStatistics() {
        Map stats = new HashMap<>();
        stats.put("cacheSize", 120);
        stats.put("hits", 340);
        stats.put("misses", 45);
        return stats;
    }
}

Now, you can access it via:


GET /actuator/cache-stats

🧑‍🔧 Step 3: Enable the Custom Endpoint

By default, only certain endpoints are exposed. You’ll need to include your custom endpoint in application.yml:


management:
  endpoints:
    web:
      exposure:
        include: health, info, cache-stats

✏️ Other Operation Types

🔄 Write Operation Example


@WriteOperation
public String resetCache() {
    // logic to clear/reset cache
    return "Cache cleared!";
}

❌ Delete Operation Example


@DeleteOperation
public String deleteOldStats() {
    // remove old stats logic
    return "Old stats removed.";
}

These map to:

  • POST /actuator/cache-stats
  • DELETE /actuator/cache-stats

🔐 Step 4: Securing Custom Actuator Endpoints

Spring Security allows you to lock down endpoints.


@Bean
public SecurityFilterChain security(HttpSecurity http) throws Exception {
    http
      .authorizeHttpRequests(authorize -> authorize
          .requestMatchers("/actuator/health").permitAll()
          .requestMatchers("/actuator/cache-stats").hasRole("ADMIN")
          .anyRequest().authenticated()
      )
      .httpBasic(); // Or JWT, OAuth2, etc.

    return http.build();
}

🧪 Step 5: Testing the Endpoint

Make a GET request:


curl http://localhost:8080/actuator/cache-stats

Expected output:


{
  "cacheSize": 120,
  "hits": 340,
  "misses": 45
}

Or for the write operation:


curl -X POST http://localhost:8080/actuator/cache-stats

📘 Summary

  • Custom Actuator Endpoints in Spring Boot allow developers to expose app-specific data for observability.
  • Use annotations like @Endpoint, @ReadOperation, @WriteOperation, and @DeleteOperation.
  • You can secure these endpoints using Spring Security and expose only what’s necessary.
  • Great for diagnostics, monitoring, troubleshooting, or DevOps tooling.

🔗 Resources