4. Spring Boot Actuator & Micrometer: 애플리케이션 메트릭 수집 실습

지금까지 모니터링의 이론과 프로메테우스의 동작 방식을 배웠습니다. 이제 가장 중요한 "그래서 내 스프링 부트 애플리케이션은 어떻게 모니터링하는데?" 라는 질문에 답할 차례입니다. 이 장에서는 Spring Boot Actuator와 Micrometer를 사용하여 실제 애플리케이션의 내부 동작을 메트릭으로 노출하는 방법을 실습합니다.

핵심 플레이어: Actuator와 Micrometer

스프링 부트 환경에서 메트릭을 수집할 때, 이 두 가지 라이브러리는 환상의 콤비로 동작합니다.

• Spring Boot Actuator: 스프링 부트 애플리케이션의 운영(production-ready) 기능을 제공하는 도구입니다. 단순히 메트릭뿐만 아니라, 애플리케이션의 상태(health), 정보(info), 환경변수(env) 등을 HTTP 엔드포인트로 노출해줍니다.
• Micrometer: 애플리케이션 메트릭 수집을 위한 '외관(Facade)' 라이브러리입니다. 마치 로깅 세계의 SLF4J처럼, Micrometer는 표준화된 API를 제공하고, 개발자는 이 API를 사용하여 메트릭을 기록합니다. 그러면 Micrometer가 실제 모니터링 시스템(Prometheus, Datadog, New Relic 등)에 맞는 포맷으로 데이터를 변환하여 전달해줍니다.

1단계: 프로젝트 설정하기

먼저, build.gradle 파일에 Actuator와 프로메테우스용 Micrometer Registry 의존성을 추가합니다.

// build.gradle.kts
dependencies {
    // ... 다른 의존성들
    implementation("org.springframework.boot:spring-boot-starter-web")
    
    // 1. Actuator 추가
    implementation("org.springframework.boot:spring-boot-starter-actuator")
    
    // 2. Prometheus 연동을 위한 Micrometer Registry 추가
    implementation("io.micrometer:micrometer-registry-prometheus")
}

다음으로, application.yml 파일에서 Actuator 엔드포인트를 활성화하고 프로메테우스가 메트릭을 수집해갈 수 있도록 /actuator/prometheus 엔드포인트를 노출시킵니다.

# application.yml
management:
  endpoints:
    web:
      exposure:
        # "health"와 "prometheus" 엔드포인트를 웹으로 노출
        include: health,prometheus
  
  # (선택) 메트릭에 공통 태그(레이블) 추가하기
  metrics:
    tags:
      application: my-awesome-app

이제 애플리케이션을 실행하고 http://localhost:8080/actuator/prometheus에 접속하면, JVM, Tomcat, 시스템 정보 등 Actuator가 기본으로 제공하는 수많은 메트릭이 텍스트 형태로 출력되는 것을 볼 수 있습니다.

2단계: 기본 제공 메트릭 활용하기

Actuator와 Micrometer를 추가하는 것만으로도 우리는 이미 강력한 무기를 손에 넣었습니다. 별도의 코드 없이 아래와 같은 핵심 지표들을 바로 모니터링할 수 있습니다.

• jvm_memory_used_bytes: JVM 힙 메모리 사용량
• system_cpu_usage: 시스템 전체 CPU 사용률
• tomcat_sessions_active_current: 현재 활성화된 Tomcat 세션 수
• http_server_requests_seconds_*: HTTP 요청 처리 시간 (Histogram)

특히 http_server_requests_seconds는 모든 API 엔드포인트의 응답 시간을 자동으로 측정해주는 매우 유용한 메트릭입니다. 이 메트릭 하나만으로도 각 API의 RPS, Latency(p99, p95), 에러율 등을 모두 계산할 수 있습니다.

# 예시: URI 별 초당 평균 요청 수 (RPS)
sum by (uri) (rate(http_server_requests_seconds_count[1m]))

# 예시: URI 별 95 percentile 응답 시간
histogram_quantile(0.95, sum by (le, uri) (rate(http_server_requests_seconds_bucket[1m])))

3단계: 커스텀 메트릭 추가하기

기본 메트릭도 훌륭하지만, 진짜 중요한 것은 우리 서비스의 비즈니스 로직과 관련된 메트릭입니다. "오늘 신규 가입자 수", "주문 실패 건수", "특정 외부 API 호출 시간" 등이 여기에 해당합니다. Micrometer는 두 가지 편리한 방법을 제공합니다.

