Custom actuator endpoints in Spring Boot - Step-by-Step Execution

Concept Flow - Custom actuator endpoints

Start Spring Boot App

↓

Define Custom Endpoint Class

↓

Annotate with @Endpoint

↓

Add @ReadOperation or @WriteOperation

↓

App Runs and Registers Endpoint

↓

Call /actuator/custom

↓

Execute Method and Return Data

↓

Client Receives Response

The app starts, registers a custom actuator endpoint class with annotated methods, then serves data when the endpoint URL is called.

Execution Sample

Spring Boot

import org.springframework.boot.actuate.endpoint.annotation.*;

@Endpoint(id = "custom")
public class CustomEndpoint {
  @ReadOperation
  public String info() { return "Hello from custom endpoint"; }
}

Defines a custom actuator endpoint named 'custom' that returns a simple string when accessed.

Execution Table

Step	Action	Annotation Used	Result	Endpoint URL
1	Spring Boot starts	N/A	App context initialized	N/A
2	CustomEndpoint class loaded	@Endpoint(id="custom")	Endpoint registered	N/A
3	info() method detected	@ReadOperation	Method ready to serve GET requests	N/A
4	HTTP GET /actuator/custom called	N/A	info() method invoked	/actuator/custom
5	info() returns string	N/A	"Hello from custom endpoint"	/actuator/custom
6	Response sent to client	N/A	Client receives "Hello from custom endpoint"	/actuator/custom

💡 Execution stops after response is sent to client for the custom actuator endpoint.

Variable Tracker

Variable	Start	After Step 2	After Step 3	After Step 5	Final
App Context	Empty	Initialized with CustomEndpoint bean	CustomEndpoint methods registered	N/A	Running with endpoint ready
CustomEndpoint.info()	Not called	Registered	Ready	"Hello from custom endpoint"	Returned response

Key Moments - 3 Insights

Why do we need @Endpoint and @ReadOperation annotations?

The @Endpoint annotation marks the class as a custom actuator endpoint (see Step 2). The @ReadOperation marks the method to handle GET requests (see Step 3). Without these, Spring Boot won't register or expose the endpoint.

What URL do I use to call my custom endpoint?

The URL is /actuator/{id} where id is from @Endpoint(id). Here, it is /actuator/custom as shown in Steps 4-6.

Can the method return other data types?

Yes, methods can return any serializable data like String, Map, or POJOs. Spring Boot converts it to JSON automatically (Step 5).

Visual Quiz - 3 Questions

Look at the execution table, what annotation registers the class as an actuator endpoint?

A @ReadOperation

B @Endpoint

C @WriteOperation

D @Component

💡 Hint

Check Step 2 in the execution table where the class is registered.

At which step does the custom endpoint method get called?

A Step 4

B Step 2

C Step 3

D Step 6

💡 Hint

Look for the HTTP GET request triggering the method invocation.

If you change @Endpoint(id = "custom") to @Endpoint(id = "info"), what changes?

A The app will not start

B The method name must change to info()

C The endpoint URL changes to /actuator/info

D The response string changes automatically

💡 Hint

Refer to the URL column in the execution table and how id affects it.

Concept Snapshot

Custom actuator endpoints let you add your own monitoring URLs.
Use @Endpoint(id = "name") on a class.
Use @ReadOperation for GET methods.
Spring Boot exposes it at /actuator/name.
Return any data; it converts to JSON.
Useful for custom health or info checks.

Full Transcript

This visual trace shows how to create a custom actuator endpoint in Spring Boot. First, the app starts and loads the CustomEndpoint class annotated with @Endpoint. This registers the endpoint with Spring Boot. Then, the method annotated with @ReadOperation is detected and prepared to handle GET requests. When a client calls /actuator/custom, the info() method runs and returns a string. The response is sent back to the client. Variables like the app context and method state change from uninitialized to ready and then to returned response. Key points include the importance of annotations to register and expose the endpoint, the URL pattern based on the id, and the flexibility of return types. The quiz tests understanding of annotations, method invocation step, and URL naming.

Practice

1. What annotation is used to define a custom actuator endpoint in Spring Boot?

easy

A. @Endpoint

B. @Controller

C. @Service

D. @RestController

Solution

1. Step 1: Understand the purpose of custom actuator endpoints

   Custom actuator endpoints allow you to add your own monitoring or info checks in Spring Boot.

2. Step 2: Identify the correct annotation for defining custom endpoints

   The @Endpoint annotation is specifically designed to mark a class as a custom actuator endpoint.

3. Final Answer:

   @Endpoint -> Option A

4. Quick Check:

   Custom actuator endpoint = @Endpoint [OK]

Hint: Custom actuator endpoints always use @Endpoint annotation [OK]

Common Mistakes:

