액추에이터 활용하기

김하영·2023년 7월 2일

스프링 부트 핵심 가이드 스터디

목록 보기

8/9

출처: 스프링 부트 핵심 가이드 - 장정우 지음
https://www.aladin.co.kr/shop/wproduct.aspx?ItemId=296591989

어플리케이션을 개발하는 단계를 지나 운영단계에 접어들면 어플리케이션이 정상적으로 동작하는지 모니터링하는 환경을 구축하는 것이 중요해진다.
스프링 부트 엑추에이터는 HTTP 엔드포인트나 JMX를 활용해 어플리케이션을 모니터링하고 관리할 수 있는 기능을 제공한다.
(JMX : 실행중인 어플리케이션의 상태를 모니터링하고 설정을 변경할 수 있게 해주는 API, JMX를 통해 리소스 관리하려면 MBeans를 생성해야 한다.)

액추에이터 종속성 추가

액추에이터 기능을 사용하려면 어플리케이션에 spring-boot-starter-actuator 종속성을 추가해야 한다.

엔드포인트

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

<자주 사용되는 엔드포인트>
https://incheol-jung.gitbook.io/docs/study/srping-in-action-5th/chap-16.#undefined

엔드포인트는 활성화 여부와 노출 여부를 설정할 수 있다.
- 활성화는 기능 자체를 활성화 할것인지 결정하는 것
- 비활성화 된 엔드포인트는 어플리케이션 컨택스트에서 완전히 제거됨
- application.properties파일에 속성을 추가하여 활성화 여부 지정
- 다음은 엔드포인트의 shutdown 기능은 활성화하고 caches기능은 비활성화하겠다는 의미
```
management.endpoint.shutdown.enabled=true
management.endpoint.caches.enabled=false
```
엔드포인트의 노출 여부 설정
- 노출 여부는 JMX를 통한 노출과 HTTP를 통한 노출이 있어 설정이 구분된다.
- 다음은 web과 JMX 환경에서 엔드포인트를 전체적으로 노출하며, 스레드덤프와 힙덤프 기능은 제외하겠다는 의미
```
// 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
```
엔드포인트는 어플리케이션에 관한 민감한 정보를 포함하고 있으므로 노출 설정을 신중하게 고려햏야 한다.
특히 공개적으로 노출되는 어플리케이션이라면 더욱 신중히 고려해서 사용해야 한다.

액추에이터 기능 살펴보기

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

/info 앤드포인트를 활용하면 가동중인 어플리케이션 정보를 볼 수 있다.
제공하는 정보의 범위는 application.properties파일에 info.으로 시작하는 속성값들을 정의하는 것이 가장 쉬운 방법이다.

// application.propertie파일 내에 어플리케이션 정보 속성 작성
info.organization.name=helloworld
info.contact.email=hello@gmail.com
imfo.contact.phoneNumber=010-0000-0000

이러고 나서 어플리케이션 가동 후 브라우저에 http://localhost:8080/actuator/info 에 접근하면 json형식의 작성한 어플리케이션 정보 속성을 확인할 수 있다.

어플리케이션 상태 (/health)

/health 앤드포인트를 활용하면 어플리케이션 상태를 확인할 수 있다.
http://localhost:8080/actuator/health 에 접근하면 된다.
status의 값으로 UP, DOWN, UNKNOWN, OUT_OF_SERVICE 4가지의 상태 지표를 가질 수 있다.
이 결과는 주로 네트워크 계층 중 L4(Loadbalancing)레벨에서 어플리케이션 상태를 확인하기 위해 사용된다.
상세 상태를 확인하고 싶다면 application.properties파일에 다음과 같이 추가하면 된다.

management.endpoint.health.show-details=always

show-details의 설정 값은 다음과 같다
- ㅇㄹ
- never(기본값): 세부사항 표시하지 않음
- when-authorized: 승인된 사용자에게만 세부상태 표시, 확인 권한은 application.properties에 추가한 management.endpoint.health.roles속성으로 부여 가능
- always : 모든 사용자에게 세부상태 표시
만약 어플리케이션에 DB가 연동되어 있다면 인프라 관련 상태까지 확인가능
detail의 모든 status가 UP이어야 어플리케이션의 상태가 UP으로 표시됨, 만약 DOWN상태인 항목이 있다면 어플리케이션의 상태도 DOWN으로 표기되고 HTTP상태코드도 변경된다.

빈 정보 확인 (/beans)

