Spring Boot Actuator와 Micrometer로 애플리케이션 모니터링

개요

애플리케이션 가용성이나 성능을 확인하려면 일관된 메트릭 수집이 필요하다. Spring Boot Actuator는 상태와 운영 정보를 제공한다. Micrometer는 다양한 모니터링 백엔드로 메트릭을 노출하는 추상층을 제공한다. 본문은 spring boot actuator 설정과 micrometer spring boot prometheus 연동, 그리고 spring boot metrics actuator 활용을 중심으로 초보자도 이해하기 쉬운 흐름으로 정리한다.

필수 구성 요소

기본적으로 필요한 구성 요소는 다음과 같다.

• Spring Boot 애플리케이션
• spring-boot-starter-actuator
• micrometer-registry-prometheus (Prometheus 사용 시)
• Prometheus 서버와 Grafana (선택적 시각화)

의존성 추가

Maven 프로젝트 기준 기본 의존성 예시이다.

 <dependencies>
  <dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-actuator</artifactId>
  </dependency>
  <dependency>
    <groupId>io.micrometer</groupId>
    <artifactId>micrometer-registry-prometheus</artifactId>
  </dependency>
</dependencies>

Actuator와 Micrometer 설정

application.yml 또는 application.properties에서 엔드포인트 노출과 보안, Prometheus 노출을 설정한다. 기본적으로 actuator는 민감한 엔드포인트를 제한한다. 프로덕션 환경에서는 인증과 네트워크 레벨 보호가 권장된다.

management:
  endpoints:
    web:
      exposure:
        include: "health,info,prometheus,metrics"
  endpoint:
    health:
      show-details: always
  metrics:
    enable:
      all: true
  server:
    port: 8080

주요 엔드포인트

• /actuator/health: 애플리케이션 상태
• /actuator/info: 빌드 정보 등
• /actuator/metrics: 등록된 메트릭 목록
• /actuator/prometheus: Prometheus 형식의 메트릭 노출

Micrometer로 커스텀 메트릭 등록

비즈니스 지표나 카운터, 타이머를 직접 등록할 수 있다. 아래 예시는 요청 카운터와 처리 시간 측정 예시이다.

package com.example.monitoring;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
import io.micrometer.core.instrument.MeterRegistry;
import io.micrometer.core.instrument.Timer;

@RestController
public class MetricController {

  private final MeterRegistry registry;
  private final Timer processTimer;

  public MetricController(MeterRegistry registry) {
    this.registry = registry;
    this.processTimer = registry.timer("example.process.timer");
  }

  @GetMapping("/process")
  public String process() {
    return processTimer.record(() -> {
      try {
        Thread.sleep(120); // 샘플 작업
      } catch (InterruptedException e) {
        Thread.currentThread().interrupt();
      }
      return "ok";
    });
  }
}

위 코드의 MeterRegistry는 Micrometer가 제공하는 공용 인터페이스다. registry.counter, registry.gauge 등 다양한 메서드로 메트릭을 생성한다. 생성한 메트릭은 /actuator/metrics 또는 /actuator/prometheus를 통해 확인 가능하다.

Prometheus 연동

Prometheus는 주기적으로 애플리케이션의 /actuator/prometheus 엔드포인트를 스크랩한다. Prometheus 설정 파일에서 job을 등록하면 된다.

scrape_configs:
  - job_name: 'spring-application'
    metrics_path: '/actuator/prometheus'
    static_configs:
      - targets: ['host.docker.internal:8080']

스크랩 주기나 TLS, 인증은 Prometheus 설정에서 제어한다. 사내망이나 클라우드 환경에서는 네트워크 정책을 통해 접근을 제한한다.

Grafana 시각화

Prometheus를 데이터 소스로 추가한 뒤 대시보드를 구성하면 실시간 모니터링이 가능하다. 주요 메트릭은 다음과 같다.

• jvm.memory.used, jvm.memory.max
• process.cpu.usage
• http.server.requests (요청 수, 응답 시간 분포)
• custom metric names (예: example.process.timer)

보안과 운영 고려사항

운영 환경에서는 actuator 엔드포인트 접근 제어가 중요하다. 다음 권장 사항을 고려한다.

• 엔드포인트는 내부 네트워크로 제한
• 기밀 정보 노출 방지(health 세부 정보 제어)
• Prometheus와의 통신은 TLS 또는 사설 네트워크 사용
• 메트릭 라벨(cardinality) 관리: 높은 라벨 카디널리티는 성능 문제 유발

문제 해결과 검증

설정 후에는 다음 순서로 동작을 확인한다.

• /actuator/health에서 상태 확인
• /actuator/metrics로 메트릭 목록 확인
• /actuator/prometheus로 Prometheus 포맷 검증
• Prometheus에서 스크래핑 로그 확인

정리

spring boot actuator 설정과 micrometer spring boot prometheus 연동은 비교적 단순하다. Actuator는 운영 정보 노출을, Micrometer는 백엔드 독립적인 메트릭 수집을 담당한다. spring boot metrics actuator를 통해 기본 메트릭을 확보한 뒤, 커스텀 지표를 추가하면 실무 모니터링 체계가 완성된다. 마지막으로 보안과 라벨 카디널리티를 주의하면 안정적인 운영이 가능하다.