• Confusing @Endpoint with @Controller
• Using @Service instead of @Endpoint
• Using @RestController which is for REST APIs

2. Which annotation should you use on a method inside a custom actuator endpoint to expose a read-only operation?

easy

A. @WriteOperation

B. @ReadOperation

C. @GetMapping

D. @PostMapping

Solution

1. Step 1: Recall method annotations for custom actuator endpoints

   Custom actuator endpoints use specific annotations to define operations: read or write.

2. Step 2: Match read-only operation annotation

   The @ReadOperation annotation marks a method as a read-only operation accessible via HTTP GET.

3. Final Answer:

   @ReadOperation -> Option B

4. Quick Check:

   Read-only method = @ReadOperation [OK]

Hint: Use @ReadOperation for read-only endpoint methods [OK]

Common Mistakes:

• Using @WriteOperation for read methods
• Confusing @GetMapping with actuator annotations
• Using @PostMapping which is for REST controllers

3. Given this custom endpoint class, what will be the HTTP response body when accessing the endpoint?

@Endpoint(id = "status")
public class StatusEndpoint {
  @ReadOperation
  public String getStatus() {
    return "UP";
  }
}

medium

A. "DOWN"

B. 404 Not Found

C. "UP"

D. 500 Internal Server Error

Solution

1. Step 1: Analyze the custom endpoint class

   The class is annotated with @Endpoint(id = "status") and has a method with @ReadOperation returning "UP".

2. Step 2: Understand the HTTP response from the read operation

   Accessing the actuator endpoint with id "status" triggers the getStatus() method, returning the string "UP" as the response body.

3. Final Answer:

   "UP" -> Option C

4. Quick Check:

   Read operation returns "UP" [OK]

Hint: ReadOperation returns method result as HTTP response body [OK]

Common Mistakes:

• Expecting 404 if endpoint is defined correctly
• Confusing return value with HTTP status code
• Assuming method returns JSON object instead of string

4. Identify the error in this custom actuator endpoint code:

@Endpoint(id = "metrics")
public class MetricsEndpoint {
  @ReadOperation
  public String metrics() {
    return 12345;
  }
}

medium

A. The @ReadOperation annotation is missing

B. The method name must be getMetrics

C. The @Endpoint annotation must be on a method, not class

D. The method declares String return type but returns an int

Solution

1. Step 1: Check method return type consistency

   The method metrics() returns an integer literal 12345 but declares return type String, causing a type mismatch.

2. Step 2: Verify annotations and method naming

   The @ReadOperation annotation is present, and @Endpoint is correctly on the class. Method name can be arbitrary.

3. Final Answer:

   The method declares String return type but returns an int -> Option D

4. Quick Check:

   Return type mismatch causes error [OK]

Hint: Method return type must match declared type [OK]

Common Mistakes:

• Thinking @Endpoint goes on methods
• Assuming method name must follow getter pattern
• Ignoring type mismatch errors

5. You want to create a custom actuator endpoint that accepts a POST request to update a configuration value. Which combination of annotations and method signature is correct? A)

@Endpoint(id = "config")
public class ConfigEndpoint {
  @WriteOperation
  public String updateConfig(String key, String value) {
    // update logic
    return "Updated";
  }
}

B)

@Endpoint(id = "config")
public class ConfigEndpoint {
  @ReadOperation
  public void updateConfig(String key, String value) {
    // update logic
  }
}

C)

@Endpoint(id = "config")
public class ConfigEndpoint {
  @WriteOperation
  public void updateConfig() {
    // update logic
  }
}

D)

@Endpoint(id = "config")
public class ConfigEndpoint {
  @WriteOperation
  public String updateConfig() {
    // update logic
    return "Updated";
  }
}

hard

A. Option A is correct because @WriteOperation supports parameters and returns a response

B. Option B is correct because @ReadOperation can update values

C. Option C is correct because @WriteOperation methods cannot have parameters

D. Option D is correct because @WriteOperation methods should not have parameters

Solution

1. Step 1: Understand @WriteOperation usage

   @WriteOperation marks methods that handle write operations, typically POST, and can accept parameters for input.

2. Step 2: Analyze method signatures and annotations

   The correct combination uses @WriteOperation with String key and String value parameters and returns a String response, which is valid for POST updates. Using @ReadOperation is wrong for update operations. The other snippets lack parameters needed to receive key and value.

3. Final Answer:

   Option A is correct because @WriteOperation supports parameters and returns a response -> Option A

4. Quick Check:

   @WriteOperation with parameters for POST updates [OK]

Hint: Use @WriteOperation with parameters for POST updates [OK]

Common Mistakes:

• Using @ReadOperation for write/update methods
• Omitting parameters needed for update
• Assuming @WriteOperation methods cannot return values