📖 스프링 부트 핵심 가이드
: 스프링 부트를 활용한 애플리케이션 개발 실무
📝 목차
11장. 액추에이터 활용하기
11-1. 프로젝트 생성 및 액추에이터 종속성 추가
11-2. 엔드포인트
11-3. 액추에이터 기능 살펴보기
- 애플리케이션 기본 정보(/info)
- 애플리케이션 상태(/health)
- 빈 정보 확인(/beans)
- 스프링 부트의 자동설정 내역 확인(/conditions)
- 스프링 환경변수 정보(/env)
- 로깅 레벨 확인(/loggers)
11-4. 액추에이터 커스텀 기능 만들기
- 정보 제공 인터페이스 구현체 생성
- 커스텀 엔트포인트 생성
11장. 액추에이터 활용하기
스프링 부트 액추에이터는 HTTP 엔드포인트나 JMX를 활용해 애플리케이션을 모니터링하고 관리할 수 있는 기능을 제공한다.
액추에이터의 환경을 설정하고 활용하는 방법을 다뤄보자
- JMX (Java Management Extensions) 란?
실행 중인 애플리케이션의 상태를 모니터링하고 설정을 변경할 수 있게 해주는 API
11-1. 프로젝트 생성 및 액추에이터 종속성 추가
액추에이터 기능을 사용하려면,
애플리케이션에 spring-boot-starter - actuauor 모듈의 종속성을 추가하기
- Maven : pom.xml 파일에 의존성 추가
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-actuator</artifactId>
</dependency>
</dependencies>- Gradle : build.gradle에 의존성 추가
implementation 'org.springframework.boot:spring-boot-starter-actuator'11-2. 엔드포인트
: 애플리케이션의 모니터링을 사용하는 경로
스프링부트에는 여러 내장 엔드포인트가 포함돼있고, 커스텀 엔드포인트를 추가할 수 있다. 기본적으로 엔드포인트 URL로 /actuator 가 추가된다.
다른 경로를 사용하고 싶다면 application.properties에 다음과 같이 작성한다.
⬇️ 액추에이터 엔드포인트의 기본 경로 변경
management.endpoints.web.base-path=/custom-path⬇️ 자주 활용되는 액추에이터 엔드포인트 리스트
✅ 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 : 스레드 덤프를 수행한다.⬇️ Spring MVC, Spring WebFlux, Jersey을 사용한다면 추가로 사용 가능
✅ 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에 다음과 같은 방법으로 속성을 추가하면 된다.
⬇️ 엔드포인트 활성화 설정
## 엔드포인트의 shutdown 기능은 활성화, caches 기능은 비활성화
management.endpoint.shutdown.enabled=true
management.endpoint.caches.enabled=false- 노출 여부 : JMX를 통한 노출과 HTTP를 통한 노출이 존재
⬇️ 엔드포인트 노출 설정
## web과 jmx 환경에서 엔드포인트를 전체적으로 노출하며,
스레드 덤프(thread dump)와 힙 덤프(heap dump) 기능은 제외
## 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⭐ 엔드포인트는 애플리케이션에 관한 민감한 정보를 포함하고 있으므로,
노출 설정을 신중하게 고려해야한다.
11-3. 액추에이터 기능 살펴보기
액추에이터를 활성화 + 노출 지점도 설정 = 애플리케이션에서 기능 사용 가능
기능 추가 없이 액추에이터 설정만으로 볼 수 있는 기능 위주로 설명
애플리케이션 기본 정보(/info)
: 가동 중인 애플리케이션 정보를 볼 수 있다.
application.properties에 'info.'로 시작하는 속성 값들을 정의하는 방법
## 액추에이터 info 정보 설정
info.organization.name=wikibooks
info.contact.email=thinkground.flature@gmail.com
info.contact.phoneNumber=010-1234-5678속성 값을 정의한 후 애플리케이션을 가동 ➡️ 브라우저에서 url로 접근 ➡️ JSON 형태로 출력된 결과 확인 가능
애플리케이션 상태(/health)
: 애플리케이션의 상태를 확인할 수 있다.
-
별도의 설정 없이 url접근 ➡️ 상태지표 확인 가능
(상태지표 : UP , DOWN , UNKNOWN , OUT_OF_SERVICE)네트워크 계층 중 L4레벨에서 애플리케이션의 상태를 확인을 위해 사용
-
상세 상태 확인을 원하면
application.properties속성 추가하기
⬇️ 액추에이터 health 상세 내역 활성화
management.endpoint.health.show-detail=alwaysshow-detail속성에서 설정할 수 있는 값
✅ never(기본값)
: 세부 사항 표시 안 함
✅ when-authorized
: 승인된 사용자에게만 세부 상태 표시
확인 권한은 application.properties에 추가한
management.endpoint.health.roles 속성으로 부여할 수 있다.
✅ always : 모든 사용자에게 세부 상태 표시빈 정보 확인(/beans)
: 스프링 컨테이너에 등록된 스프링 빈의 전체 목록을 표시할 수 있다.
스프링 부트의 자동설정 내역 확인(/conditions)
: 스프링 부트의 자동설정 조건 내역을 확인할 수 있다.
스프링 환경변수 정보(/env)
: 스프링의 환경변수 정보를 확인하는데 사용한다.
로깅 레벨 확인(/loggers)
: 애플리케이션 로깅 레벨 수준이 어떻게 설정되어 있는지 확인할 수 있다.
11-4. 액추에이터 커스텀 기능 만들기
: 커스텀 기능을 개발하는 방식에는 크게 두 가지가 존재
1. 기존 기능에 내용을 추가하는 방식
2. 새로운 엔드포인트를 개발하는 방식
정보 제공 인터페이스 구현체 생성
-
application.properties파일 내에 내용 추가하는 방법
➡️ 많을 내용을 담을 때는 관리 측면에서 좋지 않음 -
별도의 구현체 클래스를 작성해서 내용을 추가하는 방법
액추에이터에서 제공하는 InfoContributor 인터페이스에 별도 구현체 클래스를 작성해서 내용을 추가하는 방법이 많이 활용된다.
커스텀 엔트포인트 생성
@Endpoint 어노테이션으로 빈에 추가된 객체들은
@ReadOperation, @WriteOperation, @DeleteOperation 어노테이션을 사용해 JMX나 HTTP를 통해 커스텀 엔드포인트를 노출시킬 수 있다.
JMX에서만 사용하거나 HTTP에서만 사용하는 것으로 제한하고 싶다면, @JmxEndpoint, @WebEndpoint 어노테이션을 사용하면 된다.
