• 액추에이터: 스프링 부트 애플리케이션의 모니터링이나 메트릭과 같은 기능을 HTTP와 JMX 엔드포인트를 통해 제공한다.

액추에이터 개요

  • 액추에이터가 노출하는 엔드포인트를 사용하면 실행 중인 스프링 부트 애플리케이션의 내부 상태에 관한 것을 알 수 있다.

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

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

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

  • 엔드포인트의 노출 여부를 제어할 때는 management.emdpoints.web.exposure.include와 management.endpoints.web.exposure.exclude 속성을 사용하면 노출을 원하는 엔드포인트를 지정할 수 있다.
  • /health, /info, /beans, /conditions 엔드포인트만 노출하기
  • 모든 엔드포인트 노출하기
  • /threaddump와 /heapdump를 제외한 모든 엔드포인트 노출하기
  • /health와 /info 외에 더 많은 엔드포인트를 노출해야 한다면 다른 엔드포인트의 접근을 제한하기 위해 스프링 시큐리티를 구성하는 것이 좋다.

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

  • 액추에이터가 제공하는 엔드포인트에는 어떤 것이 있는지 알아보기 위해 액추에이터의 기본 경로에 대해 GET 요청을 하면 각 엔드포인트의 HATEOAS 링크를 응답으로 받을 수 있다.

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

  • /info: 애플리케이션에 관해 알려준다.
    • 기본적으로 제공하는 정보가 없다.
    • .info으로 시작하는 하나이 상의 구성 속성을 생성하면 응답으로 정보를 준다.
  • /health: 애플리케이션의 건강 상태를 알려준다.
    • 기본적으로는 애플리케이션의 종합적인 건강 지표 상태만 알려준다.
    • 건강 지표는 애플리케이션이 상호 작용하는 외부 시스템의 건강 상태를 나타낸다.
      • UP: 외부 시스템이 작동 중이고 접근 가능하다.
      • DOWN: 외부 시스템이 작동하지 않거나 접근할 수 없다.
      • UNKNOWN: 외부 시스템의 상태가 분명하지 않다.
      • OUT_OF_SERVICE: 외부 시스템에 접근할 수 있지만, 현재는 사용할 수 없다.
    • 모든 건강 지표의 건강 상태는 다음 규칙에 따라 애플리케이션의 전체 건강 상태로 종합된다.
      • 모든 건강 지표가 UP이면 애플리케이션의 건강 상태도 UP
      • 하나 이상의 건강 지표가 DOWN이면 애플리케이션의 건강 상태도 DOWN
      • 하나 이상의 건강 지표가 OUT_OF_SERVICE이면 애플리케이션의 건강 상태도 OUT_OF_SERVICE
      • UNKNOWN 건강 상태는 무시되며, 애플리케이션의 종합 건강 상태에 고려되지 않는다.
    • management.endpoint.health.show-deatils 속성의 기본 값은 never인데, always를 설정하면 건강 상태의 상세 내역을 보여준다.
      • when-authorized로 설정하면, 클아이언트가 완변하게 인가된 경우에 한해서 상세 내역을 보여준다.
    • 자동-구성에서는 애플리케이션과 관련된 건강 지표만 /health 엔드포인트의 응답에 나타낸다.
      • 카산드라
      • 구성 서버
      • Couchbase
      • 유레카
      • Hystrix
      • JDBC 데이터 소스
      • Elasticsearch
      • InfuxDB
      • JMS 메시지 브로커
      • LDAP 이메일 서버
      • Neo4j
      • Rabbit 메시지 브로커
      • Redis
      • Solr
    • 또한, 서드파티 라이브러리들도 자신들의 건강 지표를 제공할 수 있다.

구성 상세 정보 보기

  • Bean 연결 정보 얻기
    • 엔드포인트: /beans
  • 자동-구성 내역 알아보기
    • 엔드포인트: /conditions
    • 자동-구성 내역은 세 부분으로 나뉜다.
      • 긍정 일치: 성공한 조건부 구성
      • 부정 일치: 실패한 조건부 구성
      • 조건 없는 클래스
  • 환경 속성과 구성 속성 살펴보기
    • 엔드포인트: /env
    • 스프링 애플리케이션에 적용 중인 모든 속성 근원의 속성들을 응답으로 받늗나.
      • 스프링 클라우드 구성 서버의 속성들까지도 포함된다.
    • activeProfiles: 활성화된 프로필들
    • propertySources: 스프링 애플리케이션 환경의 모든 속성 근원들을 항목으로 포함하는 배열
    • 특정 속성을 가져오는 데도 사용할 수 있다.
    • 속성을 설정하는 데도 사용될 수 있다.
      • POST 요청을 보내면 된다.
      • DELETE 요청을 보내면 특정 속성을 삭제할 수 있다.
      • 속성을 설정하는 것은 이 요청을 받은 애플리케이션에만 적용되므로 일시적이며, 애플리케이션을 다시 시작하면 없어진다.
  • HTTP 요청-매핑 내역 보기
    • 엔드포인트: /mappings
  • 로깅 레벨 관리하기
    • 엔드포인트: /loggers
    • 일반적으로 로깅 레벨은 패키지 단위로 적용된다.
    • configuredLevel: 명시적으로 구성된 로깅 레벨
    • effectiveLevel: 부모 패키지나 루트 로거로부터 상속받을 수 있는 유효 로깅 레벨
    • 특정 패키지의 로깅 레벨 항목을 확인하기 위해서는 엔드포인트 경로의 두 번째 요소로 지정하면 된다.
      • 예: tacos.ingredients 패키지에 설정된 로깅 레벨을 알고 싶을 때는 /loggers/tacos/ingredients의 GET 요청을 하면 다음의 응답이 반환된다.
    • POST 요청으로 로깅 레벨을 변경할 수도 있다.

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

  • 메모리나 스레드 문제를 찾는 데 사용할 수 있는 gzip 압축 형태의 HPROF 힙 덤프 파일을 다운로드
    • 엔드포인트: /heapdump
  • 애플리케이션이 처리한 가장 최근의 100개 요청
    • 엔드포인트: /httptrace
  • 현재 실행 중인 스레드에 관한 스냅샷
    • 엔드포인트: /threaddump

