Spring Boot - Actuator

🚀 스프링 부트 Actuator 정리

1. 🔍 Actuator란?

Spring Boot Actuator는 애플리케이션의 모니터링 및 관리 기능을 제공하는 라이브러리이다.

이를 통해 애플리케이션의 상태, 로그, 성능 지표 등을 쉽게 확인할 수 있다.

✅ Actuator의 주요 기능

• 애플리케이션의 상태 점검(Health Check)
• 환경 변수, 빈(Bean), 캐시 정보 조회
• 메트릭(성능 지표) 제공
• 로그 레벨 동적 변경

---

2. ⚙️ Actuator 설정 및 활성화

2.1 Actuator 의존성 추가

프로젝트의 build.gradle 또는 pom.xml 파일에 Actuator 의존성을 추가한다.

✅ Gradle (build.gradle)

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

✅ Maven (pom.xml)

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

---

2.2 application.properties 설정

Actuator를 활성화하고 필요한 엔드포인트를 설정할 수 있다.

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

# 특정 엔드포인트만 활성화 (예: health, info)
# management.endpoints.web.exposure.include=health,info

# Health 상세 정보 노출
management.endpoint.health.show-details=always

# 메트릭 정보 노출
management.metrics.export.prometheus.enabled=true

---

3. 🎯 주요 Actuator 엔드포인트

Actuator를 활성화하면 여러 개의 유용한 엔드포인트를 제공한다.

엔드포인트 설명

/actuator	사용 가능한 엔드포인트 목록 제공
/actuator/health	애플리케이션의 상태 확인
/actuator/info	애플리케이션 정보 제공 (버전, 설명 등)
/actuator/metrics	성능 지표 (CPU, 메모리, HTTP 요청 수 등)
/actuator/env	환경 변수 조회
/actuator/beans	등록된 스프링 빈 목록 조회
/actuator/loggers	로그 레벨 동적 변경
/actuator/mappings	컨트롤러 매핑 정보 제공
/actuator/threaddump	현재 실행 중인 스레드 정보 조회

📌 예제: /actuator/health

{
    "status": "UP",
    "components": {
        "db": {
            "status": "UP",
            "details": {
                "database": "MySQL",
                "result": "SUCCESS"
            }
        },
        "diskSpace": {
            "status": "UP",
            "details": {
                "total": 500000000000,
                "free": 250000000000,
                "threshold": 10485760
            }
        }
    }
}

---

4. 🎛 커스텀 Actuator 정보 추가하기

4.1 /actuator/info 엔드포인트에 추가 정보 설정

application.properties에서 추가 정보를 정의할 수 있다.

info.app.name=MySpringBootApp
info.app.version=1.0.0
info.app.description=Spring Boot Actuator Example

결과 (/actuator/info)

{
    "app": {
        "name": "MySpringBootApp",
        "version": "1.0.0",
        "description": "Spring Boot Actuator Example"
    }
}

---

4.2 커스텀 Health Indicator 만들기

사용자가 원하는 방식으로 Health Check 엔드포인트를 확장할 수 있다.

import org.springframework.boot.actuate.health.Health;
import org.springframework.boot.actuate.health.HealthIndicator;
import org.springframework.stereotype.Component;

@Component
public class CustomHealthIndicator implements HealthIndicator {

    @Override
    public Health health() {
        boolean isServiceRunning = checkServiceHealth(); // 커스텀 로직
        if (isServiceRunning) {
            return Health.up().withDetail("service", "Running").build();
        }
        return Health.down().withDetail("service", "Not Running").build();
    }

    private boolean checkServiceHealth() {
        // 실제 서비스 상태를 확인하는 로직
        return true;
    }
}

결과 (/actuator/health)

{
    "status": "UP",
    "components": {
        "customHealthIndicator": {
            "status": "UP",
            "details": {
                "service": "Running"
            }
        }
    }
}

---

5. 🛡 보안 설정 (Actuator 엔드포인트 보호)

Actuator 엔드포인트는 중요 정보(예: 환경 변수, 로그 레벨 등)를 포함할 수 있으므로 보안 설정이 필요하다.

5.1 엔드포인트 접근 제한

# 특정 엔드포인트만 허용
management.endpoints.web.exposure.include=health,info

5.2 Spring Security와 함께 사용

스프링 시큐리티를 적용하면 Actuator 엔드포인트에 인증 및 권한 설정을 추가할 수 있다.

✅ Security 의존성 추가 (build.gradle)

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-security'
}

✅ 사용자 계정 설정 (application.properties)

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

이제 /actuator 엔드포인트에 접근하려면 인증이 필요하다.

---

6. 🚀 Actuator + Prometheus + Grafana

Actuator는 Prometheus 및 Grafana와 연동하여 애플리케이션 모니터링 시스템을 구축할 수도 있다.

1. Prometheus 설정 (application.properties)
2. management.metrics.export.prometheus.enabled=true
3. Prometheus에서 Actuator 데이터를 스크랩
4. scrape_configs: - job_name: 'spring-boot-app' metrics_path: '/actuator/prometheus' static_configs: - targets: ['localhost:8080']
5. Grafana에서 Prometheus 연동 후 Spring Boot 메트릭 대시보드 설정

---

7. ✅ 정리

✅ Actuator는 스프링 부트 애플리케이션의 상태, 메트릭, 로그 등을 제공하는 강력한 모니터링 도구이다.

✅ /actuator/health, /actuator/metrics 등의 엔드포인트를 통해 애플리케이션 상태를 확인할 수 있다.

✅ Prometheus + Grafana를 연동하면 실시간 모니터링 시스템을 구축할 수 있다.

✅ 보안 설정을 적용하여 Actuator 엔드포인트를 안전하게 보호해야 한다.