[스프링 인 액션] 16. 스프링 부트 액추에이터 사용하기

김하영·2021년 8월 26일

Spring

이 장에서 배우는 내용
스프링 부트 프로젝트에 액추에이터 활성화하기
액추에이터 엔드포인트 살펴보기
액추에이터 커스터마이징
액추에이터 보안 처리하기

16.1 액추에이터 개요

액추에이터는 실행 중인 애플리케이션의 내부를 볼 수 있게 하고,
어느 정도까지는 애플리케이션의 작동 방법을 제어할 수 있게 한다.

예를 들면, 다음과 같다.

애플리케이션 환경에서 사용할 수 있는 구성 속성들
애플리케이션에 포함된 다양한 패키지의 로깅 레벨(logging level)
애플리케이션이 사용 중인 메모리
지정된 엔드포인트가 받은 요청 횟수
애플리케이션의 건강 상태 정보

스프링 부트 애플리케이션에 액추에이터를 활성화하려면 의존성을 빌드에 추가해야 한다.

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

액추에이터 스타터가 프로젝트 빌드의 일부가 되면 애플리케이션에서 여러 가지 액추에이터 엔드포인트를 사용할 수 있다.

[ 실행 중인 스프링 부트 애플리케이션의 내부 상태를 볼 수 있는 엑추에이터 앤드포인트 ]

16.1.1 액추에이터의 기본 경로 구성하기

엑추에이터의 모든 엔드포인트의 경로에는 /actuator가 앞에 붙는다.
액추에이터의 기본 경로는 management.endpoint.web.base-path 속성을 설정하여 변경할 수 있다.

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

16.1.2 액추에이터 엔드포인트의 활성화와 비활성화

액추에이터를 추가하면 /health와 /info 엔드포인트만 기본적으로 활성화되는 것을 알 수 있다.
대부분의 액추에이터 엔드포인트는 민감한 정보를 제공하므로 보안 처리가 되어야 하기 때문이다.
물론 스프링 시큐리티를 사용해서 액추에이터를 보안 처리할 수 있다.
그러나 액추에이터 자체로는 보안 처리가 되어 있지 않으므로 대부분의 엔드포인트가 기본적으로 비활성화되어 있다.

엔드포인트의 노출 여부를 제어할 때는 management.endpoints.web.exposure.include(활성화)와 management.endpoints.web.exposure.exclude(비활성화) 구성 속성을 사용할 수 있다.

management:
  endpoints:
    web:
      exposure:
        include: health,info,beans,conditions
        exclude: threaddump, heapdump

16.2 액추에이터 엔드포인트 소비하기

16.2.1 애플리케이션 기본 정보 가져오기

애플리케이션에 관한 정보 요구하기 (info)

실행 중인 스프링 부트 애플리케이션에 관한 정보를 알려면 /info 앤드포인트에 요구하면 된다.
/info 엔드포인트가 반환하는 정보를 제공하는 방법은 몇 가지가 있다.
이중 이름이 info.으로 시장하는 하나 이상의 구성 속성을 생성하는 것이 가장 쉬운 방법이다.

info:
  contact:
    email: support@tacocloud.com
    phone: 822-625-6831

속성 이름이 info. 으로 시작하므로 이제는 /info 엔드포인트가 다음과 같이 응답한다.

{
  "contact": {
    "email": "support@tacocloud.com"
    "phone": "822-625-6831"
	}
}

애플리케이션의 건강 상태 살펴보기 (health)

/health 엔드포인트에 HTTP GET 요청을 하면 애플리케이션의 건강 상태 정보를 갖는 간단한 JSON 응답을 받는다.

$ curl localhost:8080/actuator/health

{"status":"up"}

각 지표의 건강 상태는 다음중 하나가 될 수 있다.

UP : 외부 시스템이 작동 중이고 접근 가능하다.
DOWN : 외부 시스템이 작동하지 않거나 접근할 수 없다.
UNKNOWN : 외부 시스템의 상태가 분명하지 않다.
OUT_OF_SERVICE : 외부 시스템에 접근할 수 있지만, 현재는 사용할 수 없다.

16.2.2 구성 상세 정보 보기

빈(beans) 연결 정보 얻기

스프링 애플리케이션 컨텍스트를 살펴보는 데 가장 중요한 엔드포인트가 /beans 엔드포인트다.
이 엔드포인트는 애플리케이션 컨텍스트의 모든 빈을 나타내는 JSON 문서(빈의 이름, 자바 타입, 주입되는 다른 빈 등)를 반환한다.

자동-구성 내역 알아보기

자동-구성은 스프링 부트가 제공하는 가장 강력한 기능 중 하나다.
그러나 때로는 왜 자동-구성이 되었는지 궁금할 것이다. 이런 경우에 /conditions 엔드포인트의 GET요청을 하여 확인할 수 있다.

환경 속성과 구성 속성 살펴보기

어떤 환경 속성들이 사용 가능하고 어떤 구성 속성들이 각 빈에 주입되었는지 파악하는 것도 중요하다.
/env 엔드포인트에 GET 요청을 하면, 스프링 애플리케이션에 적용 중인 모든 속성 근원의 속성들을 포함하는 다소 긴 응답을 받는다.
여기에는 환경 변수, JVM 시스템 속성, application.properties, application.yml 파일, 그리고 스프링 클라우드 구성 서버의 속성까지도 포함된다.

