1. 들어가며
Spring Boot를 사용하다 보면 “애플리케이션이 잘 떠 있는지, DB는 연결됐는지, 메모리는 얼마나 쓰고 있는지” 같은 내부 상태를 확인하고 싶을 때가 많다. 이럴 때 유용한 도구가 바로 Spring Boot Actuator다. Actuator는 애플리케이션의 다양한 정보를 HTTP 엔드포인트로 노출해주며, 모니터링, 운영, 헬스체크, 메트릭 수집 같은 기능을 손쉽게 구현할 수 있도록 도와준다.
이전 부트캠프 프로젝트에서는 Actuator를 사용하지 않고 Node Exporter를 이용한 Metric 수집만 했었는데 이번 기회에 여러 MSA 프로젝트를 하면서 Actuator를 사용해볼 수 있었다.
2. Spring Boot Actuator란?
Spring Boot Actuator는 애플리케이션의 상태, 환경, 로그, 메트릭 등을 노출하는 기능을 제공하는 Spring Boot 서브 프로젝트다.
프로덕션 환경에서 중요한 모니터링, 관리 작업을 단 몇 줄의 설정으로 쉽게 처리할 수 있다.
대표적인 기능은 다음과 같다.
- /actuator/health : 시스템 헬스 상태
- /actuator/metrics : 메트릭 수치 (CPU 사용률, JVM 메모리 등)
- /actuator/env : 환경 변수
- /actuator/beans : 빈 등록 현황
- /actuator/loggers : 런타임 로그 레벨 변경
3. 의존성 추가 및 기본 설정
3.1 의존성 추가
dependencies {
implementation 'org.springframework.boot:spring-boot-starter-actuator'
}
Spring Boot 2 이상에서는 이 의존성만 추가하면 대부분의 엔드포인트가 기본으로 활성화된다.
3.2 application.yml 설정
management:
endpoints:
web:
exposure:
include: health,info,metrics,env
endpoint:
health:
show-details: always
기본적으로 actuator는 보안을 고려해 /health, /info 정도만 외부에 노출한다.
필요한 엔드포인트만 exposure.include로 열어주고, 상세 정보를 보고 싶다면 show-details 옵션을 활성화하면 된다.
4. 주요 엔드포인트 소개
4.1 /actuator/health
애플리케이션의 전반적인 상태를 보여준다.
기본 상태는 UP / DOWN 으로 표시되며, DB, Redis, Kafka 등 다양한 의존성의 상태도 함께 보여줄 수 있다.
{
"status": "UP",
"components": {
"db": {
"status": "UP",
"details": {
"database": "MySQL",
"validationQuery": "isValid()"
}
},
"diskSpace": {
"status": "UP"
}
}
}
4.2 /actuator/metrics
JVM, 스레드 수, GC, CPU 등 다양한 메트릭을 확인할 수 있다.
예: /actuator/metrics/jvm.memory.used, /actuator/metrics/system.cpu.usage
이 메트릭은 Prometheus, Micrometer와도 연동할 수 있어 관제 시스템과 통합할 때 매우 유용하다.
4.3 /actuator/env
현재 환경 변수, 시스템 프로퍼티, application.yml의 구성 내용을 확인할 수 있다.
운영 환경에서 중요 설정 값을 실시간으로 확인하고 싶을 때 사용한다.
4.4 /actuator/loggers
특정 클래스의 로그 레벨을 런타임 중에 변경할 수 있는 강력한 기능이다.
curl -X POST localhost:8080/actuator/loggers/com.example.service \
-H 'Content-Type: application/json' \
-d '{"configuredLevel": "DEBUG"}'
5. 보안 설정
Actuator는 민감한 정보를 다루므로, 운영 환경에서는 반드시 보안 설정을 추가해야 한다.
management:
endpoints:
web:
exposure:
include: "*"
endpoint:
health:
show-details: when-authorized
security:
enabled: true
spring:
security:
user:
name: admin
password: secret
기본 로그인 인증 외에도 Spring Security와 연동하여 권한별로 엔드포인트 접근을 제어할 수도 있다.
특히 /env, /beans, /loggers는 외부에 무분별하게 노출되면 보안 이슈가 생길 수 있으니 제한하는 게 좋다.
6. 커스터마이징 예시
커스텀 Health Indicator를 만들면 DB 이외의 서비스도 상태 체크가 가능하다.
@Component
public class CustomHealthIndicator implements HealthIndicator {
@Override
public Health health() {
boolean serverIsUp = checkExternalServer();
if (serverIsUp) {
return Health.up().withDetail("external-service", "Available").build();
}
return Health.down().withDetail("external-service", "Unavailable").build();
}
}이렇게 하면 /actuator/health에서 커스텀 상태도 함께 노출된다.
7. 마무리
Spring Boot Actuator는 애플리케이션의 상태를 진단하고 모니터링하는 데 매우 강력한 도구다.
특히 마이크로서비스 환경에서는 서비스별 헬스 체크, 메트릭 수집, 동적 로그 변경 같은 작업이 필요해지는데, Actuator는 그 모든 것을 손쉽게 지원한다. 게다가 Prometheus, Grafana 같은 외부 모니터링 도구와도 잘 연동되기 때문에 실제 운영 환경에서도 널리 사용되고 있다.