런타임 메트릭 활용하기

  • 엔드포인트: metrics
  • 메모리, 프로세스, 가비지 컬렉션, HTTP 요청 관련 메트릭 등이 포함된다.
  • /metrics/{메트릭 종류}에 GET 요청을 하면 해당 종류의 메트릭에 관한 더 상세한 정보를 받을 수 있다.
    • 가장 중요한 부분은 measurements이다.
      • 2103개의 응답
      • 요청들을 처리하는데 소요된 전체 시간은 18.086334315초
      • 요청 처리에 소요된 최대 시간은 0.028926313초
  • availableTags를 참고하여 필요한 요청만 필터링해서 볼 수 있다.

액추에이터 커스터마이징

/info 엔드포인트에 정보 제공하기

  • /info 엔드포인트는 처음에 아무 정보도 제공하지 않지만, info.로 시작하는 속성을 생성하면 쉽게 커스텀 데이터를 추가할 수 있다.
  • 이외에도 스프링 부트는 InfoContributor라는 인터페이스를 제공하며, 이 인터페이스는 우리가 원하는 어떤 정보도 /info 엔드포인트 응답에 추가할 수 있다.
    • contribute()를 구현해야된다.
    • Builder 객체의 withDetail()를 호출하여 정보를 추가할 수 있다.
    • 이를 토해 동적인 정보를 엔드포인트에 추가할 수 있다.
  • 빌드 정보를 /info 엔드포인트에 주입하기
    • 스프링 부트에는 /info 엔드포인트 응답에 자동으로 정보를 추가해주는 몇 가지 InfoContributor 구현체가 포함되어 있다.
    • BuildInfoContributor: 프로젝트 빌드 파일의 정보를 /info 엔드포인트 응답에 추가해 준다.
    • build-info goal을 스프링 부트 메이븐 플러그인 execution에 추가하면 된다.
    • 응답 결과
  • Git 커밋 정보 노출하기
    • 메이븐 플러그인을 추가하면 된다.
    • 응답 결과
    • management.info.git.mode 속성을 full로 설정하면 프로젝트가 빌드된 시점의 Git 커밋에 관한 상세한 정보를 얻을 수 있다.

커스텀 건강 지표 정의하기

  • HealthIndicator 인터페이스를 구현하는 빈만 생성하면 된다.

커스텀 메트릭 등록하기

  • 액추에이터 메트릭은 Micrometer에 의해 구현된다.
  • Micrometer: 벤더 중립적인 메트릭이며, 애플리케이션이 원하는 어떤 메트릭도 발행하여 서드파티 모니터링 시스템에서 보여줄 수 있게 한다.
  • Micrometer 메트릭을 발행하는 가장 기본적인 방법은 Micrometer의 MeterRegistry를 사용하는 것이다.
    • 스프링 부트 애플리케이션에서 메트릭을 발행할 때는 어디든 필요한 곳에 MeterRegistry만 주입하면 된다.

커스텀 엔드포인트 생성하기

  • 액추에이터 엔드포인트는 HTTP 요청을 처리하는 것은 물론이고 JMX MBeans로도 노출되어 사용될 수 있다.
  • @Controller나 @RestController 애노테이션으로 지정되는 클래스 대신, 액추에이터 엔트포인트는 @Endpoint로 지정되는 클래스로 정의된다.
    • 액추에이터 엔드포인트 오퍼레이션은 @ReadOperation, @WriteOperation, @DeleteOperation 애노테이션이 지정된 메서드로 정의된다.
  • 만일 HTTP 엔드포인트로만 제한하고 싶다면 @Endpoint 대신 @WebEndpoint를 클래스에 지정하면된다.
  • 이와 달리 MBeans 엔드포인트로만 제한하고 싶다면 @JmxEndpoint를 클래스에 지정하면 된다.

액추에이터 보안 처리하기

  • 액추에이터 엔드포인트를 보안 처리할 때는 스프링 시큐리티를 적용할 수 있다.
    • EndPointRequest.toAnyEndpoint(): 어떤 엑추에이터 엔드포인트와도 일치하는 요청 matcher를 반환한다.
  • excluding() 메서드를 호출해서 특정 엔드포인트를 제외할 수 있다.
  • 특정 엔드포인트에만 보안을 적용하고 싶다면 toAnyEndpoint() 대신 to()를 호출하면 된다.