Spring Boot Actuator란?

Spring Boot Actuator란?

Spring Boot Actuator는 SPring boot 애플리케이션의 상태와 성능을 모니터링하고 관리할 수 있도록 다양한 엔트포인트를 제공하는 기능이다.

운영 환경에서 애플리케이션의 상태를 확인하고 성능을 점검하는 데 매우 유용하며, 헬스 체크(health check), 메트릭스(metrics), 환경 정보(env), 로그(loggers)등 애플리케이션의 핵심 정보를 손쉽게 조회할 수 있다.

 

Actuator는 개발/운영 단계에서 모두 활용할 수 있으며, 특히 Kubernetes, AWS, Docker, Cloud환경의 헬스 체크 및 모니터링 시스템에서 필수적으로 사용된다.

의존성 추가

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

이 두 가지 의존성을 추가하면 Actuator 기능을 바로 사용 가능하다.

 

Actuator 주요 엔드포인트

Spring Boot는 /actuator 하위에 다양한 모니터링 엔트포인트를 제공한다.

엔드 포인트	설명
/actuator/health	애플리케이션의 상태(UP/DOWN)를 확인
/actuator/metrics	CPU사용량, HTTP 요청 수 등 메트릭 정보 제공
/actuator/loggers	로깅 설정 조회 및 변경
/actuator/env	환경 별수 및 설정 정보 확인
/actuator/beans	애플리케이션 턴켁스트의 Bean 목록 조회
/actuator/threaddump	스레드 덤프 정보 제공
/actuator/httptrace	최근 HTTP 요청/응답 정보 추적(Spring 2.x에서 기본 비활성)

이외에도 Info, Mappings, Scheduler 등 여러 엔드포인트가 존재한다.

 

 

Actuator 엔드포인트 설정

 기본적으로 모든 엔드포인트가 활성화되어 있지 않을 수 있다.

application.properties를 통해 필요한 엔드포인트만 노출할 수 있다.

 

아래는 모든 엔드포인트 노출 + 헬스체크 상세 보기 활성화 예시이다:

spring.application.name=sample

server.port=8080

#모든 엔드포인트 노출 설정
management.endpoints.web.exposure.include=* 

#헬스 체크 엔드포인트 상세 정보 표시 설정
management.endpoint.health.show-details=always # 이 설정은 /actuator/health 엔드포인트에서 헬스 체크 정보를 항상 상세히 보여주도록 설정합니다. 기본적으로, 헬스 체크 엔드포인트는 요약된 상태 정보만 제공하며, 상세 정보는 노출되지 않습니다.

 

show-details 옵션 설명

옵션	설명Acu
never	절대 상세 정보 노출하지 않음
when_authorized	인증된 사용자에게만 상세 정보 제공
always	모든 사용자에게 상세 정보 제공

운영환경에서는 반드시 when_authorized를 추천한다.

 

보안 및 운영 시 주의사항

모든 엔드포인트 노출은 위험

운영 환경에서는 민담한 정보가 노출될 수 있으므로 필요한 엔드포인트만 선택적으로 노출해야 한다.

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

 

Actuator는 별도 포트에서 제공하는 것이 안전하다.

운영 환경에서는 Actuator를 외부로 노출하지 않도록 별도 포트를 사용하는 것이 일반적이다.

server.port=8080 # 애플리케이션 포트
management.server.port=19090 # Actuator 전용 포트

 

이렇게 하면 운영 API와 모니터링 정보를 분리하여 보안을 강화할 수 있다.

 

Spring Security로 엔트포인트 보호하기

Actuator의 민감한 정보를 보호하려면 Security 설정이 반드시 필요하다.

import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
import org.springframework.security.config.annotation.web.configuration.WebSecurityConfigurerAdapter;

@Configuration
@EnableWebSecurity
public class SecurityConfig extends WebSecurityConfigurerAdapter {
    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http.authorizeRequests()
            .antMatchers("/actuator/**").authenticated()
            .and()
            .httpBasic();
    }
}

 

이 설정은 

• /actuator/** 엔드포인트 접근 시 인증을 요구하고
• Basic Auth 방식으로 인증하도록 구성한다.

Spring Boot Actuator는 서비스 운영의 필수 도구로, 애플리케이션의 현재 상태를 신속하게 확인하고 문제를 빠르게 대응할 수 있도록 도와준다. 운영 환경에서는 반드시 보안 설정과 노출 번위를 조절하여 안정하게 사용해야 한다.

추후에는 Prometheus/Grafana와 연동해서 실시간 모니터링 시스템을 구충하는 방식도 많이 활용된다.