자바 백엔드 입문 57편 — Spring Boot Actuator

이 글은 자바 백엔드 입문 시리즈 59편 중 57편이에요. 운영 환경 백엔드의 "눈" 역할 — Spring Boot Actuator.

Actuator란

Spring Boot Actuator = "운영 환경에서 백엔드 상태를 모니터링·관리하는 기능 모음". Spring Boot가 자동으로 제공하는 "운영 표준 도구 세트".

기본 제공 기능: - 헬스 체크 — "이 서버 살아 있나?" - 메트릭 — CPU·메모리·요청 수·응답 시간 - 로그 레벨 변경 — 운영 중에도 DEBUG로 변경 가능 - 환경 정보 — application.yml 설정값 조회 - 스레드 덤프 — 현재 도는 스레드 상태

비유 — Actuator = "자동차의 계기판 + 진단 단자". 엔진룸 안 들여다보지 않아도 상태 한눈에.

활성화 — 의존성 한 줄

implementation 'org.springframework.boot:spring-boot-starter-actuator'

추가하면 — 기본 엔드포인트들이 /actuator/* 경로로 자동 열려요.

기본 엔드포인트

기본은 /actuator/health·/actuator/info 두 개만 노출. 더 열려면 명시.

management:
  endpoints:
    web:
      exposure:
        include: health,info,metrics,loggers,env       # 노출할 엔드포인트
        # 또는 include: "*"  (전부, 운영 보안 주의)
  endpoint:
    health:
      show-details: when-authorized                     # 인증된 사용자에게만 상세

/actuator/health — 헬스 체크

가장 중요한 엔드포인트. 로드밸런서·Kubernetes의 "이 서버 살아 있나" 검사에 사용.

GET /actuator/health
{
  "status": "UP"
}

상세 정보 (인증·설정 후):

GET /actuator/health
{
  "status": "UP",
  "components": {
    "db": {
      "status": "UP",
      "details": {"database": "PostgreSQL", "validationQuery": "SELECT 1"}
    },
    "diskSpace": {"status": "UP", "details": {...}},
    "redis": {"status": "UP", "details": {"version": "7.0.0"}}
  }
}

자동으로 — DB 연결·디스크 공간·Redis·Kafka 같은 인프라 헬스 체크 포함. 인프라 한 곳 깨지면 status: DOWN.

/actuator/metrics — 메트릭

JVM·HTTP·DB 같은 메트릭 자동 수집.

GET /actuator/metrics
{
  "names": [
    "jvm.memory.used",
    "jvm.threads.live",
    "http.server.requests",
    "hikaricp.connections.active",
    ...
  ]
}

GET /actuator/metrics/http.server.requests
{
  "name": "http.server.requests",
  "measurements": [{"statistic": "COUNT", "value": 12345}, ...]
}

Prometheus 연동 — 모니터링 표준

운영에서는 메트릭을 외부 시스템(Prometheus·Datadog·New Relic)에 보내요. Micrometer + Prometheus 가 한국 회사 표준.

implementation 'io.micrometer:micrometer-registry-prometheus'

management:
  endpoints:
    web:
      exposure:
        include: health,info,prometheus
  metrics:
    distribution:
      percentiles-histogram:
        http.server.requests: true

/actuator/prometheus 엔드포인트가 자동 추가 — Prometheus가 주기적으로 스크래핑.

# HELP http_server_requests_seconds
# TYPE http_server_requests_seconds summary
http_server_requests_seconds_count{method="GET",uri="/api/orders"} 1234
http_server_requests_seconds_sum{method="GET",uri="/api/orders"} 56.78

이 데이터로 Grafana 대시보드 만들면 "실시간 모니터링" 완성.

/actuator/loggers — 동적 로그 레벨

운영 중에 "이 패키지만 DEBUG 켜자" 할 때.

# 현재 레벨 조회
GET /actuator/loggers/com.example.myshop

# 레벨 변경 (POST)
POST /actuator/loggers/com.example.myshop
Content-Type: application/json
{"configuredLevel": "DEBUG"}

서버 재시작 없이 즉시 적용. 트러블슈팅에 매우 유용. 다만 인증 필수 (아래).

커스텀 HealthIndicator

외부 시스템 헬스 체크를 직접 추가.

@Component
public class PaymentGatewayHealthIndicator implements HealthIndicator {

    private final PaymentGateway gateway;

    @Override
    public Health health() {
        try {
            if (gateway.ping()) {
                return Health.up().withDetail("latency", gateway.getLatency()).build();
            }
            return Health.down().withDetail("reason", "ping failed").build();
        } catch (Exception e) {
            return Health.down(e).build();
        }
    }
}

/actuator/health 응답에 자동 포함. 카카오페이·토스 같은 외부 의존성 상태도 한 곳에서.

/actuator/info — 빌드 정보

배포된 버전·커밋 해시 확인.

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

info:
  app:
    name: "@project.name@"
    version: "@project.version@"

GET /actuator/info
{
  "app": {"name": "myshop", "version": "1.0.0"},
  "build": {"time": "2026-05-17T10:30:00Z"},
  "git": {"commit": {"id": "a3f7b2c1"}}
}

배포 후 "어느 버전이 떴나" 즉시 확인. 운영 표준.

보안 — Actuator 보호 필수

/actuator/* 는 민감 정보 노출 위험 — env 에 비밀번호, heapdump 에 메모리 전체.

@Configuration
public class ActuatorSecurityConfig {

    @Bean
    @Order(1)
    public SecurityFilterChain actuatorSecurity(HttpSecurity http) throws Exception {
        http
            .securityMatcher(EndpointRequest.toAnyEndpoint())
            .authorizeHttpRequests(auth -> auth
                .requestMatchers(EndpointRequest.to("health", "info")).permitAll()
                .anyRequest().hasRole("ADMIN"))
            .httpBasic(Customizer.withDefaults());
        return http.build();
    }
}

health·info 만 공개 (로드밸런서가 인증 없이 호출), 나머지 = ADMIN만. 운영 필수 설정.

한 줄 정리 — Spring Boot Actuator = 운영 모니터링 표준 도구. 의존성 한 줄 + 엔드포인트 노출 설정. 헬스 체크·Prometheus 메트릭·동적 로그 레벨이 핵심. 운영 보안 필수.

시험 직전 한 번 더 — Actuator 입문자가 매번 헷갈리는 것

• Spring Boot Actuator = 운영 모니터링·관리 도구
• 의존성 = spring-boot-starter-actuator 한 줄
• 기본 엔드포인트 = /actuator/health·/actuator/info 노출
• 다른 엔드포인트 = management.endpoints.web.exposure.include 명시
• /actuator/health = 로드밸런서·Kubernetes 헬스 체크
• DB·Redis·Kafka 헬스 자동 포함
• 상세 = management.endpoint.health.show-details
• /actuator/metrics = JVM·HTTP·DB 메트릭
• 운영 표준 = Micrometer + Prometheus
• /actuator/prometheus 엔드포인트 자동 추가
• Prometheus 스크래핑 → Grafana 대시보드
• /actuator/loggers = 운영 중 로그 레벨 동적 변경
• 트러블슈팅 핵심 도구
• HealthIndicator = 커스텀 헬스 체크
• /actuator/info = 버전·커밋 해시
• 배포 후 "어느 버전?" 확인용
• 보안 필수 = env·heapdump 민감 정보 노출 위험
• health·info 공개 + 나머지 인증
• EndpointRequest.to(...) 로 SecurityFilterChain 분기
• 한국 회사 표준 = Prometheus + Grafana + AlertManager 조합
• Kubernetes liveness·readiness 프로브 = /actuator/health/liveness·/readiness

시리즈 다른 편 (앞뒤 글 모음)

이전 글:

• 52편 — @SpringBootTest 통합 테스트
• 53편 — MockMvc로 컨트롤러 테스트
• 54편 — Testcontainers 실제 DB 통합 테스트
• 55편 — @Scheduled로 작업 스케줄링
• 56편 — @Cacheable 캐싱

다음 글:

• 58편 — MapStruct DTO 매핑 자동화
• 59편 — Swagger Springdoc OpenAPI 문서