Actuator (액츄에이터)

💡이번 포스팅에서는 Spring Boot의 Actuator (액츄에이터)에 대해서 정리해 보도록 하겠습니다.
💡이번 포스팅의 핵심은 Spring Boot의 Actuator란 무엇인지, 사용하는 방법에 초점을 맞췄기 때문에 조금 더 자세한 내용은 추후 따로 정리해 보도록 하겠습니다.

 

위와 같은 이유로 이번 포스팅에서 정리할 내용은 다음과 같습니다.

• Actuator란?
• Actuator 사용하기
• Actuator Endpoint
• Enabling Endpoints
• Exposing Endpoints
• Implementing Custom Endpoint

 

Actuator (액츄에이터) 란?

actuator를 간단하게 정의하면 Spring Boot 애플리케이션을 제어하고 모니터링하기 위한 도구라고 할 수 있습니다.

 

actuator를 살펴보면 Production-ready Features (프로덕션 준비 기능)라는 단어가 등장합니다.

 

Production-ready Features (프로덕션 준비 기능)

Spring Boot 공식 문서에서는 프로덕션 준비 기능에 대해 아래와 같이 설명하고 있습니다.

Shttps://docs.spring.io/spring-boot/docs/current/reference/html/actuator.html#actuator.enabling

Spring Boot에는 애플리케이션을 프로덕션으로 푸시할 때 애플리케이션을 모니터링하고 관리하는 데 도움이 되는 여러 가지 추가 기능이 포함되어 있습니다.
HTTP 엔드포인트 또는 JMX를 사용하여 애플리케이션을 관리하고 모니터링하도록 선택할 수 있습니다.
auditing, health 및 metrics 수집을 애플리케이션에 자동으로 적용할 수도 있습니다.

actuator를 사용하는 방법은 매우 간단합니다.

Spring Boot에서 제공하는 starter-actuator 의존성을 추가하는 것만으로 actuator 기능을 쉽게 활성화 할 수 있습니다.

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

// gradle
dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-actuator'
}

💡Actuator
actuator는 무언가를 움직이거나 제어하기 위한 기계 장치를 가리키는 제조 용어입니다.
actuator는 작은 변화로 많은 양의 동작을 생성할 수 있습니다.

 

 

actuator endpoint를 사용하면 애플리케이션을 모니터링하고 상호 작용할 수 있습니다.
Spring Boot에는 여러 가지 기본 제공 endpoint가 포함되어 있으며 사용자가 직접 추가할 수 있습니다.
예를 들어 health endpoint는 기본 애플리케이션 health 정보를 제공합니다.

각 개별 endpoint를 활성화 또는 비활성화하고 HTTP 또는 JMX를 통해 노출(원격 액세스 가능)할 ​​수 있습니다.
endpoint는 활성화되고 노출된 경우 사용 가능한 것으로 간주됩니다.
기본 제공 endpoint는 사용 가능한 경우에만 자동 구성됩니다.
대부분의 애플리케이션은 endpoint의 ID와 접두사 /actuator가 URL에 매핑되는 HTTP를 통한 노출을 선택합니다. 예를 들어 기본적으로 health endpoint는 /actuator/health에 매핑됩니다.

 

사용할 수 있는 endpoint

사용할 수 있는 endpoint는 위와 같으며 프로젝트 실행 후 /actuator url로 접속하면 아래와 같이 endpoint를 확인할 수 있습니다.

그리고 Spring Boot 공식 문서에 따르면 Web 환경에서는 아래와 같이 추가 endpoint를 사용할 수 있다고 합니다.

💡Actuator Endpoints에 대해 자세한 내용을 확인하고 싶다면, 아래 링크를 확인해보시면 좋을 것 같습니다.

HTML 문서
PDF 문서

 

 

Enabling Endpoints

endpoint 중 shutdown을 제외한 모든 endpoint가 기본적으로 활성화되어 있다고 합니다. 

엔드포인트 활성화를 구성하려면 management.endpoint.<id>.enabled 속성을 사용합니다.

management:
  endpoint:
    shutdown:
      enabled: true // shutdown endpoint 활성화
    health:
      enabled: false // health endpoint 비활성화

 

비활성화를 하면 endpoint가 노출되지 않지만, 활성화의 경우 노출 여부도 설정을 해야지만 비로소 endpoint로 노출됩니다.

 

Exposing Endpoints

기본적으로는 health endpoint만 노출됩니다. endpoint에는 민감한 정보들이 포함될 수 있으므로 언제 노출할지 신중하게 고려해야 합니다.

 

💡Endpoint의 민감한 정보, 즉 보안과 관련된 내용에 대해서는 우아한 형제들 기술 블로그에 정리된 내용이 있는데 참고해보시면 좋을 것 같습니다.

 

