Skip to content

Spring Boot Actuator 모니터링

개요

애플리케이션을 운영 환경에 올리고 나면 "지금 살아 있나? 메모리는 어떤가? 요청은 몇 번 왔나?" 같은 확인이 필요해져요. Spring Boot는 Actuator라는 운영 지원 기능을 제공해서 이걸 자동으로 해결합니다. HTTP 엔드포인트나 JMX로 애플리케이션을 관리·모니터링할 수 있고, 상태(health), 감사(auditing), 지표(metrics) 수집까지 자동으로 적용할 수 있어요. 사용하려면 spring-boot-starter-actuator 의존성을 추가하면 됩니다.

핵심 개념

엔드포인트 기반 운영 정보

Actuator는 여러 내장 엔드포인트를 제공해요. 대표적으로 상태(health) 엔드포인트가 기본 애플리케이션 상태 정보를 보여주죠. HTTP로 노출할 때는 엔드포인트 ID 앞에 /actuator 접두사가 붙어요. 예를 들어 기본 상태 엔드포인트는 /actuator/health로 매핑됩니다.

주요 엔드포인트는 다음과 같아요.

  • health — 애플리케이션 상태 정보.
  • info — 임의의 애플리케이션 정보.
  • metrics — 애플리케이션이 기록한 지표 정보.
  • beans — 애플리케이션의 모든 스프링 빈 목록.
  • conditions — 설정·자동 설정 클래스에서 평가된 조건과 매칭 여부.
  • env — ConfigurableEnvironment의 프로퍼티(민감 정보는 정리됨).
  • configprops — 모든 @ConfigurationProperties 요약(정리됨).
  • loggers — 로거 구성 조회·수정.
  • mappings — 모든 @RequestMapping 경로 목록.
  • threaddump, heapdump — 스레드 덤프, 힙 덤프.
  • prometheus — Prometheus가 수집할 수 있는 형식의 지표(micrometer-registry-prometheus 필요).
  • shutdown — 애플리케이션 정상 종료(jar 패키징에서만 동작, 기본 비활성).

노출(exposure)과 접근(access)

기본적으로 HTTP와 JMX에서는 health 엔드포인트만 노출됩니다. 엔드포인트는 민감 정보를 포함할 수 있으므로 노출 대상을 신중히 정해야 해요. 노출 범위는 management.endpoints.web.exposure.include / exclude 프로퍼티로 제어합니다. *로 전체를 선택할 수 있고, YAML에서는 따옴표를 붙여야 해요.

management:
  endpoints:
    web:
      exposure:
        include: "health,info"

접근 수준은 management.endpoint.<id>.access로 정할 수 있어요. 기본적으로 shutdown과 heapdump를 제외한 모든 엔드포인트 접근이 제한 없음(unrestricted)입니다. 아니면 기본을 none으로 두고 엔드포인트별로 허용(opt-in)하는 방식도 있어요. 보안상 클래스패스에 Spring Security가 있고 별도 SecurityFilterChain 빈이 없으면 /health를 제외한 모든 Actuator가 자동 설정으로 보호됩니다.

Kubernetes 프로브

health에는 기본적으로 liveness와 readiness 상태 그룹이 자동 활성화돼요. 그래서 쿠버네티스 프로브에 /actuator/health/liveness, /actuator/health/readiness 경로를 바로 쓸 수 있습니다. 프로브가 필요 없으면 management.endpoint.health.probes.enabled로 끌 수 있고, 액추에이터가 별도 관리 포트에 있으면 메인 포트에도 경로를 추가하는 설정도 있어요.

실제 적용 (데이터스케쳐스 관점)

웹빌더 백엔드의 Spring Boot 서비스는 Actuator로 운영 상태를 관리합니다.

  • 헬스 체크 — /actuator/health로 서비스 생존과 외부 의존성(DB 등) 상태를 확인해요.
  • 쿠버네티스 프로브 — liveness/readiness 상태 그룹을 프로브로 연결해 배포·롤아웃 안정성을 높여요.
  • 지표·모니터링 — metrics와 prometheus 엔드포인트로 지표를 수집하고, 필요한 엔드포인트만 보안 네트워크 안에서 노출합니다.

더 알아보기