Spring Boot Actuator로 애플리케이션 모니터링하기

 

Spring Boot Actuator는 스프링 부트 애플리케이션에 모니터링과 관리 기능을 손쉽게 추가할 수 있도록 설계된 강력한 도구입니다. 운영 환경에서 애플리케이션의 상태를 실시간으로 점검하고, 성능을 분석하거나 문제를 해결하는 데 필수적인 정보를 제공합니다.
이 글에서는 Spring Boot Actuator의 주요 기능과 활용 방법, 설정 방법, 그리고 실제 사용 예제를 중심으로 Actuator의 가치를 탐구합니다.

---

1. Spring Boot Actuator란 무엇인가?

Spring Boot Actuator는 스프링 부트 애플리케이션에서 운영 및 관리 기능을 제공하는 라이브러리입니다.
Actuator는 애플리케이션의 상태와 메트릭, 환경 설정, 로그, HTTP 트레이싱 등의 정보를 쉽게 확인할 수 있도록 다양한 엔드포인트(Endpoints)를 제공합니다.

주요 특징

1. 모니터링 메트릭 제공
   • CPU 사용량, 메모리 사용량, 쓰레드 수, HTTP 요청 횟수 등.
2. 애플리케이션 상태 정보 제공
   • 애플리케이션의 실행 상태(헬스 체크), 활성 프로파일, 환경 변수 등.
3. 운영 관리 기능
   • 로그 레벨 변경, 캐시 갱신, 강제 종료 등.

---

2. Actuator를 사용해야 하는 이유

운영 환경에서 애플리케이션을 효과적으로 관리하려면 상태 점검과 실시간 메트릭 수집이 필수입니다.
Actuator는 이러한 요구를 만족시키는 다양한 기능을 제공하며, 특히 다음 상황에서 유용합니다:

1. 헬스 체크(Health Check)
   • 서비스 가용성을 자동화된 툴(Nagios, Prometheus 등)로 모니터링.
2. 애플리케이션 상태 확인
   • 배포 후 문제가 발생했을 때 상태 정보를 빠르게 확인.
3. 성능 분석 및 최적화
   • 메모리 사용량, GC 활동 등을 실시간으로 모니터링.
4. 운영 효율성 개선
   • 로그 레벨을 동적으로 조정하거나 설정 변경을 API로 적용.

---

3. Spring Boot Actuator 설정 방법

3.1 의존성 추가

Spring Boot Actuator를 사용하려면 spring-boot-starter-actuator 의존성을 추가해야 합니다.

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

3.2 애플리케이션 설정

Actuator의 엔드포인트를 활성화하려면 application.properties 또는 application.yml 파일에 설정을 추가해야 합니다.
기본 설정 (application.yml):

management:
  endpoints:
    web:
      exposure:
        include: "*"  # 모든 엔드포인트 활성화
  endpoint:
    health:
      show-details: always  # 헬스 체크 상세 정보 표시

---

4. 주요 Actuator 엔드포인트 소개

Actuator는 다양한 엔드포인트를 제공하며, 이를 통해 애플리케이션의 상태를 효과적으로 모니터링할 수 있습니다.
엔드포인트 설명

/actuator/health	애플리케이션의 상태를 반환 (예: UP, DOWN).
/actuator/metrics	애플리케이션의 메트릭 데이터를 조회.
/actuator/info	애플리케이션 정보(버전, 빌드 정보 등) 제공.
/actuator/loggers	애플리케이션 로그 레벨을 실시간으로 조회 및 변경.
/actuator/env	환경 변수와 프로퍼티 값 노출.
/actuator/threaddump	애플리케이션의 현재 쓰레드 덤프를 출력.
/actuator/httptrace	최근 HTTP 요청 및 응답 정보를 확인.

---

5. 실제 사용 예제

예제 1: 헬스 체크

/actuator/health 엔드포인트는 애플리케이션의 상태를 확인하는 데 사용됩니다.
기본적으로 "UP" 또는 "DOWN" 상태만 표시되지만, 상세 정보를 포함하도록 설정할 수 있습니다.

management:
  endpoint:
    health:
      show-details: always

실행 결과:

{
  "status": "UP",
  "components": {
    "db": {
      "status": "UP",
      "details": {
        "database": "PostgreSQL",
        "validationQuery": "SELECT 1"
      }
    },
    "diskSpace": {
      "status": "UP",
      "details": {
        "total": 499963174912,
        "free": 304874106880,
        "threshold": 10485760
      }
    }
  }
}

예제 2: 메트릭 수집

/actuator/metrics 엔드포인트는 애플리케이션의 다양한 메트릭 정보를 제공합니다.
특정 메트릭 값을 확인하려면 엔드포인트에 매개변수를 추가합니다.
예: JVM 메모리 사용량 확인:

GET /actuator/metrics/jvm.memory.used

실행 결과:

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

예제 3: 동적 로그 레벨 변경

/actuator/loggers 엔드포인트를 통해 애플리케이션의 로그 레벨을 실시간으로 변경할 수 있습니다.
GET 요청으로 현재 로그 레벨 확인:

GET /actuator/loggers/com.example.demo

POST 요청으로 로그 레벨 변경:

curl -X POST -H "Content-Type: application/json" -d '{"configuredLevel": "DEBUG"}' http://localhost:8080/actuator/loggers/com.example.demo

---

6. Actuator와 외부 모니터링 도구 통합

Actuator는 Prometheus, Grafana, ELK 스택과 같은 모니터링 도구와 쉽게 통합할 수 있습니다.
예를 들어, Micrometer를 사용해 Prometheus로 메트릭을 전송하고 Grafana 대시보드에서 시각화할 수 있습니다.

Prometheus 연동 예제

의존성 추가:

<dependency>
    <groupId>io.micrometer</groupId>
    <artifactId>micrometer-registry-prometheus</artifactId>
</dependency>

설정 (application.yml):

management:
  endpoints:
    web:
      exposure:
        include: "prometheus"

Prometheus에서 /actuator/prometheus 엔드포인트를 데이터 소스로 등록하면 메트릭 데이터를 자동으로 수집합니다.

---

7. 결론

Spring Boot Actuator는 애플리케이션의 상태를 실시간으로 모니터링하고 운영 효율성을 높이는 데 필수적인 도구입니다. 기본적인 헬스 체크부터 복잡한 메트릭 수집 및 외부 시스템 통합까지 다양한 기능을 제공합니다.
Actuator를 통해 애플리케이션의 가용성을 유지하고 성능 병목 현상을 사전에 방지할 수 있습니다. 특히 운영 환경에서 안정적이고 신뢰할 수 있는 서비스를 제공하려는 팀이라면 반드시 활용해 보길 권장합니다.