스프링부트 핵심 가이드(장정우 지음) - 예외 처리 에러 해결, 액추에이터 활용하기

*책 내용과 다르게, 다음과 같은 환경에서 프로젝트 생성  

• Windows11(윈도우 11) 환경
• 자바 JDK 17 버전 설치 https://yungenie.tistory.com/11

• 스프링 부트 4.31.0 사용 - STS(Spring Tool Suite) 설치(Spring Tools for Eclipse - https://spring.io/tools)
  => https://priming.tistory.com/147 참고

• MySQL Community Server 8.0.42 설치 https://dev.mysql.com/downloads/mysql/

• Gradle

**STS에서 Gradle 프로젝트 생성한 과정 

*** 함께 보면 좋은 글

2025.07.10 - [스프링(Spring), 스프링부트(SpringBoot)/스프링부트(SpringBoot) 기초] - 스프링 부트 핵심 가이드(장정우 지음) - 스프링 부트 개요

스프링 부트 핵심 가이드(장정우 지음) - 스프링 부트 개요

2025.07.11 - [스프링(Spring), 스프링부트(SpringBoot)/스프링부트(SpringBoot) 기초] - 스프링 부트 핵심 가이드(장정우 지음) - 개발에 앞서 알면 좋은 기초 지식

스프링 부트 핵심 가이드(장정우 지음) - 개발에 앞서 알면 좋은 기초 지식

 

0. 지난 예외 처리 에러 해결

• 윈도우의 '서비스'에 들어가서 'MySQL8'을 다시 시작하고, STS에서 서버를 재시작했더니 http://localhost:8080/swagger-ui/index.html에 접속 및 결과 확인이 됩니다...

윈도우의 '서비스'에 들어가서 'MySQL8'을 다시 시작

STS에서 서버 재시작

http://localhost:8080/swagger-ui/index.html 접속 및 결과 확인

1. 액추에이터 개요

• 애플리케이션을 개발하는 단계를 지나 운영 단계에 접어들면, 애플리케이션이 정상 동작하는지 모니터링하는 환경을 구축하는 것이 매우 중요
  -> 이때 HTTP 엔드포인트나 JMX를 활용해 애플리케이션을 모니터링하고 관리할 수 있는 기능 제공

*JMX(Java Management Extensions)

• 실행 중인 애플리케이션의 상태를 모니터링하고 설정을 변경할 수 있게 해주는 API
• 이를 통해 리소스 관리를 하려면 MBeans(Managed Beans)를 생성해야 함 

2. 프로젝트에 액추에이터 종속성 추가

build.gradle에 의존성 추가 및 저장한 후 우클릭 -> Gradle -> Refresh Gradle Project 선택

dependencies {
    ... 생략 ...
    // 액추에이터
    implementation 'org.springframework.boot:spring-boot-starter-actuator'
}

build.gradle 저장한 후 우클릭 -> Gradle -> Refresh Gradle Project 선택

3. 액추에이터의 엔드포인트

• 애플리케이션의 모니터링을 사용하는 경로를 의미
• 스프링부트에는 여러 내장 엔드포인트가 포함되어 있는데, 커스텀 엔드포인트를 추가할 수도 있음
• 액추에이터를 추가하면 기본적으로 엔드포인트 URL로 /actuator가 추가되며, 이 뒤에 경로를 추가해 상세 내역에 접근 가능
  -> 다른 경로를 사용하고 싶다면 application.properties 파일에 다음과 같이 작성

management.endpoints.web.base-path=/custom-path

 

1) 액추에이터의 기본 엔드포인트 리스트

*내가 이해 안되는 용어 정리

• conditions(조건): @Conditional...으로 시작하는 어노테이션들을 통해, 특정 조건에서만 Bean 등록 or 기능 활성화 가능
• @ConfigurationProperties: 애플리케이션 설정값(application.yml 또는 application.properties에 작성)을 객체로 바인딩
• 스프링 통합 그래프(Spring Integration Graph): 스프링 통합(Spring Integration)에서 메시지 흐름을 시각화한 그래프
  -> 채널, 게이트웨이, 엔드포인트 간 데이터 흐름을 한눈에 볼 수 있음. 쉽게 말하면 메시지 교통지도
  => 채널(Channel): 메시지가 지나가는 "통로"
       게이트웨이(Gateway): 외부 코드(서비스, 컨트롤러 등)가 메시지 시스템과 상호작용할 수 있도록 해주는 "입구"
       엔드포인트(Endpoint): 메시지를 받아서 실제 작업을 수행하는 "처리기"
