스프링 핵심가이드) 북스터디 7주차 : 11장 액추에이터 활용하기

11장 : 액추에이터 활용하기 

애플리케이션 정상 동작 모니터링 환경 구축은 중요.

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

 

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

 

11.1 액추에이터 종속성 추가

액추에이터 기능을 사용하려면 애플리케이션에 spring-boot-starter-actuator 모듈의 종속성 추가.

 

---

11.2 엔드포인트

액추에이터의 엔드포인트틑 애플리케이션의 모니터링을 사용하는 경로.

스프링 부트에는 여러 내장 엔드포인트가 포함돼 있고 커스텀 엔드포인트를 추가할 수도 있음.

 

액추에이터 추가 시 기본적으로 엔드포인트 URL로 /actuator가 추가. 이 뒤에 경로를 추가해 상세 내역에 접근.

/actuator 경로가 아닌 다른 경로를 사용하고 싶다면 application.properties 파일에 작성.

 

management.endpoints.web.base-path=/custom-path

 

액추에이터의 엔드포인트 331P. 참고

 

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

 

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

엔드포인트의 shutdown 기능은 활성화

caches 기능은 비활성화.

 

엔드포인트의 노출 여부만 설정하는 것도 가능.

노출 여부는 JMX를 통한 노출과 HTTP를 통한 노출이 있음.

//HTTP 설정
management.endpoint.web.exposure.include=*
management.endpoint.web.exposure.exclued=threaddump,heapdump

//JMX설정
management.endpoint.jmx.exposure.include=*
management.endpoint.jmx.exposure.exclude=threaddump, heapdump

web과 jmx 환경에서 엔드포인트를 전체적으로 노출하며, 스레드 덤프(thread dump)와 힙 덤프(headp dump) 기능은 제외하겠다는 의미.

 

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

특히 공개적으로 노출되는 APP일 경우에 더욱 신중히 고려.

노출 설정에 대한 기본 값 P334. 참고

 

 

---

11.3 액추에이터 기능 살펴보기

액추에이터를 활성화하고 노출 지점도 설정하면 애플리케이션에서 해당 기능을 사용할 수 있음.

모든 기능을 살펴보려면 다른 의존성과 몇 가지 설정을 추가해야하기 때문에 기능 추가 없이 액추에이터 설정만으로 볼 수 있는 기능 위주로 아래 서술

 

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

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

제공하는 정보의 범위는 애플리케이션에서 몇 가지 방법을 거쳐 제공도 가능하나

application.properties 파일에 info. 로 시작하는 속성값의 정의가 가장 쉬움.

 

//액추에이터 info 정보 설정
info.organization.name=
info.contact.email=
info.contact.phoneNumber=

설정 후 애플리케이션 가동해서 브라우저에 http://localhost:8080/actuator/info에 접근하면

설정파일에 입력한 결과를 받아볼 수 있음.

 

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

/health 엔드포인트를 활용하면 애플리케이션의 상태를 확인할 수 있음.

별도의 설정 없이 http://localhost:8080/actuator/health 에 접근하면

{ "status":"UP"} 결과를 얻을 수 있음.

 

UP 말고도 DOWN, UNKNOWN, OUT_OF_SERVICE 상태 지표가 있음.

이 결과는 주로 네트워크 계층 중 L4(Loanbalancing) 레벨에서 애플리케이션의 상태를 확인하기 위해 사용.

 

상세 상태 확인하고 싶을 때

management.endpoint.health.show-details=always

show-details에 설정할 수 있는 값들

- never(기본값) : 세부 사항은 표시하지 않음.

- when-authorized : 승인된 사용자에게만 세부 상태를 표시.

    확인 권한은 application.properties에 추가한 management.endpoint.health.roles 속성으로 부여

- always : 모든 사용자에게 세부 상태를 표시

 

애플리케이션에 데이터베이스가 연동되어 있으면 인프라 관련 상태까지 확인 가능.

모든 status의 값이 UP이어야 애플리케이션의 상태가 UP으로 표시됨.

만약 DOWN 상태의 항목이 있으면 애플리케이션의 상태도 DOWN으로 표시되며 HTTP 상태 코드도 변경 됨.

 

11.3.3 빈 정보 확인(/beans)

http://localhost:8080/actuator/beans 를 사용하면(/beans 엔드포인트) 스프링 컨테이너에 등록된 스프링 빈의 전체 목록을 표시.

이 엔드포인트는 JSON 형식으로 빈의 정보를 반환. 스프링은 많은 빈이 자동으로 등록되어 운영되기 때문에 실제 내용을 출력해서 육안으로 내용을 파악하기는 어려움.

 

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

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

 

출력 내용은 크게 positiveMatches와 negativeMatches 속성으로 구분되는데, 자동설정의 @Conditional에 따라 평가된 내용을 표시.

 

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

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

(/env 엔드포인트의 출력 값은 내용이 매우 복잡)

 

11.3.6 로깅 레벨 확인(/loggers)

애플리케이션의 로깅 레벨 수준이 어떻게 설정돼 있는지 확인하려면 /loggers 엔드포인트 사용.

 

---

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

액추에이터는 다양한 정보를 가공해서 제공함.

그 밖에 개발자의 요구사항에 맞춘 커스텀 기능 설정도 제공.

 

- 커스텀 기능을 개발하는 방식

   1. 기존 기능에 내용을 추가.

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

 

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

액추에이터를 커스터마이징하는 가장 간단한 방법은 11.3.1에서 /info 엔드포인트의 내용을 추가한 것처럼 application.properties 파일에 내용을 추가하는 것. 다만 많은 내용을 담을 때는 좋지 않음.

 

=> 커스텀 기능을 설정할 때는 별도의 구현체 클래스를 작성해서 내용을 추가하는 방법이 많이 활용.

액추에이터에서는 InfoContributor 인터페이스를 제공하고 있는데, 이 인터페이스를 구현하는 클래스를 생성하면 됨.

 

@Component
public class CustonInfoContribuitor implements InfoContributor {
	@Override
    public void contribute(Builder builder) {
    	Map<String, Object> content = new HashMap<>();
        content.put("code-info", "InfoContributor 구현체에서 정의한 정보입니다.");
        builder.withDetail("custom-info-contributor", content);
    }
}

새로 생성한 클래스를 InfoContributor 인터페이스의 구현체로 설정하면 contribute 메서드를 오버라이딩 할 수 있음.

 

메서드의 파라미터로 받는 Builder 객체 : 액추에이터 패키지의 Info 클래스에 정의돼있는 클래스로 Info 엔드포인트에서 보여줄 내용을 담는 역할을 수행. 객체를 담아 6~8처럼 콘텐츠를 담아 bilder에 포함하면 엔드포인트 출력 결과에서 확인할 수 있음.

 

11.4.2 커스텀 엔드포인트 생성

@Endpoint 어노테이션으로 빈에 추가된 객체들은 @ReadOperation, @WriteOperation, @DeleteOperation 어노테이션을 사용해 JMX나 HTTP를 통해 커스텀 엔드포인트를 노출 시킬 수 있음.

 

JMX에서만 사용하거나 HTTP에서만 사용하는 것으로 제한하고 싶다면 @JmxEndpoint, @WebEndpoint 어노테이션을 사용하면 됨.

 

 

커스텀 엔드포인트는 코드로 구현되기 때문에 더욱 확장성 있는 기능을 개발할 수 있음.