Spring Boot Actuator 개요

Spring Boot Actuator는 애플리케이션의 상태 모니터링 및 관리 기능을 제공하는 도구입니다. 운영 환경에서 애플리케이션의 상태를 실시간으로 확인하고, 필요한 진단 정보를 제공할 수 있도록 설계되었습니다.

---

1. Actuator 의 주요 기능

Actuator는 다양한 엔드포인트(Endpoints) 를 제공하며, 이를 통해 애플리케이션 상태를 쉽게 모니터링할 수 있습니다.

📌 주요 Actuator 엔드포인트

엔드포인트	설명
/actuator/health	애플리케이션의 현재 상태 확인
/actuator/info	애플리케이션 관련 정보 제공
/actuator/metrics	성능 및 메트릭 데이터 조회
/actuator/env	환경 변수 확인
/actuator/beans	Spring Bean 목록 조회
/actuator/mappings	모든 요청 매핑 정보 확인
/actuator/loggers	로깅 레벨 변경 가능
/actuator/threaddump	현재 실행 중인 스레드 덤프 제공
/actuator/heapdump	힙 덤프 다운로드
/actuator/shutdown	애플리케이션 종료 (기본 비활성화)

---

2. Actuator 설정 및 활성화

✅ 1) 의존성 추가 (Maven)

Spring Boot 2.x 이상에서는 spring-boot-starter-actuator 의존성을 추가하면 사용할 수 있습니다.

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

✅ 2) application.properties 설정

# Actuator 기본 설정
management.endpoints.web.exposure.include=health,info,metrics

# 모든 엔드포인트 활성화
# management.endpoints.web.exposure.include=*

# Health 상세 정보 제공
management.endpoint.health.show-details=always

⚠ 기본적으로 /actuator 엔드포인트는 일부만 노출되며, 모든 엔드포인트를 활성화하려면 설정이 필요합니다.

---

3. 주요 엔드포인트 활용 예제

1) 애플리케이션 상태 확인 (Health Check)

• /actuator/health 엔드포인트를 호출하면 현재 애플리케이션 상태를 확인할 수 있습니다.
• 기본 상태 결과:

{
  "status": "UP"
}

• DB 연결 등 추가 정보를 보려면 설정 추가:

management.endpoint.health.show-details=always

• 이후 /actuator/health 호출 시:

{
  "status": "UP",
  "components": {
    "db": {
      "status": "UP",
      "details": {
        "database": "PostgreSQL",
        "result": "Connected"
      }
    },
    "diskSpace": {
      "status": "UP",
      "details": {
        "total": 50000000000,
        "free": 30000000000
      }
    }
  }
}

---

2) 애플리케이션 정보 확인 (/actuator/info)

• application.properties 에서 정보 추가:

info.app.name=MySpringBootApp
info.app.version=1.0.0

• /actuator/info 호출 결과:

{
  "app": {
    "name": "MySpringBootApp",
    "version": "1.0.0"
  }
}

---

3) 메트릭 조회 (/actuator/metrics)

• /actuator/metrics 호출 시 제공되는 메트릭 목록을 확인할 수 있음
• 특정 메트릭 조회 (예: JVM 메모리 사용량)

  GET /actuator/metrics/jvm.memory.used
  

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

---

4) Logger 레벨 변경 (/actuator/loggers)

• 현재 설정된 로깅 레벨 조회:

  GET /actuator/loggers
  

• 특정 로거의 로그 레벨 변경:

  POST /actuator/loggers/com.example.demo
  Content-Type: application/json
  Body:
  {
    "configuredLevel": "DEBUG"
  }
  

---

4. Spring Security를 활용한 보안 적용

Actuator 엔드포인트는 민감한 정보를 포함할 수 있기 때문에 보안 설정이 중요합니다.

✅ 1) Spring Security 설정 추가

1) Spring Security 의존성 추가

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

2) 기본 사용자 계정 확인 (로그 출력)
Spring Boot를 실행하면 기본 계정이 자동 생성되며, 콘솔에 아래와 같은 형태로 표시됩니다.

Using generated security password: 9a8b7c6d5e

해당 비밀번호를 사용하여 Actuator 엔드포인트에 접근할 수 있습니다.

3) 사용자 정의 계정 설정

spring.security.user.name=admin
spring.security.user.password=admin123

이제 /actuator 엔드포인트에 접근 시 Basic Auth(ID/PW) 입력이 필요합니다.

---

5. Prometheus & Grafana 연동 (모니터링)

Actuator는 Prometheus 및 Grafana 같은 모니터링 도구와 쉽게 통합할 수 있습니다.

✅ 1) Prometheus 메트릭 엔드포인트 활성화

management.endpoints.web.exposure.include=health,metrics,prometheus

• 이후 /actuator/prometheus 엔드포인트를 Prometheus에 등록하면 실시간 메트릭 수집 가능
• Grafana를 사용하여 Prometheus 데이터를 시각화 가능

---

6. Actuator와 로그 및 힙 덤프 분석

• /actuator/threaddump → 현재 실행 중인 스레드 정보 확인
• /actuator/heapdump → 힙 덤프 다운로드 가능 (OOM 발생 시 분석 가능)
• /actuator/mappings → 모든 컨트롤러의 요청 매핑 확인

---

7. Actuator의 장점과 단점

✅ 장점

• 애플리케이션 상태 모니터링을 쉽게 구현 가능
• Spring Security와 연동하여 안전한 관리 가능
• Prometheus, Grafana 같은 모니터링 툴과 쉽게 통합

❌ 단점

• 기본적으로 일부 엔드포인트만 노출되며, 모든 기능을 활용하려면 설정 필요
• 보안 설정을 신경 쓰지 않으면 민감한 정보가 외부에 노출될 가능성이 있음

---

🔹 결론

Spring Boot Actuator는 운영 환경에서 애플리케이션의 상태를 모니터링하고, 문제 발생 시 원인을 빠르게 진단하는 데 유용한 도구입니다. 특히 Prometheus 및 Grafana와 통합하면 시스템 성능 모니터링을 보다 효율적으로 할 수 있습니다. Actuator를 적절히 활용하면 애플리케이션의 안정성과 가용성을 높일 수 있으며, 관리 비용을 절감하는 데 큰 도움이 됩니다. 🚀