• 애플리케이션의 매트릭 정보(Metrics): CPU, 메모리, HTTP 요청 수, DB 커넥션 풀 상태 등의 운영 지표
• Quartz: 자바 기반 스케줄러 라이브러리로, '크론 표현식'으로 예약 작업을 실행
  (예시: 매일 새벽 3시에 데이터 정리 작업, 5분마다 캐시 갱신, 매일 특정 시간에 이메일 발송)
• 애플리케이션에서 예약된 작업: @Scheduled 어노테이션이나 Quartz 등의 스케줄러로 등록된 작업들
• 스프링 세션을 사용하는 서블릿 기반 웹 애플리케이션
  : 기본적으로 스프링은 톰캣 같은 서블릿 컨테이너에서 세션을 관리하지만, 스프링 세션을 쓰면 Redis 등 외부 저장소에 세션 저장 가능
  -> 분산 환경에서 세션 공유가 필요할 때 유용
• BufferingApplicationStartup: 스프링부트 2.4부터 도입된 애플리케이션 시작 성능 분석 도구
  -> 애플리케이션이 시작될 때 어떤 Bean이 언제 초기화되는지 기록해서 성능 병목을 찾을 수 있음
• 애플리케이션이 시작될 때 수집된 시작 단계 데이터: BufferingApplicationStartup이 수집한 데이터
  -> 어떤 Bean이 몇 ms 걸려서 초기화됐는지, 어떤 순서로 실행됐는지 확인
• 스레드 덤프(Thread Dump): JVM에서 실행 중인 모든 스레드 상태를 찍어낸 것
  -> 데드락, 무한 루프, 성능 문제를 진단할 때 사용 

ID	설명
auditevents	호출된 Audit 이벤트 정보를 표시 AuditEventRepository 빈 필요
beans	애플리케이션에 있는 모든 스프링 빈 리스트를 표시
caches	사용 가능한 캐시 표시
conditions	자동 구성 조건 내역을 생성
configprops	@ConfigurationProperties의 속성 리스트를 표시
env	애플리케이션에서 사용할 수 있는 환경 속성을 표시
health	애플리케이션의 상태 정보를 표시
httptrace	가장 최근에 이뤄진 100건의 요청 기록 표시 HttpTraceRepository 빈 필요
info	애플리케이션의 정보 표시
integrationgraph	스프링 통합 그래프 표시 spring-integration-core 모듈에 대한 의존성 추가 필수
loggers	애플리케이션의 logger 구성을 표시하고 수정
metrics	애플리케이션의 매트릭 정보 표시
mappings	모든 @RequestMapping의 매핑 정보 표시
quartz	Quartz 스케줄러 작업에 대한 정보 표시
scheduledtasks	애플리케이션에서 예약된 작업 표시
sessions	스프링 세션 저장소에서 사용자의 세션을 검색하고 삭제 스프링 세션을 사용하는 서블릿 기반 웹 애플리케이션이 필요
shutdown	애플리케이션 정상 종료(기본값은 비활성화 상태)
startup	애플리케이션이 시작될 때 수집된 시작 단계 데이터 표시 BufferingApplicationStartup으로 구성된 스프링 애플리케이션이 필요
threaddump	스레드 덤프를 수행

 

2) Spring MVC, Spring WebFlux, Jersey 사용 시 추가 엔드포인트 리스트

*내가 이해 안되는 용어 정리

• 힙 덤프(Heap Dump): JVM 메모리(힙)에 어떤 객체들이 얼마나 차지하고 있는지 그대로 찍어낸 스냅샷
  -> 메모리 누수나 OutOfMemoryError 문제를 분석할 때 사용
• 핫스팟(HotSpot) VM: Oracle/OpenJDK에서 제공하는 가장 널리 쓰이는 JVM 구현체
  -> JIT 컴파일러를 통해 자바 바이트코드를 네이티브 코드로 최적화 실행
• hprof 포맷: HotSpot JVM이 힙 덤프를 저장할 때 쓰는 기본 파일 포맷
  -> hprof 파일을 Eclipse MAT 같은 툴로 열어 분석 가능
