Skip to main content

One post tagged with "actuator"

View All Tags

Best Practices for Spring Application Health Check and Actuator

· 8 min read

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/healthProvides information about the health status of the application.
Metrics/actuator/metricsExposes various metrics such as memory usage, active threads, HTTP requests, and more.
Info Endpoint/actuator/infoProvides general or arbitrary information about the application.
Environment Endpoint/actuator/envShows properties from the Environment.
Shutdown Endpoint/actuator/shutdownAllows 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​