Chapter 2: Actuator Endpoints

Introduction

Actuator provides many ready-to-use endpoints. This chapter explores the most useful ones and shows you how to create your own.

🎯 Chapter Objectives

By the end of this chapter, you will know how to:

✅ Use all native endpoints
✅ Understand when to use each endpoint
✅ Create custom endpoints
✅ Filter and format responses

1. List of Endpoints

Basic Endpoints

Endpoint	Description	Sensitive?
`/actuator`	Lists all endpoints	No
`/actuator/health`	Health status	No
`/actuator/info`	Application information	No

Analysis Endpoints

Endpoint	Description	Sensitive?
`/actuator/beans`	Lists all Spring beans	Yes
`/actuator/conditions`	Auto-configuration conditions	Yes
`/actuator/configprops`	Configuration properties	Yes
`/actuator/env`	Environment variables	Yes
`/actuator/mappings`	All @RequestMapping	Yes

Metrics Endpoints

Endpoint	Description	Sensitive?
`/actuator/metrics`	Lists metrics	No
`/actuator/metrics/\{name\}`	A specific metric	No
`/actuator/prometheus`	Prometheus format	No

Debugging Endpoints

Endpoint	Description	Sensitive?
`/actuator/loggers`	Log levels	Yes
`/actuator/threaddump`	Thread dump	Yes
`/actuator/heapdump`	Memory dump (file)	Yes
`/actuator/httptrace`	HTTP history	Yes

Action Endpoints

Endpoint	Description	Sensitive?
`/actuator/shutdown`	Stop the application	Yes
`/actuator/refresh`	Refresh config	Yes

2. Endpoints in Detail

/actuator/beans

Lists all Spring beans in the application:

curl http://localhost:8080/actuator/beans

{
  "contexts": {
    "application": {
      "beans": {
        "userService": {
          "aliases": [],
          "scope": "singleton",
          "type": "com.example.service.UserService",
          "dependencies": ["userRepository"]
        },
        "userController": {
          "aliases": [],
          "scope": "singleton",
          "type": "com.example.controller.UserController",
          "dependencies": ["userService"]
        }
      }
    }
  }
}

Utility: Debug dependency injection.

/actuator/conditions

Shows why auto-configurations were applied or not:

curl http://localhost:8080/actuator/conditions

{
  "contexts": {
    "application": {
      "positiveMatches": {
        "DataSourceAutoConfiguration": [{
          "condition": "OnClassCondition",
          "message": "@ConditionalOnClass found required classes 'javax.sql.DataSource'"
        }]
      },
      "negativeMatches": {
        "RedisAutoConfiguration": {
          "notMatched": [{
            "condition": "OnClassCondition",
            "message": "@ConditionalOnClass did not find required class 'org.springframework.data.redis.core.RedisOperations'"
          }]
        }
      }
    }
  }
}

Utility: Understand why a feature is enabled/disabled.

/actuator/env

Displays all configuration sources:

curl http://localhost:8080/actuator/env

{
  "activeProfiles": ["dev"],
  "propertySources": [
    {
      "name": "systemProperties",
      "properties": {
        "java.version": {"value": "17.0.1"}
      }
    },
    {
      "name": "applicationConfig: [classpath:/application.properties]",
      "properties": {
        "spring.datasource.url": {"value": "jdbc:h2:mem:testdb"}
      }
    }
  ]
}

A specific property:

curl http://localhost:8080/actuator/env/spring.datasource.url

/actuator/mappings

Lists all HTTP endpoints of the application:

curl http://localhost:8080/actuator/mappings

{
  "contexts": {
    "application": {
      "mappings": {
        "dispatcherServlets": {
          "dispatcherServlet": [
            {
              "handler": "com.example.controller.UserController#getAll()",
              "predicate": "{GET /api/users}",
              "details": {
                "requestMappingConditions": {
                  "methods": ["GET"],
                  "patterns": ["/api/users"]
                }
              }
            }
          ]
        }
      }
    }
  }
}

Utility: See all available endpoints.

/actuator/loggers

View and modify log levels on the fly:

# View all loggers
curl http://localhost:8080/actuator/loggers

# A specific logger
curl http://localhost:8080/actuator/loggers/com.example.service

{
  "configuredLevel": null,
  "effectiveLevel": "DEBUG"
}

Modify a level on the fly (POST):

curl -X POST http://localhost:8080/actuator/loggers/com.example.service \
  -H "Content-Type: application/json" \
  -d '{"configuredLevel": "DEBUG"}'

Utility: Enable DEBUG in production without restarting!

/actuator/threaddump

Displays the state of all threads:

curl http://localhost:8080/actuator/threaddump

{
  "threads": [
    {
      "threadName": "http-nio-8080-exec-1",
      "threadId": 23,
      "blockedTime": -1,
      "blockedCount": 0,
      "waitedTime": -1,
      "waitedCount": 2,
      "lockName": null,
      "threadState": "RUNNABLE",
      "stackTrace": [
        {
          "className": "java.net.SocketInputStream",
          "methodName": "socketRead0",
          "lineNumber": -2,
          "nativeMethod": true
        }
      ]
    }
  ]
}

