Spring Boot Actuator - 애플리케이션 모니터링 가이드

Source: Dev.to

설정

Gradle

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

Maven

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>

엔드포인트

상세 정보 표시 및 빌드 정보

# 상세 정보 항상 표시
management.endpoint.health.show-details=always
# 또는 인증된 사용자에게만 표시
management.endpoint.health.show-details=when-authorized

# 빌드 정보 포함
management.info.build.enabled=true
management.info.git.enabled=true

# 커스텀 정보
info.app.name=My Application
info.app.version=1.0.0
info.app.description=Spring Boot Application

Metrics API 예시

전체 메트릭 이름 목록

GET /actuator/metrics

{
  "names": [
    "jvm.memory.used",
    "jvm.gc.pause",
    "http.server.requests",
    "system.cpu.usage"
    // ...
  ]
}

개별 메트릭 조회 (예: jvm.memory.used)

GET /actuator/metrics/jvm.memory.used

{
  "name": "jvm.memory.used",
  "measurements": [
    {
      "statistic": "VALUE",
      "value": 123456789
    }
  ],
  "availableTags": [
    {
      "tag": "area",
      "values": ["heap", "nonheap"]
    }
  ]
}

Prometheus 연동

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

management.endpoints.web.exposure.include=health,info,prometheus
management.metrics.export.prometheus.enabled=true

# prometheus.yml (scrape configuration)
scrape_configs:
  - job_name: 'spring-boot-app'
    metrics_path: '/actuator/prometheus'
    static_configs:
      - targets: ['localhost:8080']

Prometheus를 데이터 소스로 추가하고, Grafana 대시보드(예: ID 4701 또는 12900)를 임포트하면 시각적인 모니터링이 가능합니다.

보안 설정

# 기본적으로 health와 info만 노출
management.endpoints.web.exposure.include=health,info

# 특정 엔드포인트 제외
management.endpoints.web.exposure.exclude=env,beans

# 관리 포트 분리
management.server.port=9090

# 관리 경로 변경
management.endpoints.web.base-path=/management

@Configuration
public class ActuatorSecurityConfig {

    @Bean
    public SecurityFilterChain actuatorSecurityFilterChain(HttpSecurity http) throws Exception {
        http
            .securityMatcher("/actuator/**")
            .authorizeHttpRequests(auth -> auth
                .requestMatchers("/actuator/health", "/actuator/info").permitAll()
                .anyRequest().hasRole("ADMIN")
            )
            .httpBasic(Customizer.withDefaults());

        return http.build();
    }
}

커스텀 HealthIndicator

@Component
public class DatabaseHealthIndicator implements HealthIndicator {

    @Autowired
    private DataSource dataSource;

    @Override
    public Health health() {
        try (Connection conn = dataSource.getConnection()) {
            if (conn.isValid(1)) {
                return Health.up()
                    .withDetail("database", "Available")
                    .build();
            }
        } catch (SQLException e) {
            return Health.down()
                .withDetail("database", "Not Available")
                .withException(e)
                .build();
        }
        return Health.down().build();
    }
}

Micrometer를 이용한 서비스 메트릭

@Service
public class OrderService {

    private final Counter orderCounter;
    private final Timer orderTimer;

    public OrderService(MeterRegistry registry) {
        this.orderCounter = registry.counter("orders.created");
        this.orderTimer = registry.timer("orders.processing.time");
    }

    public void createOrder(Order order) {
        orderTimer.record(() -> {
            // 주문 처리 로직
            orderCounter.increment();
        });
    }
}

참고 자료

• Spring Boot Actuator 공식 문서
• Micrometer 문서

Spring Boot Actuator는 애플리케이션 운영에 필수적인 도구이며, 기본 제공 엔드포인트만으로도 충분한 모니터링이 가능합니다. Prometheus와 Grafana를 연동하면 시각적인 대시보드를 구축할 수 있으며, 운영 환경에서는 반드시 적절한 접근 제어를 설정해야 합니다.