Spring Boot Actuator 상세 설정 분석

이 글은 Spring Boot Actuator의 management.* 트리를 어떻게 잡아야 운영 환경에서 안전하면서도 Kubernetes·Prometheus와 잘 맞물리는지 정리한다.

전체 모니터링 스택(Actuator → Prometheus → Grafana, Docker compose 구성)은 JHipster 모니터링 글에서 다룬다. 이 글은 그중 Actuator 한 축에만 집중한다.

1. 의존성

implementation "org.springframework.boot:spring-boot-starter-actuator"
implementation "io.micrometer:micrometer-registry-prometheus"
implementation "io.dropwizard.metrics:metrics-core"

• spring-boot-starter-actuator — Actuator 핵심.
• micrometer-registry-prometheus — /management/prometheus 형식의 메트릭 출력.
• metrics-core — 추가 메트릭 수집(JHipster jhimetrics 등이 의존).

2. 엔드포인트 노출 정책 — management.endpoints.web

management:
  endpoints:
    web:
      base-path: /management
      exposure:
        include:
          - health
          - info
          - prometheus
          - loggers
          - threaddump
          - caches
          - liquibase
          - configprops
          - env
          - jhimetrics
          - jhiopenapigroups
          - logfile

• base-path — 모든 Actuator 엔드포인트의 공통 prefix. 기본 /actuator를 /management로 바꾸는 게 JHipster 기본값이다.
• exposure.include — 외부에 노출할 엔드포인트 화이트리스트. 운영에선 꼭 필요한 것만.

3. 개별 엔드포인트 옵션 — management.endpoint.*

endpoints.web.*가 전역 정책이라면, endpoint.*는 엔드포인트별 세부 설정이다.

3.1 Health — 권한 + Kubernetes probes

management:
  endpoint:
    health:
      show-details: when_authorized   # 인증된 사용자만 details 노출
      roles: ROLE_ADMIN
      probes:
        enabled: true                 # liveness/readiness 활성화
      group:
        liveness:
          include: livenessState
        readiness:
          include: readinessState, db
  health:
    mail:
      enabled: false                  # 메일 서비스 헬스 체크 비활성화

• show-details: when_authorized — 익명 호출엔 UP/DOWN만, 인증된 관리자에겐 contributor별 상세까지.
• probes.enabled: true — Kubernetes가 /management/health/liveness·/readiness로 찌를 수 있게 한다.
• group.readiness.include: ..., db — DB 연결이 살아야 트래픽을 받겠다는 의미.

3.2 Info — Git 정보 + 환경 변수

management:
  endpoint:
    info:
      enabled: true
  info:
    git:
      mode: full
    env:
      enabled: true

git.mode: full은 빌드된 jar에 git.properties가 포함돼 있을 때 커밋 해시·브랜치·tag까지 노출한다.

3.3 Metrics — Prometheus 출력 + 히스토그램

management:
  metrics:
    export:
      prometheus:
        enabled: true
        step: 60                      # 60초 주기
    enable:
      http: true
      jvm: true
      logback: true
      process: true
      system: true
    distribution:
      percentiles-histogram:
        all: true
      percentiles:
        all: 0, 0.5, 0.75, 0.95, 0.99, 1.0
    tags:
      application: ${spring.application.name}
    web:
      server:
        request:
          autotime:
            enabled: true             # HTTP 요청 시간 자동 측정

• step: 60 — Prometheus가 그 이상 자주 스크래핑해도 값이 갱신되지 않는다. Prometheus scrape_interval과 맞추는 게 안전(보통 15s~60s).
• percentiles-histogram: true — Prometheus가 quantile을 서버 측에서 집계할 수 있게 한다. percentiles만 켜면 클라이언트(Spring) 쪽에서 계산해 push형 quantile로만 나온다 — 정확도와 집계 자유도가 다르다.

4. 보안 권장 패턴

• health.show-details만 익명 노출, 나머지 모든 엔드포인트는 ADMIN만.
• /management/prometheus는 사내망(Prometheus 서버)에서만 닿게 nginx 또는 SecurityFilterChain으로 제한.
• 외부에서 절대 보면 안 되는 것: env, configprops, loggers (런타임 로그레벨 변경), threaddump, heapdump.

management:
  endpoint:
    health:
      show-details: when_authorized
      roles: ROLE_ADMIN

5. 전체 구조 요약

management
├─ endpoints.web.*    # 노출 정책 (base-path, exposure include)
├─ endpoint.*         # 엔드포인트별 옵션 (health/info/metrics)
├─ metrics.*          # 메트릭 수집/내보내기/히스토그램/태그
├─ info.*             # Info 컨트리뷰터 (git, env)
├─ health.*           # Health 컨트리뷰터 활성화/비활성화
└─ server.*           # 별도 관리 포트(쓰면)

핵심:

• endpoints.web = “어떤 엔드포인트를 밖에 열까”
• endpoint.* = “그 엔드포인트가 안에서 어떻게 동작할까”
• metrics·info·health = 각 엔드포인트가 모으는 데이터의 세부 옵션

운영에선 exposure.include를 최소로 + health 외엔 ADMIN 권한 + /prometheus는 사내 IP에서만이 기본 골격이다.