모든 endpoints를 include하거나 exclude 하기 위해서는 *(asterisk)를 사용해야 하는데,
YAML에서 *(asterisk)는 특별한 의미가 있습니다.
따라서 YAML에서 *(asterisk)를 사용하기 위해서는 "(따옴표)로 감싸줘야 합니다.

ex)
* → X
"*" → O

 

애플리케이션이 공개적으로 노출된 경우 endpoint도 보호하는 것이 좋습니다.

 

 

endpoint가 노출되는 경우에 대한 자체 전략을 구현하려는 경우 EndpointFilter 빈을 등록할 수 있습니다.

 

Implementing Custom Endpoints

Custom Endpoint를 만들기 위해서는 @Endpoint annotation을 사용합니다.

Spring Boot는 @Endpoint가 있는 @Bean을 추가하면 @ReadOperation, @WriteOperation, @DeleteOperation annotation이 달린 메서드들을 모두 JMX, HTTP에 자동으로 노출합니다.

 

 

endpoint에 대한 작업은 매개 변수를 통해 입력 받습니다. 웹을 통해 노출될 때 이러한 매개변수의 값은 URL의 쿼리 매개변수와 JSON Request Body에서 가져옵니다. 

 

 

endpoint는 기술에 구애받지 않기 때문에 메서드 서명에 단순 형식만 지정할 수 있습니다. 특히 이름 및 카운터 속성을 정의하는 CustomData 유형으로 단일 매개변수를 선언하는 것은 지원되지 않습니다.

// 이 방식은 OK
@WriteOperation
public void updateData(String name, int counter) {
    // injects "test" and 42
}

// 이 방식은 Not OK
// Object로 묶어서 받을 수는 없음
@WriteOperation
public void updateData(CustomData customData) {
    // Not OK
}​

 

predicate의 경로는 endpoint의 ID와 웹에 노출된 endpoint의 기본 경로에 의해 결정됩니다.
기본 기본 경로는 /actuator입니다.
예를 들어 ID가 sessions인 endpoint는 predicate의 경로로 /actuator/sessions를 사용합니다.

 

@Selector를 사용하여 작업 메서드의 하나 이상의 매개 변수에 주석을 달아 경로를 추가로 사용자 지정할 수 있습니다.
이러한 매개변수는 경로 조건자에 경로 변수로 추가됩니다.
변수의 값은 endpoint 작업이 호출될 때 작업 메서드로 전달됩니다.
나머지 모든 경로 요소를 캡처하려면 마지막 매개 변수에 @Selector(Match=ALL_REMAINING)를 추가하고 String[]과 변환 호환되는 유형으로 만들 수 있습니다.

 

Request Body를 사용하는 @WriteOperation(HTTP POST)의 경우 predicate의 consumes는
application/vnd.spring-boot.actuator.v2+json 또는 application/json입니다.
다른 모든 작업의 ​​경우 consumes가 비어 있습니다.

 

predicate의 produces는 @DeleteOperation, @ReadOperation 및 @WriteOperation 주석의 생성 특성에 의해 결정될 수 있습니다.
속성은 선택 사항입니다.
사용하지 않으면 produces가 자동으로 결정됩니다.

작업 메서드가 void 또는 Void를 반환하면 produces가 비어 있습니다.
작업 메서드가 org.springframework.core.io.Resource를 반환하는 경우 consumes는 application/octet-stream입니다.
다른 모든 작업의 ​​경우 produces는 application/vnd.spring-boot.actuator.v2+json 또는 application/json입니다.

 

공식 문서를 토대로 Custom Endpoint를 만들어보면 아래와 같이 만들어볼 수 있습니다.

@Component
@Endpoint(id = "my")
public class MyEndPoint {

    private String value = "hello world";

    @ReadOperation
    public String getValue() {
        return value;
    }

    @WriteOperation
    public void setValue(String value) {
        this.value = value;
    }

    @DeleteOperation
    public void deleteValue() {
        this.value = "hello world";
    }
}

 

Custom Endpoint를 만든 후 프로젝트를 실행하여 /actuator를 확인해보면 아래와 같이 직접 만든 endpoint가 노출되는 것을 확인할 수 있습니다.

 

이번 포스팅에서는 처음에 언급했던 대로 공식 문서를 토대로 간단하게 actuator가 무엇인지, 어떻게 사용해야 하는지 그리고 endpoint에는 어떤 것들이 있는지에 대해 알아봤습니다.

 

공식 문서를 읽다보니 endpoint 별로 더 상세한 내용들이 있고 security 설정 부분도 있었는데, 이런 부분들은 추후 더 자세하게 공부한 후 따로 포스팅을 작성해 보도록 하겠습니다.