ch11. 액추에이터 활용하기

액추에이터란?

애플리케이션을 개발하는 단계를 지나 운영 단계가 되면,
정상 작동을 모니터링하는 환경 구축이 매우 중요하다!

스프링 부트 액추에이터는 'HTTP 엔드포인트'나 'JMX'를 활용해
애플리케이션을 모니터링하고 관리할 수 있는 기능을 제공한다!

즉, 서비스를 시행하고 이를 유지 보수 하는 차원을 다루는 것이
11장의 액추에이터 활용하기 주로 다루는 내용이다.

의존성 추가
Maven

<dependency>
	<groupId>org.springframework.boot</groupId>
	<artifactId>spring-boot-starter-actuator</artifactId>
</dependency>

Gradle

compile "org.springframework.boot:spring-boot-starter-actuator"

JMX란?

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

엔드포인트란

액추에이터 엔드포인트는 애플리케이션의 모니터링을 사용하는 경로.
스프링 부트에 여러 내장 엔드포인트가 포함돼 있으며, 커스텀 엔드포인트를 추가할 수도 있다.
기본적으로는 /actuator로 경로가 추가되며 이 경로로 상세 내역을 접근 하지만,
커스텀을 원한다면 application.properties(resource에 위치함)에 접근해
management.endpoints.web.base-path=/custom-path(원하는 경로) 로 만들 수도 있다.

application.yml의 경우

management:
  endpoints:
    web:
      base-path: /management

이 중에 서적에서는 자주 활용되는 엔드포인트 리스트가 정리되어 있다.

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

만약, SprigMVC, Spring WebFlux, Jersey를 사용하면
추가로 다음과 같은 엔드 포인트도 사용 가능

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

또한 엔드포인트는 활성화와 노출 여부를 설정할 수 있다.
이는 기본적으로는 활성화이지만,
만약, 비활성화를 하면, 엔드포인트는 애플리케이션 컨텍스트에서 완전히 제거 된다.

properties에 다음과 같이 설정을 해주면 활성화/ 비활성화, 노출 설정가 된다.

management.endpoint.shutdown.enabled = true; ##shutdown 기능은 활성화
management.endpoint.caches.enabled = false; ##caches는 비활성화
management.endpoints.web.exposure.inclued=*
management.endpoints.web.expousre.exclued=number, address
management.endpoints.jmx.exposure.inclued=*
management.endpoints.jmx.expousre.exclued=number, address

yml의 경우

management:
 endpoint: 
  shutdown:
   enabled: true ##default
 endpoint: 
  caches:
   enabled: false  
 endpoints:
  web:
   exposure:
    include: '*'
    exclude: number, address 
 endpoints:
  jmx:
   exposure:
    include: '*'
    exclude: number, address  

include: '*'##전체를 노출하겠다는 의미로 문제가 될 수 있음
exclude: number, address
특정 경로를 제외하고 보여주겠다는 의미 이 경우, number, address

위와 같이 작성할 수 있다.
yml의 경우 어떻게 작성해야 하는지 막막할 때가 있어서,
특히, 들여쓰기 위주다 보니 같이 정리하기로 했다.

jmx의 설정값과 web의 설정값도 모두 써 놓았는데, 위에서 언급한 것처럼.
*의 경우 문제가 될 수도 있기에 팀 내에서 충분히 해당 내용을 논의하고
잘 인지할 필요가 있다.

엔드 포인트의 노출 설정값은 아래와 같은데, 뭐 크게 의미가 있나 싶긴 하다?

ID	JMX	WEB
auditevents	O	X
beans	O	X
caches	O	X
conditions	O	X
configprops	O	X
env	O	X
heapdump	해당 없음	X
health	O	X
httptrace	O	X
info	O	X
integrationgraph	O	X
jilokia	해당 없음	X
logfile	해당 없음	X
loggers	O	X
metrics	O	X
mapping	O	X
Prometheus	해당 없음	X
quartz	O	X
scheduledtasks	O	X
sessions	O	X
shutdown	O	X
startup	O	X
threeaddump	O	X

이제 본격적으로 액추에이터의 기능을 살펴보도록 하자!

액추에이터의 기능(모니터링은 어떻게 하나요!)

사실 책에서 소개하는 게 크진 않다. 총 6가지로!
/info /health /beans /conditions /env /loggers와
커스텀 기능을 만드는 걸 소개하는 것이 11장의 내용의 큰 틀이다.(그래서 12장도 함께하는)

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

액추에이터의 /info 엔드포인트는 가동 중인 애플리케이션의 정보를 볼 수 있다.
제공 정보 범위가 애플리케이션에서 몇 가지 방법을 거쳐 제공할 수도 있지만,
application.properties 파일에 'info.'로 시작하는 속성 값들을 정의하는 것이 가장 쉬운 방법이다.

