[스프링 부트 핵심 가이드] 11. 액추에이터 활용하기

본 게시글은 '스프링 부트 핵심 가이드' 책의 내용을 정리한 것입니다.

저자 : 장정우

출판사 : 위키북스

---

스프링 부트 액추에이터는 HTTP 엔드포인트나 JMX(Java Management Extensions, 실행 중인 애플리케이션의 상태를 모니터링하고 설정을 변경할 수 있게 해주는 API)를 활용해 애플리케이션을 모니터링하고 관리할 수 있는 기능을 제공한다.

 

11.1 프로젝트 생성 및 액추에이터 종속성 추가

 

책에서 실습을 위해 구성한 프로젝트 설정은 다음과 같다.

• groupId : com.springboot
• artifactId : actuator
• name : actuator
• Developer Tools : Spring Configuration Processor
• Web : Spring Web

+ SwaggerConfiguration 클래스 생성 & pom.xml에 의존성 추가

+ spring-boot-starter-actuator 의존성 추가

<dependencies>

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

  </dependencies>

 

 

11.2 엔드포인트

 

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

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

 

액추에이터 기본 엔드포인트 리스트

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

 

Spring MVC, Spring WebFlux, Jersey을 사용한다면 추가로 사용 가능한 엔드포인트

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

 

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

## management.endpoint.<id>.enabled 를 통해 id로 구분된 기능을 활성화
management.endpoint.shutdown.enabled=true
management.endpoint.caches.enabled=false

 

액추에이터 설정을 통해 기능 활성화/비활성화가 아니라 엔드포인트 노출 여부만 설정하는 것도 가능하다. 노출 여부는 JMX를 통한 노출과 HTTP를 통한 노출이 있다.

## 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

## web과 jmx 환경에서 엔드포인트를 전체적으로 노출, 스레드 덤프와 힙 덤프는 제외

 

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

노출 설정에 대한 기본값은 다음과 같다.

 

ID	JMX	WEB
auditevents	O	X
beans	O	X
caches	O	X
conditions	O	X
configprops	O	X
env	O	X
flyway	O	X
health	O	O
heapdump	해당 없음	X
httptrace	O	X
info	O	X
integrationgraph	O	X
jolokia	해당 없음	X
logfile	해당 없음	X
loggers	O	X
liquibase	O	X
metrics	O	X
mappings	O	X
Prometheus	해당 없음
quartz	O	X
scheduledtasks	O	X
sessions	O	X
shutdown	O	X
startup	O	X
threaddump	O	X

 

 

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

 

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

 

/info 엔드포인트를 통해 가동 중인 애플리케이션의 정보를 볼 수 있다. application.properties에 'info.'로 시작하는 속성 값들을 정의하여 제공하는 정보의 범위를 설정할 수 있다.

## 액추에이터 info 정보 설정
info.organization.name=wikibooks
info.contact.email=thinkground.flature@gmail.com
info.contact.phoneNumber=010-1234-5678

/actuator/info로 접근하면 다음과 같이 출력되는 것을 확인할 수 있다.

 

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

 

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

상세 상태를 확인하려면 application.properties에 아래 코드를 추가한다.

## 액추에이터 health 상세 내역 활성화
management.endpoint.health.show-details=always

show-details 속성에서 설정할 수 있는 값은 다음과 같다.

• never(기본값) : 세부 사항은 표시하지 않는다.
• when-authorized : 승인된 사용자에게만 세부 상태를 표시한다. 확인 권한은 application.properties에 추가한 management.endpoint.health.roles 속성으로 부여할 수 있다.
• always : 모든 사용자에게 세부 상태를 표시한다.

 

 

설정 후 출력을 확인하면 다음과 같다.

status 속성에는 UP, DOWN, UNKNOWN,  OUT_OF_SERVICE 가 사용된다.

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

중간에 있는 status 들의 값이 모두 UP이여야 애플리케이션 상태가 UP으로 표시되며, DOWN인 것이 있다면 애플리케이션 상태도 DOWN으로 표기되며 HTTP 상태 코드도 변경된다.

 

11.3.3 빈 정보 확인(/beans)

 

