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

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

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

액추에이터 기능을 사용하기 위해 아래와 같이 spring-boot-starter-actuator 모듈의 종속성을 추가한다.

// build.gradle에 의존성 추가
implementation 'org.springframework.boot:spring-boot-starter-actuator'

이렇게 의존성을 추가하고 애플리케이션을 실행시키면 아래와 같은 메시지가 나오면서 애플리케이션이 실행되지 않는다.

Failed to start bean 'documentationPluginsBootstrapper'

스웨거와 충돌이 발생하여 발생한 오류이다. 그래서 아래와 같이 엔드포인트를 매핑해주는 빈을 등록해줬더니 실행되었다.

	@Bean
    public WebMvcEndpointHandlerMapping webMvcEndpointHandlerMapping(
            WebEndpointsSupplier webEndpointsSupplier,
            ServletEndpointsSupplier servletEndpointsSupplier,
            ControllerEndpointsSupplier controllerEndpointsSupplier,
            EndpointMediaTypes endpointMediaTypes,
            CorsEndpointProperties corsEndpointProperties,
            WebEndpointProperties webEndpointProperties,
            Environment environment) {
        List<ExposableEndpoint<?>> allEndpoints = new ArrayList<>();
        Collection<ExposableWebEndpoint> webEndpoints =
                webEndpointsSupplier.getEndpoints();
        allEndpoints.addAll(webEndpoints);
        allEndpoints.addAll(servletEndpointsSupplier.getEndpoints());
        allEndpoints.addAll(controllerEndpointsSupplier.getEndpoints());

        String basePath = webEndpointProperties.getBasePath();
        EndpointMapping endpointMapping = new EndpointMapping(basePath);
        boolean shouldRegisterLinksMapping = this.shouldRegisterLinksMapping(
                webEndpointProperties, environment, basePath);
        return new WebMvcEndpointHandlerMapping(endpointMapping, webEndpoints,
                endpointMediaTypes, corsEndpointProperties.toCorsConfiguration(),
                new EndpointLinksResolver(allEndpoints, basePath),
                shouldRegisterLinksMapping, null);
    }

    private boolean shouldRegisterLinksMapping(
            WebEndpointProperties webEndpointProperties,
            Environment environment, String basePath) {
        return webEndpointProperties.getDiscovery().isEnabled()
                && (StringUtils.hasText(basePath)
                || ManagementPortType.get(environment)
                        .equals(ManagementPortType.DIFFERENT));
    }

11.2 엔드포인트

액추에이터를 추가하면 기본적으로 엔드포인트 URL로 /actuator가 추가된다. 다른 경로를 사용하고 싶다면 아래와 같이 application.properties 파일에 작성하면 된다.

# 액추에이터 엔드포인트의 기본 경로 변경
management.endpoints.web.base-path=/custom-path

엔드포인트 활성화를 설정하기 위해서는 application.properties 파일에 아래와 같이 작성하면 된다.

# 엔드포인트 활성화 설정
# 엔드포인트의 shutdown 기능은 활성화, caches 기능은 비활성화
management.endpoint.shutdown.enabled=true
management.endpoint.caches.enabled=false

엔드포인트의 노출 여부 설정은 아래와 같이 한다.

# 엔드포인트 노출 설정
# web과 jmx 환경에서 엔드포인트를 전체적으로 노출하며, 스레드 덤프와 힙 덤프 기능을 제외
# 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

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

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

11.3.1 애플리케이션 기본 정보(/info)
기본 정보 제공 범위는 여러가지 방법이 있지만, 아래와 같이 application.properties 파일에 작성하여 간단하게 애플리케이션 정보를 작성할 수 있다.

# 액추에이터 info 정보 설정
management.info.env.enabled=true
info.organization.name=myTable
info.contact.email=aaa@aaaaaa.com
info.contact.phoneNumber=010-0000-0000

11.3.2 애플리케이션 상태(/health)
기본값으로는 간단한 status만 확인할 수 있지만, 아래와 같이 애플리케이션 상세 상태 확인을 위한 application.properties에 속성을 추가할 수 있다.

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

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

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

11.3.3 빈 정보 확인(/beans)
스프링 컨테이너에 등록된 스프링 빈의 전체 목록을 표시한다.

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

11.3.5 스프링 환경변수 정보(/env)
스프링의 환경변수 정보를 확인한다.

11.3.6 로깅 레벨 확인(/loggers)
애플리케이션의 로깅 레벨 수준 확인한다. GET메서드로 호출하면 조회 가능하며, POST 형식으로 호출하면 로깅 레벨을 변경하는 것도 가능하다.

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

11.4.1 정보 제공 인터페이스의 구현체 생성
커스텀 기능을 설정할 때는 InfoContributor 인터페이스의 별도 구현체 클래스를 작성해서 내용을 추가하는 방법이 많이 활용된다.

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

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

// 엔드포인트 클래스
@Component
@Endpoint(id = "note")
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;
    }
}

위와 같이 설정 후 post형식으로 body에 json형식으로 아래와 같이 입력하여, /note 엔드포인트를 호출하면 직접 입력이 가능하다. delete 형식으로 파라미터에 key 값을 입력하면 삭제 또한 가능하다.

{
    "key":"description",
    "value":"설명 부분을 기입합니다."
}