Spring Boot Actuator 사용해 보기

소개

Spring Boot Actuator는 application을 모니터링하고 관리하는데 도움이 되는 여러 추가 기능을 제공한다.
Http endpoint나 JMX를 통해 application을 관리하고 모니터링할 수 있다.
auditing, health 및 metric 수집을 application에 자동으로 적용한다.

Spring Boot Actuator에 대한 안내는 document의 Production-ready Features 섹션으로 안내되고 있다.
https://docs.spring.io/spring-boot/docs/current/reference/html/index.html
https://docs.spring.io/spring-boot/docs/current/reference/html/actuator.html

설정

dependency 설정

actuator의 사용은 다음 의존성을 추가하면 된다.

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

해당 의존성을 추가하면 actuator가 활성화되며 기본 설정되어 있는 /actuator 주소 아래 다양한 endpoint를 사용할 수 있게 된다.

properties 설정

endpoint는 기본 설정이 모두 노출이 아니고 health endpoint만 노출되어 있다.
다음이 기본 값이다.

management.endpoints.jmx.exposure.include=health
management.endpoints.web.exposure.include=health

actuator가 제공하는 다양한 endpoint를 노출하고 싶은 경우 아래처럼 명시하면 된다.
예를 들어 info endpoint를 노출하고 싶은 경우 다음과 같다.

management.endpoints.jmx.exposure.include=health,info

수많은 endpoint를 일일이 열거하기 귀찮으면 전체를 노출할 수 있고 그중 몇몇을 제외하는 설정도 가능하다.

management.endpoints.web.exposure.include=* 
management.endpoints.web.exposure.exclude=env,beans

spring에서 제공하는 endpoint의 목록은 현재 다음과 같다.

기본적으로 /actuator 주소를 호출하면 어떤 endpoint를 사용할 수 있는지 json으로 제공한다.
만약 비활성화 하고 싶으면 다음 설정을 추가하면 된다.

management.endpoints.web.discovery.enabled=false

info endpoint

info endpoint는 InfoContributor bean에서 수집된 다양한 정보를 노출한다.
Spring Boot에는 여러 auto-configured InfoContributor bean이 포함되어 있으며 또한 직접 사용할 수도 있다.

Spring이 제공하는 infoContributor는 다음과 같다.

prerequisites가 있는 BuildInfoContributor나 GitInfoContributor는 해당 파일이 있으면 활성화된다.
prerequisites가 None인 InfoContributor를 활성화시키길 원한다면 management.info.enabled를 true로 설정하면 된다.
예를 들어 env를 활성화시키려면 다음과 같이 설정한다.

management.info.env.enabled=true

아마 별다른 설정 없이 actuator만 추가하고 /actuator/info를 호출하면 다음과 같은 간단한 build 정보만 노출될 것이다.

{ 
    "build": { 
        "version": "0.0.1-SNAPSHOT", 
        "artifact": "bluesky-api-gate", 
        "name": "bluesky-api-gate", 
        "time": "2023-01-26T22:06:47.399Z", 
        "group": "net.luversof" 
    } 
}

Custom Application information

EnvironmentInfoContributor 사용하기

만약 properties 설정으로 info 정보를 추가하고자 하는 경우 EnvironmentInfoContributor를 사용하면 된다.
다음처럼 활성화시킨 후

management.info.env.enabled=true

추가하고자 하는 값을 info.* 으로 설정하면 된다.
예를 들어 다음처럼 추가되어 있다면

info.app.encoding=UTF-8 
info.app.java.source=17 
info.app.java.target=17

/actuator/info에 다음과 같이 추가되게 된다.

{
    "app": {
        "encoding": "UTF-8",
        "java": {
            "source": "17",
            "target": "17"
        }
    },
    // ... 기존 info 정보
}

만약 maven 빌드 시 정보를 추가하고자 하는 경우 다음과 같이 사용할 수 있다.

info.app.encoding=@project.build.sourceEncoding@ 
info.app.java.source=@java.version@ 
info.app.java.target=@java.version@

BuildInfoContributor 사용하기

BuildInfoContributor는 META-INF/build-info.properties 파일이 있는 경우 해당 파일에 설정된 값을 /actuator/info에 추가해 준다.
build-info.properties 파일을 사용하는 설정은 간단하다.
기존에 사용하던 spring-boot-maven-plugin에 build-info goal과 properties 설정을 추가하면 된다.

<plugin> 
    <groupId>org.springframework.boot</groupId> 
    <artifactId>spring-boot-maven-plugin</artifactId> 
    <executions> 
        <execution> 
            <goals> 
                <goal>build-info</goal> 
            </goals> 
            <configuration> 
                <additionalProperties> 
                    <buildNumber>${build.number}</buildNumber> 
                </additionalProperties> 
            </configuration> 
        </execution> 
    </executions> 
</plugin>

위에서 사용한 build.number는 maven properties에 기본 값을 설정하였다.

<properties>
    <build.number>LOCAL_BUILD</build.number> 
</properties>

jenkins에서 maven 빌드 시 jenkins의 job BUILD_NUMBER 값을 매개변수로 넘겨주면 기본 값 대신 해당 값이 설정되게 된다.

mvn -Dbuild.number=${BUILD_NUMBER} deploy

Implementing Custom Endpoints

위의 예에서는 info endpoint를 확장해서 사용하는 2가지 방법을 소개했다.

그 외에도 각자가 원하는 endpoint를 개별 사용할 수 있다.

@ReadOpration, @WriteOperation 또는 @DeleteOperation을 가진 @Endpoint annotation을 가진 bean을 등록하면 된다.
@Endpoint의 id는 필수로 지정해야 한다.

@Endpoint(id = "someEndpoint")
@Component
public class SomeEndpoint {

    @ReadOperation
    public CustomData getData() {
        return new CustomData("test", 5);
    }

    
    public static record CustomData(String name, int amount) {};
}

위와 같이 지정하면 /actuator에서 해당 endpoint는 추가된 걸 확인할 수 있다.

"someEndpoint": {
    "href": "http://localhost:40132/actuator/someEndpoint",
    "templated": false
}

해당 endpoint를 호출해 보면 다음과 같은 응답을 확인할 수 있다.

{
    "name": "test",
    "amount": 5
}

management bast-path 설정

/actuator 주소를 만약 이미 사용하고 있다면 다른 주소를 사용해야 한다.

기본으로 설정된 /actuator를 다른 주소로 바꾸길 원하는 경우 다음과 같이 설정한다.

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

위와 같이 설정한 경우 기존 /actuator/info 같은 주소는 /manage/info 와 같이 변경된다.

management port 설정

/actuator로 시작하는 management는 외부에 노출되지 않아야 한다.

이를 위해 내부에서만 접근하도록 port를 분리할 수 있다.

다음과 같이 설정한다.

management.server.port=8081

---

여기까지 간단하게 Spring Boot Actuator를 사용하는 방법을 알아보았다.

이렇게 actuator를 사용하게 되면 해당 application에 대해 모니터링을 할 수 있게 된다.

보통 모니터링은 위에서 소개한 /actuator 주소를 직접 호출하여 할 수도 있지만 대부분은 이를 연계하여 데이터를 수집하고 모니터링을 할 수 있는 다른 도구를 사용한다.

Promoetheus나 Grafana를 사용할 수도 있고 간단하게는 Spring Cloud Admin Server를 사용할 수도 있다.

그 밖에도 좋은 모니터링 오픈소스가 있을 수도 있다.