Spring Boot Actuator 운영 가이드 — Health·Metrics·Prometheus·보안 설정

Spring Boot 서비스가 “프로세스는 살아 있지만 요청을 처리하지 못하는 상태”가 되면 단순 포트 체크만으로는 장애를 찾기 어렵습니다. Actuator는 Health, Metrics, Loggers, Thread Dump 등 운영 정보를 표준 Endpoint로 제공합니다.

하지만 /actuator/**를 전부 외부에 공개하면 환경 설정, 매핑, Heap Dump 같은 민감 정보가 노출될 수 있습니다. 운영의 핵심은 많이 여는 것이 아니라 필요한 Endpoint만 노출하고 네트워크와 인증으로 보호하는 것입니다.

핵심 요약

• Actuator는 spring-boot-starter-actuator로 활성화합니다.
• 기본 HTTP 노출은 제한적이며 필요한 Endpoint만 명시적으로 추가합니다.
• Liveness는 재시작이 필요한 상태, Readiness는 트래픽 수신 가능 상태를 판단합니다.
• Prometheus Endpoint는 Micrometer Registry 의존성과 노출 설정이 필요합니다.
• env, configprops, heapdump, loggers는 공개 범위를 특히 주의합니다.

1. 의존성과 기본 설정

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-actuator'
    runtimeOnly 'io.micrometer:micrometer-registry-prometheus'
}

management:
  endpoints:
    web:
      exposure:
        include: health,info,prometheus
  endpoint:
    health:
      show-details: when_authorized
      probes:
        enabled: true

Spring Boot 버전에 따라 속성명과 기본 동작이 달라질 수 있으므로 사용하는 버전의 Reference를 확인합니다. YAML에서 *는 특별한 의미가 있으므로 전체 노출 시에도 따옴표가 필요하지만, 운영에서는 전체 노출을 기본값으로 삼지 않는 편이 안전합니다.

2. Liveness와 Readiness를 분리하라

Probe질문실패 시

Liveness	애플리케이션이 복구 불가능하게 멈췄나	컨테이너 재시작
Readiness	현재 요청을 받을 준비가 됐나	Service Endpoint에서 제외
Startup	초기 기동이 아직 진행 중인가	기동 완료까지 다른 Probe 지연

DB가 잠시 느리다고 Liveness까지 실패시키면 모든 Pod가 재시작되어 장애가 커질 수 있습니다. 외부 의존성은 보통 Readiness에 반영하고, Liveness에는 애플리케이션 자체가 교착·고장 난 경우만 포함합니다.

3. Prometheus 연동

scrape_configs:
  - job_name: spring-app
    metrics_path: /actuator/prometheus
    static_configs:
      - targets: ['app:8080']

Micrometer는 JVM, HTTP Server, Connection Pool 등 다양한 Meter를 제공합니다. 알림은 단일 순간값보다 Rate와 분위수를 활용합니다.

• HTTP 요청 수, 오류율, P95·P99 지연시간
• JVM Heap 사용률과 GC Pause
• Tomcat/Netty Thread와 Queue
• DB Connection Pool Active·Pending
• 업무 지표: 주문 실패, 메시지 지연, 재시도 수

4. 보안 설정 원칙

1. Management Port를 서비스 포트와 분리하고 내부 네트워크에만 바인딩합니다.
2. Ingress·Load Balancer에서 Actuator 경로를 공용으로 노출하지 않습니다.
3. Spring Security의 별도 SecurityFilterChain으로 역할 기반 접근을 설정합니다.
4. Health 상세 정보는 인증된 운영자에게만 보여줍니다.
5. Heap Dump와 Logfile은 개인정보·토큰 포함 가능성을 고려해 별도 절차로 수집합니다.

사용자가 직접 SecurityFilterChain Bean을 정의하면 Actuator 보안 Auto-configuration이 물러날 수 있습니다. Actuator용 Chain과 애플리케이션용 Chain을 모두 명시적으로 검토해야 합니다.

5. Custom Metric 예시

@Component
class OrderMetrics(private val registry: MeterRegistry) {
    fun recordFailure(reason: String) {
        registry.counter("orders.failed", "reason", reason).increment()
    }
}

태그 값에 고객 ID, 주문 번호, URL 전체처럼 종류가 계속 늘어나는 값을 넣으면 Cardinality가 폭증합니다. 태그는 상태 코드, 고정된 오류 유형, 기능명처럼 제한된 집합으로 설계합니다.

6. 운영 체크리스트

• health, info, prometheus만 기본 노출합니다.
• Probe의 Timeout·Failure Threshold를 실제 기동·응답시간에 맞춥니다.
• Actuator 접근 로그와 실패 인증을 모니터링합니다.
• 알림에는 증상, 영향, 확인 대시보드, Runbook 링크를 포함합니다.
• 배포 전 인증 없이 민감 Endpoint에 접근할 수 없는지 테스트합니다.

공식 자료

• Spring Boot Production-ready Features
• Spring Boot Actuator Endpoints
• Spring Boot Metrics

정리: Actuator는 단순한 Health URL이 아니라 운영 관측의 입구입니다. Liveness와 Readiness를 분리하고, 필요한 지표만 인증된 내부 경로에 노출해야 모니터링과 보안을 함께 만족할 수 있습니다.