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
𧱠Step 1: Add Required Dependencies
Make sure you include the Actuator module:
|
1 2 3 4 5 6 7 |
<dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-actuator</artifactId> </dependency> |
Optionally, you may include Spring Security if you plan to secure it:
|
1 2 3 4 5 6 7 |
<dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-security</artifactId> </dependency> |
π οΈ Step 2: Create a Custom Actuator Endpoint
Spring Boot 3 uses @Endpoint, @ReadOperation, @WriteOperation, and @DeleteOperation.
π Example: Cache Monitoring Endpoint
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 |
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<String, Object> getCacheStatistics() { Map<String, Object> stats = new HashMap<>(); stats.put("cacheSize", 120); stats.put("hits", 340); stats.put("misses", 45); return stats; } } |
Now, you can access it via:
|
1 2 3 4 |
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:
|
1 2 3 4 5 6 7 8 |
management: endpoints: web: exposure: include: health, info, cache-stats |
βοΈ Other Operation Types
π Write Operation Example
|
1 2 3 4 5 6 7 8 |
@WriteOperation public String resetCache() { // logic to clear/reset cache return "Cache cleared!"; } |
β Delete Operation Example
|
1 2 3 4 5 6 7 8 |
@DeleteOperation public String deleteOldStats() { // remove old stats logic return "Old stats removed."; } |
These map to:
POST /actuator/cache-statsDELETE /actuator/cache-stats
π Step 4: Securing Custom Actuator Endpoints
Spring Security allows you to lock down endpoints.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
@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:
|
1 2 3 4 |
curl http://localhost:8080/actuator/cache-stats |
Expected output:
|
1 2 3 4 5 6 7 8 |
{ "cacheSize": 120, "hits": 340, "misses": 45 } |
Or for the write operation:
|
1 2 3 4 |
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.