Custom actuator endpoints in Spring Boot - Deep Dive

Overview - Custom actuator endpoints

What is it?

Custom actuator endpoints in Spring Boot let you add your own monitoring or management features to your application. They extend the built-in actuator endpoints by exposing new information or actions specific to your app. This helps you keep track of custom metrics, health checks, or operations beyond the default ones.

Why it matters

Without custom actuator endpoints, you would only see generic app info and metrics, missing important details unique to your app. This limits your ability to monitor, troubleshoot, or control your app effectively in real time. Custom endpoints give you tailored insights and controls, making your app easier to manage and more reliable.

Where it fits

Before learning custom actuator endpoints, you should understand basic Spring Boot applications and the default actuator endpoints. After mastering custom endpoints, you can explore advanced monitoring tools, security for actuator endpoints, and integrating with external monitoring systems.

Mental Model

Core Idea

Custom actuator endpoints are like adding your own special control panels to the app’s dashboard for monitoring and managing unique parts of your application.

Think of it like...

Imagine your car’s dashboard has standard gauges like speed and fuel, but you want to add a custom gauge for tire pressure. Custom actuator endpoints are like installing that extra gauge so you can watch something important that the standard dashboard doesn’t show.

┌───────────────────────────────┐
│       Spring Boot App          │
│ ┌───────────────┐             │
│ │ Actuator Core │             │
│ └──────┬────────┘             │
│        │                      │
│ ┌──────▼────────┐             │
│ │ Default       │             │
│ │ Endpoints     │             │
│ └──────┬────────┘             │
│        │                      │
│ ┌──────▼────────┐             │
│ │ Custom        │             │
│ │ Endpoints     │             │
│ └───────────────┘             │
└───────────────────────────────┘

Build-Up - 7 Steps

1

Foundation

Understanding Spring Boot Actuator Basics

Concept: Learn what Spring Boot Actuator is and what default endpoints it provides.

Spring Boot Actuator is a tool that adds ready-made endpoints to your app for monitoring and management. These endpoints show info like app health, metrics, and environment details. You enable it by adding a dependency and configuring properties. For example, /actuator/health shows if the app is running well.

Result

You get a set of default endpoints that give you basic app status and metrics.

Understanding the default actuator endpoints sets the stage for why and how you might want to add your own custom ones.

2

Foundation

How to Enable Actuator in Spring Boot

Concept: Learn the simple steps to add actuator support to a Spring Boot app.

Add the 'spring-boot-starter-actuator' dependency to your project. Then, in application.properties or application.yml, enable the endpoints you want. For example, 'management.endpoints.web.exposure.include=health,info' exposes health and info endpoints over HTTP. Run the app and visit /actuator/health to see the output.

Result

Your app now exposes actuator endpoints accessible via HTTP.

Knowing how to enable actuator endpoints is essential before customizing or extending them.

3

Intermediate

Creating a Simple Custom Endpoint

🤔Before reading on: do you think a custom endpoint is created by implementing an interface or by annotating a class? Commit to your answer.

Concept: Learn how to define a new actuator endpoint by creating a class with a special annotation.

Create a class annotated with @Endpoint(id = "custom") to define a new endpoint named 'custom'. Inside, add methods annotated with @ReadOperation to expose data when the endpoint is called. For example, return a map with some custom info. Register this class as a Spring bean so the actuator picks it up.

Result

A new endpoint /actuator/custom appears, returning your custom data.

Understanding that custom endpoints are beans with special annotations helps you extend actuator functionality cleanly and modularly.

4

Intermediate

Adding Write and Delete Operations

🤔Before reading on: do you think actuator custom endpoints support only read operations or also write/delete? Commit to your answer.

Concept: Learn how to add methods to your custom endpoint that handle write (POST) and delete (DELETE) HTTP requests.

Besides @ReadOperation, you can use @WriteOperation and @DeleteOperation annotations on methods inside your @Endpoint class. For example, a @WriteOperation method can accept parameters and change app state. This lets you control your app remotely via actuator endpoints.

