[Spring Boot] 서버의 건강검진 리포트, Actuator 완벽 가이드

서버를 배포하고 나면 개발자들은 불안해집니다.
"서버가 죽지는 않았나?", "DB 연결은 잘 붙어있나?", "디스크 용량은 충분한가?"

로그 파일을 뒤지는 건 너무 느립니다.

자동차 계기판처럼 현재 서버의 상태를 한눈에 보여주는 도구, Spring Actuator를 소개합니다.

---

1. Actuator가 뭔가요?

Actuator는 실행 중인 애플리케이션의 내부 정보를 외부로 노출해주는 라이브러리입니다.
간단한 설정만으로 Health Check(상태 점검), 로그 레벨 변경, 메모리 사용량 확인 등 운영에 필수적인 기능들을 HTTP URL로 제공합니다.

---

Step 1. 의존성 추가

가장 먼저 build.gradle에 라이브러리를 추가합니다.

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

---

Step 2. 기본 상태 확인 (/actuator/health)

서버를 실행하고 브라우저에서 http://localhost:8080/actuator/health로 접속해 봅니다.
보안상의 이유로 처음에는 아주 심플한 정보만 나옵니다.

// 기본 설정 시 결과
{
  "status": "UP"
}

• UP: 서버가 살아있음.
• DOWN: 뭔가 문제가 있음.

하지만 우리는 "왜 DOWN인지", "어디가 아픈지" 구체적인 이유가 알고 싶습니다.

---

Step 3. 상세 정보 켜기 (설정 변경)

application.yml 파일에 설정을 추가하여 잠겨있는 정보들을 해제해 봅시다.

• 위치: src/main/resources/application.yml

management:
  endpoint:
    health:
      show-details: always # 상세 정보를 항상 보여줘!

이제 서버를 재시작하고 다시 접속해 보면, 놀라운 정보들이 쏟아집니다.

[상세 결과 예시]

{
  "status": "UP",
  "components": {
    "db": { // 1. DB 연결 상태
      "status": "UP",
      "details": {
        "database": "MySQL",
        "validationQuery": "isValid()"
      }
    },
    "diskSpace": { // 2. 디스크 용량 상태
      "status": "UP",
      "details": {
        "total": 1000204886016,
        "free": 499204886016, // 남은 용량
        "threshold": 10485760 // 이 값(10MB)보다 적으면 DOWN 됨
      }
    },
    "ping": {
      "status": "UP"
    }
  }
}

이제 DB가 끊겼는지, 디스크가 꽉 찼는지 한눈에 알 수 있습니다!

---

Step 4. 전체 메뉴판 열기 (/actuator)

그럼 health 말고 다른 기능은 없을까요?
http://localhost:8080/actuator (루트 경로)로 접속해 봅니다.

{
  "_links": {
    "self": { "href": "http://localhost:8080/actuator", ... },
    "health": { "href": "http://localhost:8080/actuator/health", ... }
  }
}

어라? 링크가 몇 개 없습니다.
스프링 부트는 보안을 위해 기본적으로 health만 노출하고 나머지는 숨겨둡니다.
모든 기능을 보고 싶다면 설정을 하나 더 추가해야 합니다.

management:
  endpoints:
    web:
      exposure:
        include: "*" # 모든 기능을 다 노출해줘! (운영 환경에선 주의)

이제 다시 /actuator에 접속하면 수십 개의 기능 목록(링크)이 보일 것입니다.
이 페이지는 "어떤 기능을 쓸 수 있는지 알려주는 메뉴판(네비게이션)" 역할을 합니다. 여기서 href 주소를 보고 찾아 들어가면 됩니다.

---

Step 5. 실무 필수 기능 Best 5 💎

메뉴판에 있는 수많은 기능 중, 실무에서 가장 유용한 것들을 추려봤습니다.

기능 이름	접속 주소	용도
metrics	/actuator/metrics	CPU, 메모리(Heap), 요청 수 등 숫자 데이터 확인
loggers	/actuator/loggers	실시간 로그 레벨 변경 (재시작 없이 DEBUG 모드 켜기)
beans	/actuator/beans	스프링 빈들이 잘 등록되었는지 확인 (디버깅용)
env	/actuator/env	yml 설정값이나 환경 변수 확인
threaddump	/actuator/threaddump	현재 스레드 상태 확인 (서버가 멈췄을 때 원인 분석)

---

🚨 주의사항: 보안 (Security)

Actuator는 개발자에게는 꿀 같은 도구지만, 해커에게는 보물지도입니다.
환경 변수(env)에는 DB 비밀번호나 API 키가 들어있을 수 있기 때문입니다.

따라서 실제 운영(Production) 환경에서는 반드시 Spring Security 등을 이용해 접근을 막아야 합니다.

// 예시: /actuator/health는 누구나, 나머지는 ADMIN 권한만 접근 가능하게 설정
http.authorizeHttpRequests()
    .requestMatchers("/actuator/health").permitAll()
    .requestMatchers("/actuator/**").hasRole("ADMIN")
    ...

---

🎉 마무리

Actuator를 사용하면 내 서버의 건강 상태(Health)와 내부 사정(Metrics, Beans)을 투명하게 들여다볼 수 있습니다.

답답한 로그 파일 대신, Actuator를 장착해서 스마트한 서버 모니터링 환경을 구축해 보세요!