Skip to main content

Chapter 1: Introduction to Spring Boot Actuator

Introduction​

Spring Boot Actuator adds monitoring and management capabilities to your application. It exposes HTTP endpoints that allow you to monitor health, metrics, and diagnose issues.

🎯 Chapter Objectives​

By the end of this chapter, you will know:

  1. ✅ What Actuator is and why to use it
  2. ✅ Add Actuator to your project
  3. ✅ Configure the endpoints
  4. ✅ Secure access to the endpoints

1. What is Actuator?​

Main Features​

Spring Boot Actuator provides:
├── Health Checks: Is the application running?
├── Metrics: Performance, memory usage, requests/second
├── Info: Application information (version, build)
├── Environment: Configuration and environment variables
├── Loggers: Change log levels on the fly
├── Thread Dump: Analyze threads
├── Heap Dump: Analyze memory
└── HTTP Trace: Request history

Use Cases​

1. Kubernetes: Liveness/readiness probes
2. Load Balancer: Check if the instance is healthy
3. Prometheus: Collect metrics
4. Debugging: Diagnose in production
5. DevOps: Automate deployments

2. Installation​

Maven Dependency​

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

Gradle​

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

3. Basic Configuration​

Enable Endpoints​

By default, only /actuator/health is exposed via HTTP.

# application.properties

# Expose all endpoints via HTTP
management.endpoints.web.exposure.include=*

# Or expose only certain endpoints
management.endpoints.web.exposure.include=health,info,metrics,prometheus

# Exclude sensitive endpoints
management.endpoints.web.exposure.exclude=env,beans

Verify Installation​

# Start the application
mvn spring-boot:run

# List all available endpoints
curl http://localhost:8080/actuator

Response:

{
  "_links": {
    "self": {"href": "http://localhost:8080/actuator"},
    "health": {"href": "http://localhost:8080/actuator/health"},
    "info": {"href": "http://localhost:8080/actuator/info"},
    "metrics": {"href": "http://localhost:8080/actuator/metrics"},
    "loggers": {"href": "http://localhost:8080/actuator/loggers"}
  }
}

4. Custom Port and Path​

Separate Management Port​

# Separate port for Actuator (recommended in production)
management.server.port=8081

# Application remains on 8080
# Actuator accessible on 8081

Advantages:

  • Isolate monitoring traffic
  • Configure a different firewall
  • Do not expose on the Internet

Customize Path​

# Change base path
management.endpoints.web.base-path=/admin/monitoring

# Endpoints will be under:
# /admin/monitoring/health
# /admin/monitoring/info
# etc.

5. Endpoint Security​

With Spring Security​

@Configuration
@EnableWebSecurity
public class SecurityConfig {

    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        http
            .authorizeHttpRequests(auth -> auth
                // Public endpoints
                .requestMatchers("/actuator/health").permitAll()
                .requestMatchers("/actuator/info").permitAll()
                
                // Endpoints for Prometheus (internal IP only)
                .requestMatchers("/actuator/prometheus").permitAll()
                
                // All other Actuator endpoints: ADMIN only
                .requestMatchers("/actuator/**").hasRole("ADMIN")
                
                // Rest of the application
                .anyRequest().authenticated()
            )
            .httpBasic(Customizer.withDefaults());
        
        return http.build();
    }
}

Disable Endpoints​

# Completely disable an endpoint
management.endpoint.shutdown.enabled=false
management.endpoint.env.enabled=false

# Disable all, then selectively enable
management.endpoints.enabled-by-default=false
management.endpoint.health.enabled=true
management.endpoint.info.enabled=true
management.endpoint.metrics.enabled=true

6. Essential Endpoints​

/actuator/health​

curl http://localhost:8080/actuator/health
{
  "status": "UP"
}

With details:

management.endpoint.health.show-details=always
{
  "status": "UP",
  "components": {
    "db": {
      "status": "UP",
      "details": {
        "database": "H2",
        "validationQuery": "isValid()"
      }
    },
    "diskSpace": {
      "status": "UP",
      "details": {
        "total": 499963174912,
        "free": 234567891234,
        "threshold": 10485760
      }
    }
  }
}

/actuator/info​

# Add custom info
info.app.name=My Application
info.app.version=1.0.0
info.app.description=Demo application
info.contact.email=support@example.com

# Git info (if spring-boot-maven-plugin configured)
management.info.git.mode=full
curl http://localhost:8080/actuator/info
{
  "app": {
    "name": "My Application",
    "version": "1.0.0",
    "description": "Demo application"
  },
  "contact": {
    "email": "support@example.com"
  }
}

/actuator/metrics​

# List all metrics
curl http://localhost:8080/actuator/metrics

# A specific metric
curl http://localhost:8080/actuator/metrics/jvm.memory.used
{
  "name": "jvm.memory.used",
  "measurements": [
    {"statistic": "VALUE", "value": 123456789}
  ],
  "availableTags": [
    {"tag": "area", "values": ["heap", "nonheap"]},
    {"tag": "id", "values": ["G1 Eden Space", "G1 Old Gen"]}
  ]
}
# ===== ACTUATOR =====

# Expose necessary endpoints
management.endpoints.web.exposure.include=health,info,metrics,prometheus,loggers

# Separate port (optional but recommended in prod)
# management.server.port=8081

# Health with details
management.endpoint.health.show-details=when_authorized
management.endpoint.health.show-components=when_authorized

# Custom info
info.app.name=@project.name@
info.app.version=@project.version@
info.app.encoding=@project.build.sourceEncoding@
info.java.version=@java.version@

# Enable build info
management.info.build.enabled=true
management.info.git.enabled=true
management.info.env.enabled=true

# Metrics
management.metrics.tags.application=${spring.application.name}

8. Summary​

Installation​

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

Minimal Configuration​

management.endpoints.web.exposure.include=health,info,metrics
management.endpoint.health.show-details=always

Key Endpoints​

EndpointUsage
/actuator/healthHealth status
/actuator/infoApplication information
/actuator/metricsPerformance metrics
/actuator/loggersLog levels
/actuator/envEnvironment variables

🎯 Next Step​

Let's explore all available endpoints in detail.

➡️ Chapter 2: The Endpoints

⬅️ Back to Module 11