Result

Your custom endpoint supports GET, POST, and DELETE HTTP methods with different behaviors.

Knowing that actuator endpoints can handle multiple HTTP methods allows you to build interactive management features, not just passive info.

5

Intermediate

Securing Custom Actuator Endpoints

🤔Before reading on: do you think custom actuator endpoints are secure by default or need extra configuration? Commit to your answer.

Concept: Learn how to protect your custom endpoints so only authorized users can access them.

By default, actuator endpoints may be exposed publicly or restricted depending on your config. Use Spring Security to secure them. For example, configure HTTP security to require authentication for /actuator/custom. You can also limit exposure in application properties. This prevents unauthorized access to sensitive controls.

Result

Your custom endpoint is protected and requires login or specific roles to access.

Understanding security is critical because exposing management endpoints without protection risks your app’s safety.

6

Advanced

Using @EndpointExtension for Modular Design

🤔Before reading on: do you think all custom endpoint logic must be inside one class or can it be split? Commit to your answer.

Concept: Learn how to split custom endpoint logic into multiple classes using @EndpointExtension for cleaner code.

You can create an @Endpoint class as the main entry point and then add @EndpointExtension classes that add extra operations or data. This helps organize complex endpoints by separating concerns. The extensions must specify which endpoint they extend. Spring Boot merges them into one endpoint at runtime.

Result

Your custom endpoint is modular, easier to maintain, and can grow without clutter.

Knowing how to modularize endpoints prevents messy code and supports large-scale management features.

7

Expert

Custom Endpoint Internals and Runtime Behavior

🤔Before reading on: do you think custom endpoints are simple HTTP controllers or integrated differently? Commit to your answer.

Concept: Understand how Spring Boot actuator discovers, registers, and exposes custom endpoints internally.

At runtime, Spring Boot scans for beans annotated with @Endpoint and registers them with the actuator infrastructure. It creates HTTP mappings dynamically based on the annotated methods (@ReadOperation, etc.). The endpoint ID defines the URL path. Security and exposure settings are applied automatically. This integration allows custom endpoints to behave like built-in ones seamlessly.

Result

Custom endpoints behave consistently with built-in actuator endpoints, including lifecycle and security.

Understanding the internal registration and mapping process helps debug issues and design advanced custom endpoints.

Under the Hood

Spring Boot uses component scanning to find classes annotated with @Endpoint. It then creates proxy handlers that map HTTP requests to the annotated methods inside these classes. Each method annotation (@ReadOperation, @WriteOperation, @DeleteOperation) corresponds to an HTTP verb (GET, POST, DELETE). The actuator framework manages endpoint lifecycle, security, and exposure based on configuration. This dynamic registration means custom endpoints integrate fully with the actuator ecosystem.

Why designed this way?

This design allows developers to add custom management features without modifying actuator core code. Using annotations and Spring’s bean system keeps the API simple and consistent. Alternatives like manual controller creation would be less integrated and harder to secure. The modular approach supports extensibility and maintainability.

┌───────────────────────────────┐
│ Spring Boot Application Context│
│ ┌───────────────────────────┐ │
│ │ @Endpoint Bean            │ │
│ │ + @ReadOperation method   │ │
│ │ + @WriteOperation method  │ │
│ └─────────────┬─────────────┘ │
│               │               │
│ ┌─────────────▼─────────────┐ │
│ │ Actuator Endpoint Registry │ │
│ └─────────────┬─────────────┘ │
│               │               │
│ ┌─────────────▼─────────────┐ │
│ │ HTTP Request Dispatcher   │ │
│ │ Maps /actuator/{id} to    │ │
│ │ annotated methods         │ │
│ └───────────────────────────┘ │
└───────────────────────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Do you think custom actuator endpoints automatically appear without registering as beans? Commit yes or no.

Common Belief: Custom actuator endpoints just need the @Endpoint annotation and will work automatically.

Reality: Custom endpoints must be registered as Spring beans to be discovered and exposed by actuator.

