Best Practices for Spring Application Health Check and Actuator
- Introduction
- Spring Actuator Basics
- Best Practices
- Production Scenarios
- 5. Architecture Diagrams
- 6. Sample Code and Configuration
- 7. Key Takeaways
- Conclusion
- References
Introduction
Spring Actuator is a powerful tool for monitoring and managing Spring Boot applications. It provides production-ready features such as health checks, metrics, and tracing. Properly configuring and securing Actuator endpoints is crucial for ensuring the reliability and security of your application.
Key Benefits:
- Helps detect issues before they affect users.
- Provides an easy integration with monitoring systems like Prometheus, Grafana, and ELK stack.
- Customizable to expose only the needed endpoints.
Spring Actuator Basics
2.1 What is Spring Actuator?
Spring Actuator is a sub-project of the Spring Boot framework that provides production-ready features for monitoring and managing applications. It exposes various endpoints that can be used to check the health of the application, gather metrics, environment and perform other administrative tasks.
2.2 Key Features
Spring Boot Actuator offers various endpoints for different purposes:
| Endpoint | ||
|---|---|---|
| Health Checks | /actuator/health | Provides information about the health status of the application. |
| Metrics | /actuator/metrics | Exposes various metrics such as memory usage, active threads, HTTP requests, and more. |
| Info Endpoint | /actuator/info | Provides general or arbitrary information about the application. |
| Environment Endpoint | /actuator/env | Shows properties from the Environment. |
| Shutdown Endpoint | /actuator/shutdown | Allows for graceful shutdown of the application. |
2.3. Architecture Overview
The architecture of a Spring Boot application with Actuator enabled can be visualized as follows:
+---------------------+
| Spring Boot App |
| |
| +---------------+ |
| | Actuator | |
| +---------------+ |
| Health Checks |
| Metrics |
| Info Endpoint |
+---------------------+
|
v
+-----------------------------+
| Monitoring System (e.g., |
| Prometheus, Grafana, ELK) |
+-----------------------------+
sequenceDiagram
participant Client
participant Actuator Endpoint
participant Health Indicator(s)
Client->>Actuator Endpoint: GET /actuator/health
Actuator Endpoint->>Health Indicator(s): Evaluate Health
Health Indicator(s)-->>Actuator Endpoint: Return Status
Actuator Endpoint-->>Client: Respond with Health Status
Best Practices
3.1 Configuring Actuator Endpoints
Add the following dependency to your pom.xml:
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-actuator</artifactId>
</dependency>
Configure Actuator endpoints to expose only the necessary information. Use the management.endpoints.web.exposure.include property to specify which endpoints should be exposed.
Configure Actuator in application.properties or application.yml:
application.properties
management.endpoints.web.exposure.include=health,info,metrics
management.endpoint.health.show-details=always
application.yaml
management:
endpoints:
web:
exposure:
include: health, metrics, info
endpoint:
health:
show-details: always
3.2 Securing Actuator Endpoints
It is essential to secure your Actuator endpoints to prevent unauthorized access. Use Spring Security to restrict access to specific endpoints.
application.properties
management.endpoints.web.exposure.include=health,info
management.endpoints.web.base-path=/actuator
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.annotation.web.configuration.WebSecurityConfigurerAdapter;
@Configuration
public class SecurityConfig extends WebSecurityConfigurerAdapter {
@Override
protected void configure(HttpSecurity http) throws Exception {
http.authorizeRequests()
.antMatchers("/actuator/health").permitAll()
.antMatchers("/actuator/**").hasRole("ADMIN")
.and()
.httpBasic();
}
}
3.3 Custom Health Indicators
Spring Boot allows you to create custom health indicators for specific checks, such as database connectivity or third-party service availability.
Implement custom health indicators to monitor specific components of your application. Custom health indicators should extend the HealthIndicator interface.
CustomHealthIndicator
import org.springframework.boot.actuate.health.Health;
import org.springframework.boot.actuate.health.HealthIndicator;
import org.springframework.stereotype.Component;
@Component
public class CustomHealthIndicator implements HealthIndicator {
@Override
public Health health() {
// Perform custom health check
boolean isHealthy = checkCustomComponent();
if (isHealthy) {
return Health.up().withDetail("Custom Service", "Available").build();
} else {
return Health.down().withDetail("Custom Service", "Custom component is down").build();
}
}
private boolean checkCustomComponent() {
// Custom health check logic
return true;
}
}
Unit Test for CustomHealthIndicator
import static org.assertj.core.api.Assertions.assertThat;
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.boot.actuate.health.Health;
@SpringBootTest
public class CustomHealthIndicatorTest {
@Autowired
private CustomHealthIndicator customHealthIndicator;
@Test
public void healthIndicatorStatusShouldBeUp() {
Health health = customHealthIndicator.health();
assertThat(health.getStatus().getCode()).isEqualTo("UP");
}
}
3.4 Monitoring and Metrics
Enable and configure metrics to monitor the performance and health of your application. Use the micrometer library to expose metrics to various monitoring systems.
management:
metrics:
export:
prometheus:
enabled: true
3.5 Graceful Shutdown
Configure graceful shutdown to ensure that your application shuts down cleanly without interrupting ongoing requests.
server:
shutdown: graceful
Production Scenarios
4.1 Scenario 1: Database Health Check
Implement a health check for the database to ensure that the application can connect to the database.
import org.springframework.boot.actuate.health.Health;
import org.springframework.boot.actuate.health.HealthIndicator;
import org.springframework.stereotype.Component;
import javax.sql.DataSource;
import java.sql.Connection;
import java.sql.SQLException;
@Component
public class DatabaseHealthIndicator implements HealthIndicator {
private final DataSource dataSource;
public DatabaseHealthIndicator(DataSource dataSource) {
this.dataSource = dataSource;
}
@Override
public Health health() {
try (Connection connection = dataSource.getConnection()) {
if (connection.isValid(1000)) {
return Health.up().build();
} else {
return Health.down().withDetail("Error", "Database connection is not valid").build();
}
} catch (SQLException e) {
return Health.down(e).build();
}
}
}
4.2 Scenario 2: Custom Health Indicator
Implement a custom health indicator to monitor a specific external service.
import org.springframework.boot.actuate.health.Health;
import org.springframework.boot.actuate.health.HealthIndicator;
import org.springframework.stereotype.Component;
import org.springframework.web.client.RestTemplate;
@Component
public class ExternalServiceHealthIndicator implements HealthIndicator {
private final RestTemplate restTemplate;
public ExternalServiceHealthIndicator(RestTemplate restTemplate) {
this.restTemplate = restTemplate;
}
@Override
public Health health() {
try {
restTemplate.getForEntity("https://external-service.com/health", String.class);
return Health.up().build();
} catch (Exception e) {
return Health.down(e).withDetail("Error", "External service is down").build();
}
}
}
5. Architecture Diagrams
5.1 Component Diagram
+-------------------+ +-------------------+ +-------------------+
| Spring Boot App | | Spring Actuator | | Monitoring System |
+-------------------+ +-------------------+ +-------------------+
| | |
| (1) Health Check | |
|--------------------------->| |
| | (2) Metrics |
| |-------------------------->|
| | |
| (3) Info Endpoint | |
|<---------------------------| |
| | |
+-------------------+ +-------------------+ +-------------------+
| Spring Boot App | | Spring Actuator | | Monitoring System |
+-------------------+ +-------------------+ +-------------------+
5.2 Sequence Diagram
+-------------------+ +-------------------+ +-------------------+
| Client | | Spring Boot App | | Spring Actuator |
+-------------------+ +-------------------+ +-------------------+
| | |
| (1) Health Check Request | |
|--------------------------->| |
| | (2) Perform Health Check |
| |-------------------------->|
| | |
| (3) Health Check Response | |
|<---------------------------| |
| | |
+-------------------+ +-------------------+ +-------------------+
| Client | | Spring Boot App | | Spring Actuator |
+-------------------+ +-------------------+ +-------------------+
6. Sample Code and Configuration
6.1 Dependency Configuration
Add the necessary dependencies to your pom.xml file.
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-actuator</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-security</artifactId>
</dependency>
<dependency>
<groupId>io.micrometer</groupId>
<artifactId>micrometer-registry-prometheus</artifactId>
</dependency>
</dependencies>
6.2 Actuator Configuration
Configure Actuator endpoints in your application.yml file.
management:
endpoints:
web:
exposure:
include: health, metrics, info
metrics:
export:
prometheus:
enabled: true
server:
shutdown: graceful
6.3 Custom Health Indicator Implementation
Implement a custom health indicator to monitor a specific component.
import org.springframework.boot.actuate.health.Health;
import org.springframework.boot.actuate.health.HealthIndicator;
import org.springframework.stereotype.Component;
@Component
public class CustomHealthIndicator implements HealthIndicator {
@Override
public Health health() {
// Perform custom health check
boolean isHealthy = checkCustomComponent();
if (isHealthy) {
return Health.up().build();
} else {
return Health.down().withDetail("Error", "Custom component is down").build();
}
}
private boolean checkCustomComponent() {
// Custom health check logic
return true;
}
}
7. Key Takeaways
- Granular Health Checks: Implement separate health indicators for databases, message brokers, and other critical components.
- Monitoring Integration: Integrate with monitoring tools like Prometheus and Grafana for visualizing metrics and health data.
- Security Measures: Ensure only trusted sources can access sensitive health information.
- Detailed Health Information: Enable detailed health information only for internal access to protect sensitive data.
- Cluster-Aware Checks: In distributed environments, ensure health checks are cluster-aware and provide insights into individual instance health.
Conclusion
Spring Actuator is a powerful tool for monitoring and managing Spring Boot applications. By following best practices such as configuring and securing Actuator endpoints, implementing custom health indicators, and enabling monitoring and metrics, you can ensure the reliability and security of your application. This article provided a comprehensive guide to best practices for Spring application health checks and Actuator, including architecture diagrams, sample code, and configuration details.
References
- Spring Boot Actuator Documentation
- Spring Security Documentation
- [Micrometer Documentation](https://micrometer.io/docs