/beans 앤드포인트를 사용하면 스프링 컨테이너에 등록된 스프링빈의 전체 목록을 표시할 수 있다.
json형식으로 빈의 정보 반환 (스프링은 워낙 많은 빈이 자동등록되어 운영되므로 실제 내용을 출력해서 육안으로 내용파악하긴 어려움..)

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

/conditions앤드포인트를 통해 스프링부트의 자동설정(AutoConfiguration) 조건 내역을 확인할 수 있다.
출력내용은 그케 positiveMatches와 negativeMatches 속성으로 구분되는데, 자동 설정의 @Conditional에 따라 평가된 내용을 표시한다.

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

/env 앤드포인트를 통해 스프링 환경변수 정보를 확인할 수 있다.
기본적으로 application.properties 파일의 변수들이 표시되며, OS, JVM의 환경변수도 함께 표시된다.
만약 일부 내용에 포함된 민감한 정보를 가리기 위해서는 management.endpoint.env.keys-to-sanitize 속성을 사용하면 된다. 이 속성에 넣을 수 있는 값은 단순 문자열이나 정규식을 활용한다.

로깅 레벨 확인 (/loggers)

/loggers 엔드포인트로 어플리케이션의 로깅레벨 수준이 어떻게 설정되어 있는지 확인할 수 있다.
POST 메소드로 호출하면 로깅 레벨을 변경하는 것도 가능하다.

액추에이터 커스텀 기능 만들기

액추에이터는 다양한 정보를 가공해서 제공하지만 개발자의 요구사항에 맞춘 커스텀 기능 설정도 제공한다.
커스텀 기능 개발하는 방식에는 기존기능에 내용추가하는 방식, 새로운 엔드포인트를 개발하는 방식 이렇게 두가지가 있다.

정보제공 인터페이스의 구현체 생성

액추에이터를 커스터마이징 하는 가장 간단한 방법은 /info 엔드포인트의 내용을 추가한것처럼 application.properties파일에 내용을 추가하는 것이다.
그러나 이방법은 많은 내용을 담을 때는 관리측면에서 좋지 않다.
그래서 커스텀 기능 설정시에는 별도의 구현체 클래스를 작성해서 내용을 추가하는 방법이 많이 활용된다.
액추에이터에서는 InfoContributor 인터페이스를 제공하는데, 이 인터페이스를 구현하는 클래스를 작성하면 된다.
InfoContributor 인터페이스의 구현체로 설정하면 contribute 메소드를 오버라이딩할 수 있게 된다.
이 메소드의 파라미터인 Builder 객체는 액추에이터 패키지의 Info 클래스 안에 정의되어 있는 클래스로서 Info 앤드포인트에서 보여줄 내용을 담는 역할을 수행한다.
보다시피 기존 applications.properties에서 정의했던 속성값을 비롯해 구현체 클래스에서 포함한 내용이 추가된 것을 볼 수 있다.

커스텀 엔드포인트 생성

@EndPoint 어노테이션으로 빈에 추가된 객체들을 @ReadOperation, @WriteOperation, @DeleteOperation어노테이션을 사용해 JMX나 HTTP를 통해 커스텀 엔드포인트를 노출시킬 수 있다.
만약 JMX에서만 사용하거나 HTTP에서만 사용하는 것으로 제한하고 싶다면 @JmxEndpoint, @WebEndPoint 어노테이션을 사용하면 된다.
다음은 어플리케이션에 메모기록을 남길 수 있는 기능을 엔드포인트로 생성하는 예시이다.
@EndPoint 어노테이션을 통해 액추에이터에 엔드포인트로 자동 등록되도록 한다.
id 속성값으로 경로를 정의한다.
또한 enableByDefault 속성으로 현재 생성하는 앤드포인트의 기본 활성화 여부도 설정가능하다. 기본값은 true로서, 별도로 지정하지 않으면 활성화 된다.
@ReadOperation, @WriteOperation, @DeleteOperation어노테이션으로 동작 메소드를 생성할 수 있다.
- @ReadOperation : HTTP GET 요청에 반응하는 메소드
- @WriteOperation : HTTP POST 요청에 반응하는 메소드, 메소드에서 받고자 하는 파라미터의 이름을 JSON의 키 값으로 설정하고 호출!
- @DeleteOperation : DELETE호출을 통해 사용, Query Parameter에 값을 넣어 호출!!
  
  스프링 부트 액추에이터의 자세한 내용은 공식 홈페이지에서 확인하자!
  https://docs.spring.io/spring-boot/docs/current/reference/html/actuator.html