액추에이터 활용하기

애플리케이션을 개발하는 단계를 지나 운영 단계에 접어들면 애플리케이션이 정상적으로 동작하는지 모니터링하는 환경을 구축하는 것이 중요하다. 스프링 부트 액추에이터는 HTTP 엔드포인트나 JMX를 활용해 애플리케이션을 모니터링하고 관리할 수 있는 기능을 제공한다.

 

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

 

1 엔드포인트

 

액추에이터의 엔드포인트는 애플리케이션의 모니터링을 사용하는 경로이다. 스프링 부트에는 여러 내장 엔드포인트가 포함돼 있으며, 커스텀 엔드포인트를 추가할 수도 있다.

액추에이터를 추가하면 기본적으로 엔드포인트 URL로 actuator가 추가되며 이 뒤에 경로를 추가해 상세 내역에 접근한다.

 

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

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

 

엔드포인트는 활성화 여부와 노출 여부를 설정할 수 있다. 활성화 기능 자체를 활성화할 것인지를 결정하는 것으로, 비활성화된 엔드포인트는 애플리케이션 컨텍스트에서 완전히 제거된다. 엔드포인트를 활성화하려면 application.properties 파일에 속성을 추가하면 된다.

## 엔드포인트 활성화
management.endpoint.shutdown.enabled=true
management.endpoint.caches.enabled=false

 

위 예제는 엔드포인트의 shutdown 기능을 활성화하고, caches 기능은 비활성화한다는 의미이다.

 

또한 액추에이터 설정을 통해 엔드포인트의 노출 여부만 설정하는 것도 가능하다. 노출 여부는 JMX를 통한 노출과 HTTP를 통한 노출이 있어 아래 예제와 같이 구분할 수 있다.

## 엔드포인트 노출 설정
## HTTP 설정
management.endpoints.web.exposure.include=*
management.endpoints.web.exposure.exclude=threaddump, heapdump

## JMX 설정
management.endpoints.jmx.exposure.include=*
management.endpoints.jmx.exposure.exclude=threaddump, heapdump

위 설정은 web과 jmx 환경에서 엔드포인트를 전체적으로 노출하고, 스레드 덤프와 힙 덤프 기능은 제외한다는 의미이다.

 

엔드포인트는 애플리케이션에 관한 민감한 정보를 포함하고 있으므로 노출 설정을 신중하게 고려해야 한다.

 

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

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	해당 없음	X
quartz	O	X
scheduledtasks	O	X
sessions	O	X
shutdown	O	X
startup	O	X
threaddump	O	X

 

1.1 애플리케이션 기본 정보(/info)

 

엑추에이터의 /info 엔드포인트를 활용하면 가동 중인 애플리케이션의 정보를 볼 수 있다.

## 엑추에이터 info 정보 설정
info.organization.name=wikibooks
info.concat.email=thinkgroud.flature@gamil.com
info.concat.phoneNumber=010-1234-5678

위처럼 application.properties를 설정한 후, 'http://localhost:8080/acturator/info'에 접근하면 결괏값을 확인할 수 있다.

 

1.2 애플리케이션 상태(/health)

 

/health 엔드포인트를 활용하여 애플리케이션의 상태를 확인할 수 있다. 별도의 설정이 필요하지 않고 'http://localhost:8080/acturator/health'에 접근하여 확인할 수 있다.

 

1.3 빈 정보 확인(/beans)

 

엑추에이터의 /beans 엔드포인트를 사용하면 스프링 컨테이너에 등록된 스프링 빈의 전체 목록을 표시할 수 있다. 이 엔드포인트는 JSON 형식으로 빈의 정보를 반환한다. 다만, 스프링은 많은 빈이 자동으로 등록되어 운영되기 때문에 실제로 내용을 출력하여 내용을 파악하기는 어렵다. 'http://localhost:8080/acturator/beans'에 접근하여 확인할 수 있다.

 

1.4 스프링 부트의 자동설정 내역 확인(/conditions)

 

스프링 부트의 자동설정(AutoConfiguration) 조건 내역을 확인하려면 /conditions 엔드포인트를 사용한다. 'http://localhost:8080/acturator/conditions'에 접근하여 확인할 수 있다.

 

1.5 스프링 환경변수 정보(/env)

 

/env 엔드포인트를 사용하여 스프링의 환경변수 정보를 확인할 수 있다. 기본적으로  application.poperties 파일의 변수들이 표시되며, OS, JMV의 환경변수도 함께 표시된다. 'http://localhost:8080/acturator/env'에 접근하여 확인할 수 있다.

만약, 민감한 정보를 표시하지 않기 위해서는 management.endpoint.env.keys-to-sanitize 속성을 사용하면 된다. 해당 속성에는 단순 문자열이나 정규식을 활용한다.

 

1.6 로깅 레벨 확인(/loggers)

 

/loggers 엔드포인트를 사용하여 애플리케이션의 로깅 레벨 수준이 어떻게 설정돼 있는지 확인할 수 있다. 'http://localhost:8080/acturator/loggers'에 접근하여 확인할 수 있다.

 

 

 

 

 

출처: 이 글의 출처는 책 '스프링 부트 핵심 가이드'를 참고하여 작성하였습니다.

https://www.yes24.com/Product/Goods/110142898