How to Create Custom Actuator Endpoint in Spring Boot

To create a custom actuator endpoint in Spring Boot, define a class annotated with @Endpoint and add methods annotated with @ReadOperation, @WriteOperation, or @DeleteOperation. Then, register this class as a Spring bean to expose the endpoint under /actuator/yourEndpointId.

Syntax

Use @Endpoint(id = "yourEndpointId") on a class to define a custom actuator endpoint. Inside, use @ReadOperation for GET operations, @WriteOperation for POST, and @DeleteOperation for DELETE. Register the class as a Spring bean to activate it.

• @Endpoint: Marks the class as an actuator endpoint with a unique ID.
• @ReadOperation: Defines a method to handle GET requests.
• @WriteOperation: Defines a method to handle POST requests.
• @DeleteOperation: Defines a method to handle DELETE requests.

java

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

@Component
@Endpoint(id = "custom")
public class CustomEndpoint {

    @ReadOperation
    public String read() {
        return "This is a custom actuator endpoint response";
    }

    @WriteOperation
    public String write(String input) {
        return "Received input: " + input;
    }

    @DeleteOperation
    public String delete() {
        return "Delete operation performed";
    }
}

Example

This example shows a simple custom actuator endpoint named custom that supports GET, POST, and DELETE operations. It returns fixed messages or echoes input for POST.

java

package com.example.demo;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.boot.actuate.endpoint.annotation.Endpoint;
import org.springframework.boot.actuate.endpoint.annotation.ReadOperation;
import org.springframework.boot.actuate.endpoint.annotation.WriteOperation;
import org.springframework.boot.actuate.endpoint.annotation.DeleteOperation;
import org.springframework.stereotype.Component;

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

@Component
@Endpoint(id = "custom")
class CustomEndpoint {

    @ReadOperation
    public String read() {
        return "Hello from custom actuator endpoint!";
    }

    @WriteOperation
    public String write(String message) {
        return "You sent: " + message;
    }

    @DeleteOperation
    public String delete() {
        return "Custom endpoint delete called";
    }
}

Output

GET /actuator/custom
Response: Hello from custom actuator endpoint!

POST /actuator/custom with body 'Test'
Response: You sent: Test

DELETE /actuator/custom
Response: Custom endpoint delete called

Common Pitfalls

• Forgetting to annotate the class with @Component so Spring can detect the endpoint bean.
• Using an id in @Endpoint that conflicts with existing actuator endpoints.
• Not enabling actuator endpoints in application.properties (e.g., management.endpoints.web.exposure.include=* to expose all).
• Defining methods without the proper @ReadOperation, @WriteOperation, or @DeleteOperation annotations.

java

/* Wrong: Missing @Component annotation */

@Endpoint(id = "custom")
public class CustomEndpoint {
    @ReadOperation
    public String read() {
        return "No component annotation";
    }
}

/* Right: Add @Component to register bean */

import org.springframework.stereotype.Component;

@Component
@Endpoint(id = "custom")
public class CustomEndpoint {
    @ReadOperation
    public String read() {
        return "Properly registered endpoint";
    }
}

Quick Reference

Remember these key points when creating custom actuator endpoints:

• @Endpoint(id = "name"): Defines the endpoint ID.
• @ReadOperation: Handles GET requests.
• @WriteOperation: Handles POST requests.
• @DeleteOperation: Handles DELETE requests.
• Register your endpoint class as a Spring bean with @Component.
• Expose endpoints in application.properties with management.endpoints.web.exposure.include=custom or *.

Key Takeaways

Annotate your class with @Endpoint and give it a unique id to create a custom actuator endpoint.

Use @ReadOperation, @WriteOperation, and @DeleteOperation to define GET, POST, and DELETE methods respectively.

Register the endpoint class as a Spring bean with @Component to activate it.

Ensure your custom endpoint is exposed by configuring management.endpoints.web.exposure.include in application.properties.

Avoid id conflicts with existing actuator endpoints and always use proper annotations on methods.