/beans 엔드포인트를 통해 스프링 컨테이너에 등록된 스프링 빈의 전체 목록을 표시할 수 있다. 

 

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

 

/conditions 엔드포인트를 통해 스프링 부트의 자동설정 조건 내역을 확인할 수 있다.

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

 

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

 

/env 엔드포인트를 통해 환경변수 정보를 확인할 수 있다. 기본적으로 application.properties 파일의 변수들이 표시되며, OS, JVM의 환경변수도 함께 표시된다. 

민감한 정보를 가리기 위해서는 management.endpoint.env.keys-to-sanitize 속성을 사용한다.

## env 호출 시 등장하는 환경 변수 정보 중 민감 정보를 가리는데 사용할 수 있음
management.endpoint.env.keys-to-sanitize=password, secret

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

 

11.3.6 로깅 레벨 확인(/loggers)

 

애플리케이션의 로깅 레벨 수준이 어떻게 설정돼 있는지 확인할 수 있다. POST 형식으로 호출하면 로깅 레벨을 변경하는 것도 가능하다.

 

 

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

 

액추에이터는 커스텀 기능 설정도 제공한다. 커스텀 기능을 개발하는 방식은 기존 기능에 내용을 추가하는 방식과 새로운 엔드포인트를 개발하는 방식이 있다.

 

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

 

액추에이터를 커스터마이징 하는 가장 간단한 방법은 application.properties 파일 내에 내용을 추가하는 것이다. 그러나 관리 측면에서 좋지 않기 때문에 별도의 구현체 클래스를 작성해서 내용을 추가하는 방법이 많이 활용된다. 액추에이터에서는 InfoContributor 인터페이스를 제공하고 있는데, 이 인터페이스를 구현하는 클래스를 생성하면 된다.

@Component
public class CustomInfoContributor 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);
    }
}

contribue 메서드를 오버라이딩 할 수 있는데, 이 메서드에서 파라미터로 받는 Builder 객체는 액추에이터 패키지의 Info 클래스 안에 정의돼 있는 클래스로서 Info 엔드포인트에서 보여줄 내용을 담는 역할을 수행한다.

구현체 클래스에서 작성한 내용이 추가된 것을 볼 수 있다.

 

11.4.2 커스텀 엔드포인트 생성

 

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

 

애플리케이션에 메모 기록을 남길 수 있는 기능을 엔트포인트로 생성하는 예제를 작성해 본다.

 

우선 엔드포인트 클래스를 생성한다.

@Component
@Endpoint(id = "note", enableByDefault = true)
public class NoteEndpoint {

    private Map<String, Object> noteContent = new HashMap<>();

    @ReadOperation
    public Map<String, Object> getNote(){
        return noteContent;
    }

    @WriteOperation
    public Map<String, Object> writeNote(String key, Object value){
        noteContent.put(key,value);
        return noteContent;
    }

    @DeleteOperation
    public Map<String, Object> deleteNote(String key){
        noteContent.remove(key);
        return noteContent;
    }

}

@Endpoint 어노테이션을 선언하면 액추에이터에 엔드포인트로 자동으로 등록되며 id 속성값으로 경로를 정의할 수 있다. 또한 enableByDefault라는 속성으로 현재 생성하는 엔드포인트의 기본 활성화 여부도 설정 가능하다. enableByDefault 속성의 기본값은 true로서 값을 별도로 지정하지 않으면 활성화된다.

 

엔드포인트를 설정하는 클래스에는 @ReadOperation, @WriteOperation, @DeleteOperation 어노테이션을 사용해 각 동작 메서드를 생성할 수 있다.

 

해당 예제에서는 @ReadOperation 어노테이션을 정의해 HTTP GET 요청에 반응하는 메서드를 생성했다. noteContent라고 하는 Map 타입의 객체를 전달하고 있다.

@WriteOperation 이 정의된 메서드를 통해 값을 추가 후 /note 엔드포인트를 호출해 보면 다음과 같이 출력된다.

@DeleteOperation 어노테이션이 선언된 메서드는 DELETE 호출을 통해 사용할 수 있으며, key 값을 받아 Map 객체에서 해당 값을 삭제하는 작업을 수행한다.