Spring Actuator

Here you will see example on creating custom endpoints in Spring Boot Actuator. There are a number of endpoints provided by Spring Boot however you may want to create a custom endpoint using Spring Boot Actuator.

You have seen few examples on Spring Boot actuators:

• Spring Boot Actuator Example
• Spring Boot Actuator – Accessing Endpoints via JMX
• Spring Boot Actuator – Securing Endpoints

Prerequisites

Java 12/19, Spring Boot 2.2.5/3.1.4, Maven 3.6.3/3.8.5

First go through the example Spring Boot Actuator – Production Ready Features

Custom Endpoints

If you add a @Bean annotated with @Endpoint, any methods annotated with @ReadOperation, @WriteOperation, or @DeleteOperation are automatically exposed over JMX and, in a web application, over HTTP as well. Endpoints can be exposed over HTTP using Jersey, Spring MVC, or Spring WebFlux.

You can also write technology-specific endpoints by using @JmxEndpoint (exposed only over JMX and not over HTTP) or @WebEndpoint (exposed only over HTTP and not over JMX).

You can write technology-specific extensions by using @EndpointWebExtension and @EndpointJmxExtension. These annotations let you provide technology-specific operations to augment an existing endpoint.

Finally, if you need access to web-framework-specific functionality, you can implement Servlet or Spring @Controller and @RestController endpoints at the cost of them not being available over JMX or when using a different web framework.

Here you will see examples on @Endpoint, @ControllerEndpoint and @RestControllerEndpoint.

VO class

Create below VO (Value Object) class, which is a POJO class holds data or value and does nothing special.

public class Greeting {

	private final long id;
	private final String content;

	public Greeting(long id, String content) {
		this.id = id;
		this.content = content;
	}

	public long getId() {
		return id;
	}

	public String getContent() {
		return content;
	}

}

@Endpoint

Create below class, which is annotated with @Endpoint and it means that I am creating custom endpoint using Spring Boot Actuator.

The class must have @Component annotation in order to let container pick up the class.

You must provide a unique id to the endpoint in order to identify it.

I have shown here @ReadOperation, which is equivalent to HTTP GET request. You can also create other operations, such as, @WriteOperation (POST), @DeleteOperation (DELETE).

I have taken an input as a query parameter called name in sayHello() method. If you do not provide any name to the parameter then it will automatically pick the name as variable name. Here it is “String name”, so the parameter name is “name”.

@Component
@Endpoint(id = "hello-endpoint")
public class GreetingEndpoint {

	private static final String template = "Hello, %s!";
	private final AtomicLong counter = new AtomicLong();

	@ReadOperation
	public Greeting sayHello(@RequestParam(defaultValue = "Stranger") String name) {
		return new Greeting(counter.incrementAndGet(), String.format(template, name));
	}
}

@ControllerEndpoint and @RestControllerEndpoint

@ControllerEndpoint and @RestControllerEndpoint can be used to implement an endpoint that is only exposed by Spring MVC or Spring WebFlux. Methods are mapped using the standard annotations for Spring MVC and Spring WebFlux such as @RequestMapping and @GetMapping, with the endpoint’s ID being used as a prefix for the path. Controller endpoints provide deeper integration with Spring’s web frameworks but at the expense of portability. The @Endpoint and @WebEndpoint annotations should be preferred whenever possible.

@ControllerEndpoint

You must provide a unique id to the endpoint in order to identify it.

I have used @ResponseBody because I want response to be displayed directly on the body of the response rather than using a view file, such as, jsp.

@Component
@ControllerEndpoint(id = "controller-endpoint")
public class GreetingController {

	private static final String template = "Hello, %s!";
	private final AtomicLong counter = new AtomicLong();

	@ResponseBody
	@GetMapping("/hello")
	public Greeting greet(@RequestParam(defaultValue = "Stranger") String name) {
		return new Greeting(counter.incrementAndGet(), String.format(template, name));
	}

}

@RestControllerEndpoint

You must provide a unique id to the endpoint in order to identify it.

@Component
@RestControllerEndpoint(id = "rest-controller-endpoint")
public class GreetingRestController {

	private static final String template = "Hello, %s!";
	private final AtomicLong counter = new AtomicLong();

	@GetMapping("/hello")
	public ResponseEntity<Greeting> greet(@RequestParam(defaultValue = "Stranger") String name) {
		return new ResponseEntity<Greeting>(new Greeting(counter.incrementAndGet(), String.format(template, name)),
				HttpStatus.OK);
	}

}

Exposing Endpoints

Now either you can expose only the endpoints you have created above or you can expose all endpoints including the above endpoints.

If you want to expose all endpoints then add below line to application.properties file:

management.endpoints.web.exposure.include=*

If you want to expose only the above endpoints, which you have created then add below line to the application.properties file:

management.endpoints.web.exposure.include=hello-endpoint,controller-endpoint,rest-controller-endpoint

Main Class

The main class helps you to start and deploy the Spring Boot application into embedded Tomcat server.

@SpringBootApplication
public class ActuatorApplication {

	public static void main(String[] args) {
		SpringApplication.run(ActuatorApplication.class, args);
	}

}

Testing the Actuator Custom Endpoint

Run the above main class to deploy the application.

Now hit the URLs either from REST client or in the browser directly.

You will get same output for the below URLs:

http://localhost:8080/actuator/hello-endpoint?name=Soumitra
http://localhost:8080/actuator/controller-endpoint/hello?name=Soumitra
http://localhost:8080/actuator/rest-controller-endpoint/hello?name=Soumitra

You will get same output for the below URLs:

http://localhost:8080/actuator/controller-endpoint/hello
http://localhost:8080/actuator/rest-controller-endpoint/hello

Source Code

Download