본문으로 건너뛰기
Advertisement

2.5 Actuator와 운영 모니터링

실무에서는 애플리케이션이 실행 중인 상태(Health) 와 메트릭(Metrics) 을 외부에서 확인할 수 있어야 합니다. 스프링 부트 Actuator는 이러한 운영(Production) 환경에 필요한 엔드포인트를 표준화하여 제공합니다.

작성 기준: Spring Boot 3.2.x, spring-boot-starter-actuator

1. Actuator란?​

Actuator는 스프링 부트 애플리케이션의 상태 조회·모니터링·관리를 위한 HTTP(또는 JMX) 엔드포인트 모음입니다. 로드밸런서 헬스체크, APM 연동, Kubernetes 프로브 등에서 활용됩니다.

2. 의존성 추가 및 기본 설정​

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-actuator'
}

application.yml에서 노출할 엔드포인트를 제한하는 것이 보안상 권장됩니다. 운영 환경에서는 health와 info만 노출하고, 나머지는 내부망에서만 사용하는 경우가 많습니다.

management:
  endpoints:
    web:
      exposure:
        include: health,info,metrics   # 노출할 엔드포인트만 명시
      base-path: /actuator
  endpoint:
    health:
      show-details: when-authorized    # 인증된 경우에만 상세 정보 (운영 권장)

3. 주요 엔드포인트​

엔드포인트설명활용 예
/actuator/health애플리케이션·DB·디스크 등 상태로드밸런서 헬스체크, K8s liveness/readiness
/actuator/info빌드 정보, 버전 등 (직접 설정)배포 버전 확인
/actuator/metricsJVM, HTTP, DB 풀 등 메트릭 목록APM, Grafana 연동
/actuator/metrics/{name}특정 메트릭 값 조회세부 모니터링

Health 상세 예시​

show-details: always로 두면 다음처럼 상세 상태를 볼 수 있습니다.

{
  "status": "UP",
  "components": {
    "db": {
      "status": "UP",
      "details": {
        "database": "MySQL",
        "validationQuery": "isValid()"
      }
    },
    "diskSpace": {
      "status": "UP",
      "details": {
        "total": 500000000000,
        "free": 250000000000,
        "threshold": 10485760
      }
    }
  }
}

4. 커스텀 Health Indicator​

비즈니스에서 중요한 외부 시스템(결제 게이트웨이, 캐시 서버 등)의 상태를 Health에 포함할 수 있습니다.

@Component
public class CustomPaymentHealthIndicator implements HealthIndicator {

    private final PaymentGatewayClient paymentClient;

    @Override
    public Health health() {
        try {
            boolean reachable = paymentClient.ping();
            return reachable
                ? Health.up().withDetail("payment", "available").build()
                : Health.down().withDetail("payment", "unreachable").build();
        } catch (Exception e) {
            return Health.down(e).build();
        }
    }
}

5. Graceful Shutdown (우아한 종료)​

운영 환경에서 배포·스케일인 시 진행 중인 요청을 마친 뒤 종료하려면 Graceful Shutdown을 활성화합니다.

server:
  shutdown: graceful

spring:
  lifecycle:
    timeout-per-shutdown-phase: 30s

이렇게 설정하면 스프링 부트가 종료 시 새 요청은 받지 않고, 기존 요청이 timeout-per-shutdown-phase 이내에 끝날 때까지 대기한 뒤 프로세스를 종료합니다.

6. Info 엔드포인트에 빌드 정보 넣기​

build.gradle에 다음을 추가한 뒤 빌드하면 git.branch, git.commit.id 등이 /actuator/info에 노출됩니다.

springBoot {
    buildInfo()
}
팁

운영(prod)에서는 management.endpoints.web.exposure.include를 최소한으로 두고, /actuator 경로를 내부망·VPN으로만 접근 가능하게 제한하는 것이 좋습니다. 필요 시 Spring Security로 Actuator 경로에 인증을 걸 수 있습니다.

Advertisement
Advertisement