[스프링 핵심 원리와 활용] 섹션9. 액츄에이터

[724thomas]

요약

• 액츄에이터(Actuator)
  운영 환경에서 애플리케이션 상태를 모니터링·제어하기 위한 스프링 부트 내장 기능

• 프로덕션 준비 기능

  • 지표(Metrics)
  • 추적(Trace)
  • 감사(Audit)
  • 모니터링(Monitoring)

• 프로젝트 설정
  spring-boot-starter-actuator 의존성 추가 후 /actuator 엔드포인트 제공

• 주요 엔드포인트

  • /health : 서버/DB/디스크 상태
  • /info : 빌드·버전·Git 정보
  • /metrics : 메모리, GC, HTTP 지연, 커넥션 풀
  • /loggers : 로그 레벨 조회·변경
  • /httpexchanges : 최근 HTTP 요청/응답 기록
  • /threaddump, /heapdump : 스레드·메모리 덤프

• 헬스 체크

  • DB, Redis, Disk 이상 시 DOWN 상태 반환
  • 로드밸런서와 연계 가능

• 애플리케이션 정보

  • build-info.properties
  • git.properties → 배포 브랜치, 커밋 ID 확인

• 로거 관리

  • 운영 중에도 로그 레벨 동적 변경 가능
  • 서버 재시작 필요 없음

• 보안 고려

  • 내부망 전용 포트 분리 (예: 9292)
  • 엔드포인트 최소 노출
  • Spring Security 인증 적용

• 실무 시나리오

  • DB 커넥션 풀 고갈 → metrics 확인
  • 메모리 누수 → heapdump 분석
  • 스레드 교착상태 → threaddump 확인
  • 응답 지연 → http.server.requests 확인

• 모니터링 연동

  • Micrometer 기반
  • Prometheus, Grafana 등과 연계 용이

---

1. 액츄에이터

운영 환경에서의 모니터링·지표 수집·장애 대응을 위해 스프링 부트가 제공하는 기능
애플리케이션을 운영하다 보면, "코드는 잘 돌아가는데 서비스는 왜 느려졌지?", "DB 연결은 정상일까?", "갑자기 서버가 죽었는데 원인을 어떻게 찾지?" 같은 문제는 단순 로그만으로는 한계가 있다.

---

2. 프로덕션 준비 기능

운영 환경에서 중요한 것은 단순히 "서비스가 켜져 있다"가 아니라 얼마나 잘 동작하고 있는지, 이상 징후를 얼마나 빨리 감지할 수 있는지다.

• 지표(Metrics): 메모리 사용량, 쓰레드 상태, HTTP 요청 지연 시간 등 수치화된 값
• 추적(Trace): 요청이 어떤 경로를 거쳤는지 추적
• 감사(Auditing): 중요한 이벤트 발생 기록
• 모니터링(Monitoring): 위의 모든 데이터를 바탕으로 지속적으로 감시

스프링 부트 액츄에이터는 이 모든 것을 기본 제공
Prometheus·Grafana 같은 모니터링 툴과도 쉽게 연동된다.

---

3. 프로젝트 설정

Gradle 설정 예시

    dependencies {
        ...
        implementation 'org.springframework.boot:spring-boot-starter-actuator' // 핵심
        ....
    }

실행 후 확인

1. http://localhost:8080/actuator
2. { "status": "UP" } 형태의 응답 → 서버 정상 작동

---

4. 엔드포인트

액츄에이터의 모든 기능은 **엔드포인트(endpoint)**라는 단위로 제공된다.
예시:

• /actuator/health → 서버/DB/디스크 상태
• /actuator/metrics → CPU, 메모리, 요청 지연시간 등
• /actuator/loggers → 로그 레벨 확인 및 동적 변경

엔드포인트 활성화 vs 노출

• 활성화(Enabled): 해당 기능을 사용할지 여부 (on/off)
• 노출(Exposure): HTTP 또는 JMX를 통해 외부로 보여줄지 여부

application.yml 예시

    management:
      endpoints:
        web:
          exposure:
            include: "*"

---

5. 자주 쓰이는 주요 엔드포인트

• health : 서버 및 의존 리소스(DB, Redis, Disk 등) 상태
• info : 빌드/버전/Git 브랜치/커밋 ID
• metrics : 메모리, GC, HTTP 지연 시간, 쓰레드 풀 상태
• loggers : 로그 레벨 확인 및 실시간 조정
• httpexchanges : HTTP 요청/응답 기록
• mappings : 컨트롤러 요청 매핑 정보
• threaddump/heapdump : 쓰레드/메모리 덤프

---

6. 장애 상황과 헬스 체크

헬스 체크는 단순히 "status": "UP"만 아니라 DB 연결 불가, 디스크 공간 부족, Redis 장애 같은 세부 정보까지 함께 제공한다.

예시: DB 장애 발생

    {
      "status": "DOWN",
      "components": {
        "db": { "status": "DOWN" },
        "diskSpace": { "status": "UP" }
      }
    }

---

7. 애플리케이션 정보 (Info)

/actuator/info 엔드포인트는 빌드 정보, Git 커밋 ID, 배포 브랜치 같은 메타데이터를 제공.

• build-info.properties
• git.properties

실무 사례: “프로덕션에서 특정 기능이 안 돌아간다” → 확인해보니 다른 브랜치에서 빌드된 아티팩트가 배포됨 → git.commit.id 값 확인으로 문제 즉시 파악.

---

8. 로거 관리와 장애 분석

운영 중 발생한 장애를 분석하려면 로그가 필수다. 하지만 무분별하게 DEBUG 로그를 남기면 성능 저하·디스크 용량 부족으로 이어진다.

• 기본 운영 로그 레벨: INFO
• 필요 시 /actuator/loggers/{loggerName}에 POST 요청으로 로그 레벨을 DEBUG/TRACE로 변경 가능

서버 재시작 없이 실시간으로 로그 레벨을 조정할 수 있어 긴급 장애 분석에 유용.

---

9. HTTP 요청/응답 추적

httpexchanges 엔드포인트는 최근 HTTP 요청/응답을 기록.
InMemory 저장소 기반이므로 운영보다는 개발/테스트 환경용.
운영 환경에서는 Zipkin, Pinpoint 같은 분산 트레이싱 시스템과 연계.

---

10. 보안 고려 사항

액츄에이터는 내부 정보(환경 변수, 로그 레벨, 스레드 덤프 등)를 그대로 노출. (주의)

보안 전략:

1. 내부망 전용 포트에서 실행 (management.server.port=9292)
2. 엔드포인트별 노출 제한 (include, exclude)
3. Spring Security 연동으로 인증/인가 제어

---

11. 실무에서 자주 겪는 시나리오

• DB 연결 풀 고갈: /actuator/metrics에서 HikariCP active connection 수치 확인
• 메모리 누수: /actuator/heapdump 다운로드 → Eclipse MAT 분석
• 스레드 교착상태: /actuator/threaddump → 문제 스레드 추적
• API 응답 지연: /actuator/metrics/http.server.requests로 특정 엔드포인트 지연 확인

---

12. 모니터링 시스템과의 연동

스프링 부트 액츄에이터는 단순 모니터링뿐 아니라 **마이크로미터(Micrometer)**와 통합되어 Prometheus, Datadog, Grafana 등과 연계 가능.
실무에서는 액츄에이터 → Prometheus → Grafana 대시보드 구성이 가장 일반적.