아래와 같이 작성하면 된다.

info.organization.name=wikibooks
info.contact.email=thinkground.example@gmail.com
info.contact.phoneumber=010-1111-2222

yml의 경우

info:
  organization:
    name: wikibooks
  contact:
    phoneumber: 010-1111-2222
    email: thinkground.example@gmail.com

위와 같이 작성하고

localhost:8080/actuator/info

로 접근하면 Json 형태로 값이 나오는 걸 확인할 수 있다.

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

/health 엔드포인트를 활용하면 애플리케이션의 상태를 확인 가능하다.
별도의 설정 없이 다음 UR로 접근하면 된다.

localhost:8080/actuator/health

호출결과는 {"status" : "UP"}과 같이 나온다.
아래와 같은 상태지표 총 4가지가 있다.

• UP
• DOWN
• UNKNOWN
• OUT_OF_SERVICE

이는 주로 네트워크 계층 중 L4(Loadbalancing)레벨에서
애플리케이션의 상태를 확인하기 위해 사용된다.
상세 상태를 확인하려면 properties에 아래와 같은 추가가 필요하다

management.endpoint.health.show-detail=always

yml의 경우

management:
  endpoint:
    health:
      show-detail: always

를 추가하면 된다.

여기서 show-detail에 설정할 수 있는 값에는 아래와 같은 3가지가 있다.

• never(기본값) 세부 사항은 표시 X
• when-authorized: 승인된 사용자에게만 세부 상태 표시. 확인권한 추가한 management.endpoint.health.roles 속성으로 부여.
• always : 모든 사용자에게 세부 상태 표시.

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

액추에이터 /beans 엔드포인트를 사용하면 스프링 컨테이너에 등록된 스프링 빈의 전체 목록을 표시할 수 있다. 이 엔드포인트는 JSON 형식으로 빈의 정보를 반환한다.
다만, 스프링은 워낙 많은 빈이 자동으로 등록되다 보니,
실제로, 내용을 출력해서 육안으로 내용을 파악하기는 어려움.

이것도 별도의 설정이 필요한 건 아니고,

localhost:8080/actuator/beans 

위와 같이 작성하면 끝!

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

스프링 부트 자동설정(AutoConfiguration) 조건 내역을 확인하려면,
/conditions 엔드포인트를 사용.

localhost:8080/actuator/conditions 

위와 같이 작성하면 끝!
출력 내용에서 주목할 만한 부분은
positiveMathces와 negativeMatches 속성.
자동설정의 @Conditional에 따라 평가된 내용을 표시.

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

/env 엔드포인트는 스프링의 환경변수 정보를 확인하는데 사용.
기본적으로 applcation.properties(yml)파일이 표시,
OS, JVM 의 환경변수도 함께 표시.

localhost:8080/actuator/env

위와 같이 작성하면 끝!
만약, 일부 민감한 내용을 가리기를 원한다면 아래의 속성 사용.

management.endpoint.env.keys-to-sanitize

해당 속성에 넣을 수 있는 값은 단순 문자열이나 정규식 활용

management:
  endpoint:
    env:
      keys-to-sanitize: ''

yml의 경우 위와 같이 작성

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

마지막 logger 역시 아래와 같이 작성하면 끝이다.

localhost:8080/actuator/loggers

기본적으로 애플리케이션 로깅 레벨 수준이 어떻게 설정을 확인하려면,
/loggers 엔드포인트를 사용. 매우 긴 내용이 나오며,
GET,POST 형식으로 로깅레벨을 바꿀 수도 있음.

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

커스텀 기능을 만드는 방식에는 크게 2가지가 있다.
1. 기존 기능에 내용 추가
2. 새로운 엔드포인트를 개발

1. 기존 기능에 내용 추가

처음에 info에 한 것처럼 설정값을 추가하는 방식이다.
하지만, 이건 여러가지를 담을 수는 없기에
구현체, class를 별도로 만들어 주는 것이 좋다.

그리고 여기에 InfoContributor 인터페이스를 구현하는 형태로 제작하면
다양한 기능을 구현할 수 있다.

2. 새로운 엔드포인트를 개발

@EndPoint 이 어노테이션을 사용해 빈에 추가하면,
객체들은 @ReadOperation, @WriteOperation, @DeleteOperation
어노테이션을 사용해 JMX 나 HTTP를 통해 커스텀 엔드포인트를 노출 시킬 수 있다.
만약 JMX에서만 사용하거나 HTTP에서만 사용하는 것으로
제한하고 싶다면,
@JmxEndpoint나 @WebEndpoint와 같은 어노테이션을 사용하자.