If your app had a public persona and a secret diary the Actuator would be the diary. This guide shows how to add a custom Spring Boot Actuator endpoint to expose app specific metrics and lightweight operations without turning your production environment into a public confessional. Expect Java examples, property tweaks, and a few sarcastic comments to keep you awake.

Why add a custom Actuator endpoint

Spring Boot Actuator already gives you health checks, metrics and info out of the box. A custom endpoint lets you add application specific data or operations in a neat, discoverable place for monitoring and debugging. Useful for custom metrics, feature toggles, or quick diagnostic dumps when something goes wrong.

Dependencies and project setup

Add the Actuator starter so Spring Boot brings the management endpoints to the party. Use Maven or Gradle depending on your build tool.

For Maven

<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>

For Gradle

implementation 'org.springframework.boot:spring-boot-starter-actuator'

Create the custom endpoint class

Make a Spring bean that Spring Boot can component scan and annotate it with @Endpoint. Use @ReadOperation for safe queries and @WriteOperation for actions that change state.

package com.example.monitoring

import org.springframework.boot.actuate.endpoint.annotation.Endpoint
import org.springframework.boot.actuate.endpoint.annotation.ReadOperation
import org.springframework.stereotype.Component
import java.util.Map

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

  @ReadOperation
  public Map<String, Object> info() {
    return Map.of(
      "uptime", System.currentTimeMillis(),
      "customMetric", 42
    )
  }

  @WriteOperation
  public String triggerAction(String param) {
    // perform a safe operation or delegate to a service
    return "action triggered with " + param
  }
}

Expose the endpoint in application properties

Actuator endpoints are not always exposed over HTTP by default. Add the management properties so the endpoint becomes reachable using the management context path.

management.endpoints.web.exposure.include = custom,health,info
management.endpoint.custom.enabled = true
# optional separate management port
management.server.port = 8081

Test the endpoint

Hit the endpoint with curl or your browser. If you changed the management port include it in the request.

curl localhost:8080/actuator/custom
# or when using a different management port
curl localhost:8081/actuator/custom

Secure the endpoint

Custom endpoints can leak secrets if you are careless. Protect them with Spring Security and restrict access to specific roles. Also enable HTTPS in production and avoid returning sensitive config values or credentials from the endpoint.

Quick security checklist

• Require authentication for actuator paths
• Authorize by role for write operations
• Keep responses minimal and scrub sensitive fields
• Use HTTPS for all management traffic

Best practices and tips

• Prefer @ReadOperation for safe queries and @WriteOperation for state changes
• Keep payloads small to avoid bloating monitoring systems
• Register the endpoint as a Spring bean so component scanning picks it up
• Use the management endpoints for monitoring and not as a general API surface

Custom Actuator endpoints are a tidy way to expose application specific metrics and operations for monitoring, troubleshooting and automation. They fit cleanly into the Spring Framework ecosystem and play well with monitoring stacks. Add them carefully and treat them like fragile secrets that must be earned rather than handed out to everyone who asks.