방법 1: 애노테이션 기반 (`@Timed`) - 가장 쉬운 방법

특정 메소드의 실행 시간을 측정하고 싶을 때 가장 간단한 방법입니다. 메소드 위에 @Timed 애노테이션만 붙여주면 됩니다.

import io.micrometer.core.annotation.Timed;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class MyController {

    @Timed(
        value = "my.api.latency", // 메트릭 이름
        description = "My API의 응답 시간을 측정합니다.",
        percentiles = {0.5, 0.95, 0.99} // p50, p95, p99 백분위수 계산
    )
    @GetMapping("/api/my")
    public String myApi() throws InterruptedException {
        // 임의의 지연 시간
        Thread.sleep((long) (Math.random() * 1000));
        return "OK";
    }
}

@Timed를 사용하려면 애플리케이션에 AOP 의존성이 필요하며, @EnableAspectJAutoProxy 설정이 필요할 수 있습니다. Spring Boot는 보통 자동으로 구성해줍니다. 이제 /api/my를 호출하면 my_api_latency_seconds_* 라는 이름의 Histogram 메트릭이 자동으로 수집됩니다.

방법 2: 코드 기반 (MeterRegistry) - 가장 유연한 방법

더 복잡한 비즈니스 로직을 측정하거나, Counter, Gauge 등 다른 타입의 메트릭을 사용하고 싶을 때는 MeterRegistry를 직접 주입받아 사용합니다.

import io.micrometer.core.instrument.Counter;
import io.micrometer.core.instrument.MeterRegistry;
import org.springframework.stereotype.Service;

@Service
public class OrderService {

    private final Counter orderSuccessCounter;
    private final Counter orderFailedCounter;
    private final MeterRegistry meterRegistry;

    // 생성자에서 MeterRegistry를 주입받고, 사용할 메트릭을 미리 빌드
    public OrderService(MeterRegistry meterRegistry) {
        this.meterRegistry = meterRegistry;

        this.orderSuccessCounter = Counter.builder("order.requests")
                .tag("status", "success")
                .description("성공한 주문 요청 수")
                .register(meterRegistry);

        this.orderFailedCounter = meterRegistry.counter("order.requests", "status", "failed");
    }

    public void order(String item) {
        // 특정 외부 API 호출 시간을 측정 (Timer)
        meterRegistry.timer("external.api.latency", "api.name", "payment").record(() -> {
            try {
                // ... 주문 로직 및 외부 결제 API 호출 ...
                if (Math.random() > 0.1) { // 90% 확률로 성공
                    System.out.println(item + " 주문 성공");
                    orderSuccessCounter.increment();
                } else {
                    throw new RuntimeException("주문 실패!");
                }
            } catch (Exception e) {
                System.out.println(item + " 주문 실패");
                orderFailedCounter.increment();
                throw e;
            }
        });
    }
}

위 예제에서는 MeterRegistry를 사용하여 주문 성공/실패 횟수를 세는 Counter와 외부 API 호출 시간을 재는 Timer(@Timed의 코드 기반 버전)를 만들었습니다. 이렇게 하면 "성공/실패별 주문 요청 수", "결제 API의 응답 시간 분포" 등 매우 구체적이고 유용한 비즈니스 메트릭을 수집할 수 있습니다.

4단계: 프로메테우스와 연결하기

이제 우리 애플리케이션은 /actuator/prometheus 엔드포인트를 통해 메트릭을 열심히 노출하고 있습니다. 마지막으로 프로메테우스가 이 메트릭을 주기적으로 수집하도록 설정해주면 됩니다.

# prometheus.yml
scrape_configs:
  - job_name: 'spring-boot-app'
    metrics_path: '/actuator/prometheus' # 메트릭 엔드포인트 경로
    scrape_interval: 15s # 15초마다 수집
    static_configs:
      - targets: ['localhost:8080'] # 우리 애플리케이션의 주소

이제 프로메테우스를 실행하면, 15초마다 우리 스프링 부트 애플리케이션의 모든 메트릭을 수집하여 저장하기 시작합니다. 그라파나에서 이 데이터를 쿼리하여 멋진 대시보드를 만드는 일만 남았습니다!