/env 엔드포인트는 속성 값을 읽는 것은 물론 설정하는 데도 사용될 수 있다.
즉, name과 value 필드를 갖는 JSON 문서를 지정한 POST 요청을 /env 엔드포인트에 제출하면 실행 중인 애플리케이션의 속성을 설정할 수 있다.

$ curl localhost:8080/actuator/env \
	-d'{"name":"support@tacocloud.com","value":"incheol"}' \
	-H "Content-type:application/json"

HTTP 요청-매핑 내역 보기

애플리케이션이 처리할 수 있는 모든 종류의 HTTP 요청, 그리고 이런 요청들을 어떤 종류의 컴포넌트가 처리하는지를 전체적으로 파악할 수 있다. /mappings 엔드포인트에 GET 요청을 하면 다음과 같은 응답을 받을 수 있다.

로깅 레벨 관리하기

로깅은 모니터링 또는 디버깅의 수단을 제공할 수 있다. 로깅 레벨의 설정은 균형을 잡는 작업이 될 수 있다. 실행 중인 애플리케이션에 어떤 로깅 레벨이 설정되었는지 궁금하다면 /loggers 앤드포인트에 GET 요청을 할 수 있다.

16.2.3 애플리케이션 활동 지켜보기

애플리케이션이 처리하는 HTTP 요청이나 애플리케이션에 있는 모든 스레드의 작동을 포함해서 실행 중인 애플리케이션의 활동(activity)를 지켜보는 것은 유용한다.

이것을 위해 액추에이터는

/httptrace (HTTP 요청 추척하기),
/threaddump (스레드 모니터링),
/heapdump (힙 메모리 모니터링)

엔드포인트를 제공한다.

/heapdump 엔드포인트는 상세하게 나타내기 가장 어려운 액추에이터 엔드포인트일 것이다.
간략히 말해서, 이 엔드포인트는 메모리나 스레드 문제를 찾는 데 사용할 수 있는 gzip 압축 형태의 HPROF 힙 덤프 파일을 다운로드한다.

16.2.4 런타임 메트릭 활용하기

/metrics 엔드포인트는 실행 중인 애플리케이션에서 생성되는 온갖 종류의 메트릭을 제공할 수 있으며,
여기에는 메모리, 프로세스, 가비지 컬렉션, HTTP 요청 관련 메트릭 등이 포함된다.

메트릭 (metrics)

메트릭은 타임스탬프와 보통 한두 가지 숫자 값을 포함하는 이벤트이다.
이 메트릭은 모든 메트릭의 행이 타임스탬프로 정렬된 메트릭 파일에 순차적으로 추가된다.

16.3 액추에이터 커스터마이징

액추에이터의 가장 큰 특징 중 하나는 애플리케이션의 특정 요구를 충족하기 위해 커스터마이징할 수 있다는 것이다.
즉, 커스텀 엔드포인트를 생성할 수 있다.

커스텀 정보 제공자 생성하기
Git 커밋 정보 노출하기
커스텀 메트릭 등록하기
커스텀 엔드포인트 생성하기

16.4 액추에이터 보안 처리하기

액추에이터 자체의 보안이 중요하지만, 보안은 액추에이터의 책임 범위를 벗어난다.
대신에 스프링 시큐리티를 사용해서 액추에이터의 보안을 처리해야 한다.
그리고 액추에이터 앤드 포인트는 단지 애플리케이션의 경로이므로 액추에이터 보안이라고 해서 특별한 것은 없다.

요약

스프링 부트 액추에이터는 HTTP와 JMX MBeans 모두의 엔드포인트를 제공한다.
엔드포인트는 스프링 부트 애플리케이션의 내부 활동을 볼 수 있게 한다.
대부분의 액추에이터 엔드포인트는 기본적으로 비활성화된다.
그러나 management.endpoints.web.exposure.include 속성과 management.endpoints.web.exposure.exclude 속성을 설정하여 선택적으로 노출시킬 수 있다.
/loggers와 /env 같은 엔드포인트는 실행 중인 애플리케이션의 구성을 실시간으로 변경하는 쓰기 오퍼레이션을 허용한다.
애플리케이션의 빌드와 Git 커밋에 관한 상세 정보는 /info 엔드포인트에서 노출될 수 있다.
애플리케이션의 건강 상태는 외부에 통합된 애플리케이션의 건강 상태를 추적하는 커스텀 건강 지표에 의해 영향받을 수 있다.
커스텀 애플리케이션 메트릭은 Micrometer를 통해 등록할 수 있다. Micrometer는 벤더 중립적인 메트릭이며, 애플리케이션이 원하는 어떤 메트릭도 발행하여 서드파티 모니터링 시스템(예를 들어, Prometheus, Datadog, New Relic 등)에서 보일 수 있게 한다.
스프링 웹 애플리케이션의 다른 엔드포인트와 마찬가지로 액추에이터 엔드포인트는 스프링 시큐리티를 사용해서 보안을 처리할 수 있다.