Utility: Detect deadlocks, blocked threads.

/actuator/heapdump

Generates a heap dump file (warning: heavy!):

curl -O http://localhost:8080/actuator/heapdump
# Generates a heapdump file that you can analyze with VisualVM or MAT

Utility: Analyze memory leaks.

/actuator/shutdown (Dangerous!)

Stops the application gracefully:

# Must be explicitly enabled
management.endpoint.shutdown.enabled=true

curl -X POST http://localhost:8080/actuator/shutdown

{
  "message": "Shutting down, bye..."
}

⚠️ Must be secured absolutely!

3. Custom Endpoints

Create a Simple Endpoint

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 Map<String, Object> customInfo() {
        return Map.of(
            "status", "operational",
            "timestamp", LocalDateTime.now(),
            "version", "1.0.0"
        );
    }
}

curl http://localhost:8080/actuator/custom

{
  "status": "operational",
  "timestamp": "2024-01-15T10:30:00",
  "version": "1.0.0"
}

Endpoint with Parameters

@Component
@Endpoint(id = "features")
public class FeaturesEndpoint {

    private final Map<String, Boolean> features = new ConcurrentHashMap<>();

    @ReadOperation
    public Map<String, Boolean> getAllFeatures() {
        return features;
    }

    @ReadOperation
    public Boolean getFeature(@Selector String name) {
        return features.getOrDefault(name, false);
    }

    @WriteOperation
    public void setFeature(@Selector String name, boolean enabled) {
        features.put(name, enabled);
    }

    @DeleteOperation
    public void deleteFeature(@Selector String name) {
        features.remove(name);
    }
}

# Read all features
curl http://localhost:8080/actuator/features

# Read a feature
curl http://localhost:8080/actuator/features/dark-mode

# Enable a feature
curl -X POST "http://localhost:8080/actuator/features/dark-mode?enabled=true"

# Delete a feature
curl -X DELETE http://localhost:8080/actuator/features/dark-mode

Endpoint for Business Statistics

@Component
@Endpoint(id = "business-stats")
@RequiredArgsConstructor
public class BusinessStatsEndpoint {

    private final OrderRepository orderRepository;
    private final UserRepository userRepository;

    @ReadOperation
    public Map<String, Object> getStats() {
        return Map.of(
            "totalUsers", userRepository.count(),
            "totalOrders", orderRepository.count(),
            "ordersToday", orderRepository.countByCreatedAtAfter(LocalDate.now().atStartOfDay()),
            "revenue", orderRepository.sumTotalAmount()
        );
    }
}

4. Web Endpoints vs JMX

Web Exposure (HTTP)

# Expose via HTTP
management.endpoints.web.exposure.include=health,info,metrics

JMX Exposure

# Expose via JMX (for JConsole, VisualVM)
management.endpoints.jmx.exposure.include=*

# Disable JMX if not used
spring.jmx.enabled=false

5. Summary

Recommended Endpoints in Production

Endpoint	Exposure	Usage
`/health`	Public	Load balancer, K8s
`/info`	Public	Version, build
`/metrics`	Internal	Prometheus
`/prometheus`	Internal	Scraping
`/loggers`	Admin	Hot debugging

Endpoints to Secure

/actuator/env         → Expose secrets!
/actuator/heapdump    → Sensitive data!
/actuator/shutdown    → Stop the app!
/actuator/beans       → Internal architecture

Create an Endpoint

@Component
@Endpoint(id = "my-endpoint")
public class MyEndpoint {
    
    @ReadOperation    // GET
    public Data read() { }
    
    @WriteOperation   // POST
    public void write() { }
    
    @DeleteOperation  // DELETE
    public void delete() { }
}

🎯 Next Step

Endpoints are great, but how to measure performance? Let's move on to metrics!

➡️ Chapter 3: Metrics with Micrometer

⬅️ Back to Module 11

Introduction​

🎯 Chapter Objectives​

1. List of Endpoints​

Basic Endpoints​

Analysis Endpoints​

Metrics Endpoints​

Debugging Endpoints​

Action Endpoints​

2. Endpoints in Detail​

/actuator/beans​

/actuator/conditions​

/actuator/env​

/actuator/mappings​

/actuator/loggers​

/actuator/threaddump​

/actuator/heapdump​

/actuator/shutdown (Dangerous!)​

3. Custom Endpoints​

Create a Simple Endpoint​

Endpoint with Parameters​

Endpoint for Business Statistics​

4. Web Endpoints vs JMX​

Web Exposure (HTTP)​

JMX Exposure​

5. Summary​

Recommended Endpoints in Production​

Endpoints to Secure​

Create an Endpoint​

🎯 Next Step​