Spring Boot Actuator 엔드포인트가 작동하지 않는 문제 해결

개요

---

개발 프로젝트를 진행하다 보면, 애플리케이션의 상태를 모니터링하고 진단하는 것이 중요하다. 특히 Spring Boot Actuator는 이러한 기능을 제공하여 매우 유용하다.

 

하지만 Actuator 엔드포인트가 예상대로 작동하지 않는 문제를 몇 차례 경험했다. 이런 문제를 해결하고, 다른 개발자들도 같은 문제를 겪을 때 쉽게 해결할 수 있도록 글을 정리하게 되었다.

 

Actuator란 무엇인가?

---

Spring Boot Actuator는 애플리케이션의 상태를 모니터링할 수 있는 여러 엔드포인트를 제공하는 모듈이다. 이를 통해 애플리케이션의 헬스 체크(health), 메트릭(metrics), 로그(logs) 등을 쉽게 확인할 수 있다. Actuator는 기본적으로 여러 엔드포인트를 제공하지만, 때때로 이 엔드포인트들이 작동하지 않을 수 있다.

 

좀 더 자세한 정보는 아래 포스트를 통해 알 수 있다.

2023.02.14 - [Java] - [Java] Spring Boot Actuator

[Java] Spring Boot Actuator

 

Actuator 엔드포인트가 작동하지 않는 주요 원인

---

Actuator 엔드포인트가 작동하지 않는 경우, 여러 가지 원인이 있을 수 있다. 가장 흔한 문제는 다음과 같다:

의존성 누락

Actuator 기능을 사용하려면 spring-boot-starter-actuator 의존성을 추가해야 한다. 이 의존성이 누락되었을 경우, 엔드포인트가 작동하지 않는다.

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

---

설정 문제

Actuator는 기본적으로 일부 엔드포인트만 활성화되어 있다. application.properties 또는 application.yml 파일에서 추가적인 설정을 해야 한다.

management.endpoints.web.exposure.include=*

 

위 설정은 모든 Actuator 엔드포인트를 활성화하는 설정이다. 특정 엔드포인트만 활성화하고 싶다면, health, metrics와 같은 엔드포인트만 지정할 수도 있다.

management.endpoints.web.exposure.include=health,metrics

---

보안 설정 문제

Actuator 엔드포인트는 기본적으로 보안이 적용된다. management.security.enabled=false로 설정하면 인증 없이 엔드포인트에 접근할 수 있지만, 이는 프로덕션 환경에서는 권장되지 않는다. 보안을 유지하면서 엔드포인트를 접근하려면 Spring Security와 함께 설정을 해야 한다.

 

Actuator 엔드포인트 활성화 방법

---

Actuator 엔드포인트가 제대로 작동하도록 하기 위해서는 올바른 설정과 보안 구성이 필수적이다. 다음은 Actuator 엔드포인트를 활성화하고, 특정 엔드포인트에 접근할 수 있는 방법을 설명한 코드이다.

 

먼저 application.yml 파일에서 필요한 엔드포인트를 활성화하자:

management:
  endpoints:
    web:
      exposure:
        include: health,info

 

이제 헬스 체크와 정보 엔드포인트만 활성화된 것을 볼 수 있다. 그 후, 보안 설정을 추가해 보자. Spring Security와 함께 사용할 경우, 인증된 사용자만 Actuator 엔드포인트에 접근할 수 있도록 설정할 수 있다.

@Configuration
public class SecurityConfig extends WebSecurityConfigurerAdapter {

    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http
            .authorizeRequests()
            .antMatchers("/actuator/**").hasRole("ADMIN")
            .anyRequest().authenticated()
            .and()
            .httpBasic();
    }
}

 

위 코드에서는 /actuator/** 경로로 들어오는 모든 요청을 ADMIN 권한을 가진 사용자만 접근할 수 있도록 설정하였다. 이와 같이 보안 설정을 적용하면, Actuator 엔드포인트가 더 안전하게 관리될 수 있다.

 

정리

---

Spring Boot Actuator는 애플리케이션의 상태를 실시간으로 모니터링할 수 있는 매우 유용한 도구이다. 하지만 기본 설정으로는 모든 엔드포인트가 활성화되지 않거나 보안 설정이 누락되어 엔드포인트가 작동하지 않는 경우가 있다.

 

이 글에서는 Actuator 엔드포인트가 작동하지 않는 문제의 원인과 해결 방법을 정리하였다. 올바른 의존성과 설정을 적용하면, Actuator 엔드포인트를 효과적으로 사용할 수 있을 것 같다.