동블

그래프 뷰

04. Spring Boot Actuator Micrometer 상세

8 min read

이 문서를 통해 아래 질문들에 답할 수 있게 됩니다.

  • Spring Boot Actuator와 Micrometer는 운영 관측에서 각각 어떤 역할을 하는가?
  • /actuator/health, /actuator/info, /actuator/prometheus를 어떻게 안전하게 노출해야 하는가?
  • Custom metric을 만들 때 어떤 이름, tag, 보안 기준을 지켜야 하는가?

개요

Spring Boot Actuator는 애플리케이션의 운영 endpoint를 제공한다.

Micrometer는 애플리케이션 metric을 수집 시스템이 읽을 수 있는 형태로 기록하는 관측 facade다.

둘을 함께 쓰면 Spring 내부 상태, HTTP 요청, JVM, connection pool, custom business metric을 운영 지표로 볼 수 있다.

하지만 endpoint를 넓게 열거나 metric tag를 잘못 설계하면 보안과 비용 문제가 생긴다.

Actuator Endpoint

자주 쓰는 endpoint는 health, info, prometheus다.

management.endpoints.web.exposure.include=health,info,prometheus
management.endpoint.health.probes.enabled=true
management.info.git.mode=full

health는 readiness와 liveness 판단에 쓰인다.

info는 실행 중인 version, git commit, build 정보를 확인하는 데 유용하다.

prometheus는 Prometheus 형식 metric을 노출한다.

모든 endpoint를 운영 외부에 공개하면 안 된다.

Health

Health는 “프로세스가 떠 있음”과 “트래픽을 받아도 됨”을 구분해야 한다.

curl -fsS http://localhost:8080/actuator/health
curl -fsS http://localhost:8080/actuator/health/readiness
curl -fsS http://localhost:8080/actuator/health/liveness

Readiness에는 DB, Redis, 외부 의존성을 어디까지 포함할지 기준이 필요하다.

너무 많은 외부 의존성을 readiness에 넣으면 작은 외부 장애가 전체 트래픽 차단으로 이어질 수 있다.

반대로 핵심 DB 연결이 빠져 있으면 준비되지 않은 인스턴스가 트래픽을 받을 수 있다.

Prometheus Metric

Micrometer는 HTTP server request, JVM, thread, datasource, cache metric을 제공한다.

curl -fsS http://localhost:8080/actuator/prometheus | grep http_server_requests
curl -fsS http://localhost:8080/actuator/prometheus | grep jvm_memory_used

운영에서는 이 endpoint를 수집 시스템만 접근하게 제한한다.

Public internet에 그대로 열면 내부 endpoint, exception, version 정보가 노출될 수 있다.

Custom Metric

비즈니스 흐름도 metric으로 남길 수 있다.

@Service
class OrderMetrics {
    private final Counter orderFailed;
 
    OrderMetrics(MeterRegistry registry) {
        this.orderFailed = Counter.builder("order_failed_total")
                .tag("reason", "payment_timeout")
                .register(registry);
    }
 
    void recordPaymentTimeout() {
        orderFailed.increment();
    }
}

이름은 의미와 단위를 드러내야 한다.

tag 값은 제한된 범위여야 한다.

주문 번호나 사용자 id를 tag에 넣지 않는다.

보안과 접근 제어

Actuator는 운영 정보를 노출한다.

노출 endpoint, network 접근, 인증, 권한을 정해야 한다.

prometheus는 수집기에서만 접근하게 하고, env, beans, heapdump 같은 endpoint는 운영에서 특별한 이유 없이 열지 않는다.

info에 commit과 version은 유용하지만 민감 config나 Secret이 들어가면 안 된다.

운영 체크리스트

  • 운영에 노출할 Actuator endpoint가 최소로 제한되어 있는가?
  • readiness와 liveness의 의미가 구분되어 있는가?
  • /actuator/info에서 실행 version을 확인할 수 있는가?
  • /actuator/prometheus 접근이 수집 시스템으로 제한되어 있는가?
  • HTTP, JVM, datasource, custom business metric이 필요한 수준으로 수집되는가?
  • custom metric 이름과 tag cardinality를 리뷰했는가?
  • endpoint 노출 변경 후 보안 검토와 smoke test가 있는가?

장애 신호

  • readiness는 UP인데 핵심 DB query가 계속 실패한다.
  • liveness에 외부 의존성을 넣어 작은 dependency 장애 때 인스턴스가 재시작된다.
  • /actuator/prometheus가 외부에 공개되어 내부 metric이 노출된다.
  • custom metric tag에 user id가 들어가 series가 폭증한다.
  • /actuator/info의 version과 배포 기록이 다르다.
  • health endpoint가 너무 느려 수집이나 load balancer health check가 흔들린다.

안전한 완화 조치

Actuator 노출 문제가 있으면 endpoint exposure를 먼저 줄인다.

Public 접근 경로가 열렸다면 network rule과 인증 설정을 확인한다.

Readiness 오작동은 포함된 health indicator를 하나씩 확인한다.

Metric cardinality가 폭증하면 새 tag 생성을 멈추고 offending label을 제거한다.

Custom metric 이름을 바꾸면 dashboard와 alert query도 함께 갱신한다.

인프라 담당자와 공유할 자료

문제: readiness는 UP인데 주문 API 500 증가
service: order-api
version: /actuator/info = 1.8.3-abc1234
health endpoint: /actuator/health/readiness UP
관련 metric: datasource connection active max 근접
의심: readiness DB check는 통과하지만 query pool saturation 발생
요청: datasource metric dashboard와 health indicator 기준 확인

Actuator 문제 공유에는 endpoint 응답과 metric 이름, 접근 경로, version 정보를 함께 제공한다.

실전 팁

  • Actuator endpoint는 필요한 것만 연다.
  • readiness와 liveness를 같은 의미로 쓰지 않는다.
  • /actuator/info는 배포 version 확인에 유용하다.
  • Custom metric tag는 값 종류가 제한된 것만 둔다.
  • Metric 추가는 dashboard와 alert 사용 계획이 있을 때 의미가 크다.

위험 신호!

  • management.endpoints.web.exposure.include=*를 운영에 둔다.
  • health check에 모든 외부 의존성을 무조건 넣는다.
  • prometheus endpoint를 인증 없이 외부에 연다.
  • custom metric tag에 request id나 user id를 넣는다.
  • metric을 추가했지만 누구도 dashboard나 alert에서 쓰지 않는다.

확인 질문

확인 질문

  • Actuator와 Micrometer의 역할 차이는 무엇인가?
    • Actuator는 운영 endpoint를 제공하고, Micrometer는 metric을 기록해 수집 시스템이 읽을 수 있게 한다.
  • Readiness와 liveness를 구분해야 하는 이유는 무엇인가?
    • readiness는 트래픽 수신 가능 여부이고 liveness는 프로세스 재시작 필요 여부라 잘못 섞으면 불필요한 재시작이나 잘못된 트래픽 유입이 생긴다.
  • /actuator/prometheus를 조심해서 노출해야 하는 이유는 무엇인가?
    • 내부 endpoint, version, exception, resource 상태 같은 운영 정보가 외부에 노출될 수 있기 때문이다.

참고 문서

관련 문서

백링크