Why it matters: If you forget to register the bean, your custom endpoint won’t appear, causing confusion and wasted debugging time.

Quick: Do you think custom actuator endpoints are always secure by default? Commit yes or no.

Common Belief: All actuator endpoints, including custom ones, are secure out of the box.

Reality: Custom endpoints need explicit security configuration; otherwise, they may be exposed publicly.

Why it matters: Leaving sensitive endpoints unprotected can lead to security breaches and unauthorized control.

Quick: Do you think custom actuator endpoints can only return simple data types? Commit yes or no.

Common Belief: Custom endpoints can only return simple strings or numbers.

Reality: Custom endpoints can return complex objects, maps, or even custom JSON structures.

Why it matters: Limiting return types unnecessarily restricts the usefulness of custom endpoints.

Quick: Do you think custom actuator endpoints must be implemented as REST controllers? Commit yes or no.

Common Belief: You must create a REST controller to add a custom actuator endpoint.

Reality: Custom actuator endpoints use special annotations (@Endpoint) and are not regular REST controllers.

Why it matters: Using REST controllers for actuator endpoints misses integration benefits like automatic security and lifecycle management.

Expert Zone

1

Custom endpoints can be combined with @EndpointExtension to separate read and write logic cleanly, improving maintainability.

2

The actuator framework caches endpoint results by default for performance; understanding this helps when real-time data is needed.

3

Custom endpoints can integrate with Micrometer metrics to expose custom metrics alongside management data.

When NOT to use

Avoid custom actuator endpoints for complex UI or workflows; instead, build dedicated admin REST APIs or web apps. Also, do not use them for heavy processing tasks as actuator endpoints should be lightweight and fast.

Production Patterns

In production, custom actuator endpoints are often used to expose app-specific health checks, feature toggles, or cache stats. They are secured with role-based access and integrated with centralized monitoring tools like Prometheus or Grafana.

Connections

REST API Design

Custom actuator endpoints build on REST principles by mapping HTTP verbs to operations.

Understanding REST helps design intuitive and consistent custom endpoints that fit well with web standards.

Application Monitoring

Custom actuator endpoints extend monitoring by exposing app-specific metrics and health info.

Knowing monitoring concepts helps create endpoints that provide meaningful operational insights.

Modular Software Design

Using @EndpointExtension reflects modular design by separating concerns within a feature.

Appreciating modular design improves maintainability and scalability of custom management features.

Common Pitfalls

#1 Exposing sensitive data without security

Wrong approach:

management.endpoints.web.exposure.include=custom
# No security config, endpoint open to all

Correct approach:

management.endpoints.web.exposure.include=custom
# Plus Spring Security config requiring authentication for /actuator/custom

Root cause:

Assuming actuator endpoints are secure by default leads to accidental data leaks.

#2 Not registering custom endpoint as a bean

Wrong approach:

@Endpoint(id = "custom")
public class CustomEndpoint {
@ReadOperation
public String info() { return "data"; }
}
// No @Component or bean registration

Correct approach:

@Component
@Endpoint(id = "custom")
public class CustomEndpoint {
@ReadOperation
public String info() { return "data"; }
}

Root cause:

Missing bean registration means Spring never discovers the endpoint.

#3 Using REST controller instead of @Endpoint

Wrong approach:

@RestController
@RequestMapping("/actuator/custom")
public class CustomController {
@GetMapping
public String getInfo() { return "data"; }
}

Correct approach:

@Component
@Endpoint(id = "custom")
public class CustomEndpoint {
@ReadOperation
public String info() { return "data"; }
}

Root cause:

Confusing actuator endpoints with normal REST APIs loses actuator integration benefits.

Key Takeaways

Custom actuator endpoints let you add app-specific monitoring and management features beyond defaults.

They are created by defining Spring beans annotated with @Endpoint and special operation annotations.

Custom endpoints support multiple HTTP methods and can return complex data structures.

Security must be explicitly configured to protect custom endpoints from unauthorized access.

Understanding the internal registration and mapping helps build robust and maintainable custom endpoints.