• OpenJ9 JVM: IBM이 만든 대체 JVM 구현체
  -> 메모리 사용량이 적고, 클라우드 환경에서 효율적
• PHD 포맷: OpenJ9 JVM이 힙 덤프를 저장할 때 사용하는 포맷
  -> .phd 파일을 IBM HeapAnalyzer 같은 도구로 열어 분석
• jolokia의 필요성 : JMX(Java Management Extensions)를 HTTP(JSON)로 노출해주는 에이전트
  -> JMX는 원래 RMI 기반이라 접근이 불편한데, Jolokia 덕분에 REST API처럼 쉽게 모니터링 가능
  => 예시: JVM 메트릭을 브라우저나 curl로 바로 조회.
• prometheus: 오픈소스 모니터링 시스템, Prometheus 모니터링 시스템과 직접 연동하기 위한 Exporter 엔드포인트이기에 대문자로 시작함 
  -> 애플리케이션이 노출하는 메트릭을 주기적으로 수집(scraping)하고 시계열 데이터베이스에 저장
  => Grafana 같은 시각화 툴과 함께 쓰면 CPU, 메모리, 요청 수 등을 대시보드로 확인 가능

ID	설명
heapdump	힙 덤프 파일 반환 핫스팟(HotSpot) VM 상에서 hprof 포맷 파일이 반환되며, OpenJ9 JVM에서는 PHD 포맷 파일 반환
jolokia	Jolokia가 클래스패스에 있을 때 HTTP를 통해 JMX 빈 표시 jolokia-core 모듈에 대한 의존성 추가 필요 WebFlux에서는 사용 불가
logfile	logging.file.name 또는 logging.file.path 속성이 설정되어 있으면 로그 파일의 내용 반환
Prometheus	Prometheus 서버에서 스크랩할 수 있는 형식으로 매트릭 표시 micrometer-registry-prometheus 모듈의 의존성 추가 필요

 

3) 엔드포인트 활성화 및 노출 설정

(1) 엔드포인트 활성화 설정 예시

# application.properties

# shutdown 기능 활성화
management.endpoint.shutdown.enabled=true
# caches 기능 비활성화
management.endpoint.caches.enabled=false

(2) 엔드포인트 노출 설정 예시

# application.properties

# HTTP 설정
# web 환경에서 엔드포인트 전체적으로 노출
management.endpoints.web.exposure.include=*
# web 환경에서 엔드포인트 중 스레드 덤프와 힙 덤프 제외
management.endpoints.web.exposure.exclude=threaddump, heapdump

# JMX 설정
# JMX 환경에서 엔드포인트 전체적으로 노출
management.endpoints.jmx.exposure.include=*
# JMX 환경에서 엔드포인트 중 스레드 덤프와 힙 덤프 제외
management.endpoints.jmx.exposure.exclude=threaddump, heapdump

 

* 엔드포인트 노출 설정 기본값

• Web과 JMX의 기본 노출 설정이 다른 이유는 보안성과 사용 목적 때문
  -> 대부분의 운영 환경에서는 Web 기반 모니터링 툴을 붙여서 필요한 엔드포인트만 열고, JMX는 내부 관리/디버깅
  => Web은 외부 HTTP 요청을 통해 접근되므로 기본적으로 최소한의 엔드포인트만 노출(health, info)하고,
      JMX는 JVM 내부 관리용이기 때문에 더 많은 엔드포인트를 기본적으로 노출
• auditevents: 보안이나 중요한 상태 변화와 관련된 이벤트를 기록하고, 액추에이터를 통해 확인
• liquibase: 데이터베이스 스키마 변경을 코드로 관리하고, 자동으로 적용/추적/롤백할 수 있는 도구로, 
  엔드포인트에 사용 시 현재 DB에 적용된 Liquibase ChangeSet들의 상태를 보여주는 것

ID	JMX	WEB
auditevents	O	X
beans	O	X
caches	O	X
conditions	O	X
configprops	O	X
env	O	X
flyway	O	X
health	O	O
heapdump	해당 없음	X
httptrace	O	X
info	O	X
integrationgraph	O	X
jolokia	해당 없음	X
logfile	해당 없음	X
loggers	O	X
liquibase	O	X
metrics	O	X
mappings	O	X
Prometheus	해당 없음	해당 없음
quartz	O	X
scheduledtasks	O	X
sessions	O	X
shutdown	O	X
startup	O	X
threaddump	O	X