[LG CNS AM Inspire Camp] 25. Spring Boot Actuator, 서비스 상태 모니터링

chillmyh 2025. 5. 14. 23:09

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 같은 외부 모니터링 도구와도 잘 연동되기 때문에 실제 운영 환경에서도 널리 사용되고 있다.