Custom actuator endpoints in Spring Boot

Introduction

Custom actuator endpoints let you add your own health or info checks to a Spring Boot app. This helps you see app details or status easily.

You want to show extra app info like version or config values.

You need to check a custom service or resource health.

You want to expose metrics specific to your app.

You want to add a simple status check for external tools.

You want to extend Spring Boot's monitoring with your own data.

Syntax

Spring Boot

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

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

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

The @Endpoint annotation defines a new actuator endpoint with a unique id.

The @ReadOperation marks a method that handles GET requests to this endpoint.

Examples

A simple endpoint named 'status' that returns a running message.

Spring Boot

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

@Component
@Endpoint(id = "status")
public class StatusEndpoint {

    @ReadOperation
    public String status() {
        return "App is running";
    }
}

This endpoint named 'counter' shows a number and lets you increase it via POST.

Spring Boot

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.stereotype.Component;

@Component
@Endpoint(id = "counter")
public class CounterEndpoint {
    private int count = 0;

    @ReadOperation
    public int getCount() {
        return count;
    }

    @WriteOperation
    public void increment() {
        count++;
    }
}

Sample Program

This Spring Boot app adds a custom actuator endpoint at '/actuator/greeting' that returns a greeting message.

Spring Boot

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.stereotype.Component;

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

@Component
@Endpoint(id = "greeting")
class GreetingEndpoint {

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

Important Notes

Make sure to enable your custom endpoint in application.properties if actuator endpoints are restricted.

Custom endpoints appear under the main actuator URL, like /actuator/{id}.

Use @WriteOperation for POST/PUT actions on your endpoint.

Summary

Custom actuator endpoints let you add your own monitoring or info checks.

Use @Endpoint with @ReadOperation or @WriteOperation to define them.

They help you see app status or data easily through HTTP requests.

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