SpringBoot Actuator

1. Spring Boot Actuator

일단.. 생소한Actuator 이란??

An actuator is a manufacturing term that refers to a mechanical device for moving or controlling something. Actuators can generate a large amount of motion from a small change.

물건을 움직이거나 컨트롤하기 위한 장치를 의미하는 제조 용어로, 작은 변화로 큰 변화를 일으킬 수 있다.
앱을 모니터링 하거나 메트릭을 수집하거나 트래픽 혹은 데이터 베이스 상태를 이해하는 것을 쉽게 하는 것
설명만 봐선 알듯말듯하게 모르겠고, 정리를 하는 시점에도 딱 이거다! 하고 떠오르질 않네요.
모든 내용은 spring boot2.x 를 기반으로 작성했습니다. 1.x 하고는 약간 달라요

2. 의존성 추가

maven 일 경우

1
2
3
4
5
6


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

Gradle 일 경우

1
2
3


dependencies {
    compile("org.springframework.boot:spring-boot-starter-actuator")
}

3. Endpoints

엔드포인트를 사용하면 애플리케이션을 모니터링하고 상호 작용할 수 있음
spring boot 2.x 에서는 /health, /info 2개만 기본적으로 제공
모든 기능을 사용하려면 프로퍼티에 추가
```
management.endpoints.web.exposure.include = *
```
기본적인 /health 를 하면
1 2 3

{ "status": "UP" }
만 나오며 healthIndicator 을 구현하여 추가적으로 커스텀도 가능

ex)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


@Component
public class MyHealthIndicator implements HealthIndicator {
  
    @Override
    public Health health() {
        int errorCode = check(); // perform some specific health check
        if (errorCode != 0) {
            return Health.down().withDetail("Error Code", errorCode).build();
        }
        return Health.up().build();
    }
  
}

4. Metrics

Micrometer 지원, 직접 상호작용
MeterRegistry 유형의 Bean 이 자동 구성
~~이번 글을 쓰게 된 이유~~

/metrics 를 하면

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


{
    "names": [
        "http.server.requests",
        "jdbc.connections.idle",
        "tomcat.sessions.rejected",
        "hikaricp.connections.max",
        "hikaricp.connections.min",
        "process.cpu.usage",
        "jvm.memory.max",
        "jvm.threads.states",
        //....
    ]
}

이런 식으로 뜨고, 실제 값을 얻으려면 원하는 메트릭 (/actuator/metrics/jvm.memory.max) 으로 이동해야 됨

/actuator/metrics/jvm.memory.max 의 경우

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


{
    "name": "jvm.memory.max",
    "description": "The maximum amount of memory in bytes that can be used for memory management",
    "baseUnit": "bytes",
    "measurements": [
        {
        "statistic": "VALUE",
        "value": 9860284415
        }
    ],
    "availableTags": [
        {
        "tag": "area",
        "values": [
          "heap"
            //...
            ]
        }
    ]
}

당연하게도 커스텀 메트릭 또한 추가 가능

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


@Component
public class SampleBean {
  
    private final Counter counter;
    private Tag tag = Tag.of("status", "ok")
  
    public SampleBean(MeterRegistry registry) {
        this.counter = registry.counter("received.message", "status", "all");
    }
  
    public void handleMessage(String message) {
        this.counter.increment();
        // handle message implementation
    }
}

metrics 에 등록된 것 확인

1
2
3
4
5
6
7
8
9


{
    "names": [
        "http.server.requests",
        "jdbc.connections.idle",
        "tomcat.sessions.rejected",
        //....
        "received.message"
        ]
}

/actuator/metrics/received.message 에서 내용을 확인해보면

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31


{
    "name": "received.message",
    "description": null,
    "baseUnit": null,
    "measurements": [
        {
        "statistic": "COUNT",
        "value": 1  // 호출 횟수
        }
    ],
    "availableTags": [
        {
        "tag": "server_name",
        "values": [
            "sample-api"
            ]
        },
        {
        "tag": "profile",
        "values": [
            "local"
            ]
        },
        {
        "tag": "status",
        "values": [
            "all"
            ]
        }
    ]
}

이런 식으로 정보를 알 수 있음

5. Custom Endpoint 생성

커스텀 앤드 포인트를 생성하는 것이 가능

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32


@Component
@Endpoint(id = "features")
public class FeaturesEndpoint {
   
    private Map<String, Feature> features = new ConcurrentHashMap<>();
   
    @ReadOperation
    public Map<String, Feature> features() {
        return features;
    }
   
    @ReadOperation
    public Feature feature(@Selector String name) {
        return features.get(name);
    }
   
    @WriteOperation
    public void configureFeature(@Selector String name, Feature feature) {
        features.put(name, feature);
    }
   
    @DeleteOperation
    public void deleteFeature(@Selector String name) {
        features.remove(name);
    }
   
    public static class Feature {
        private Boolean enabled;
   
        // [...] getters and setters 
    }
}

위의 경우는 /actuator/features 로 접속 가능
- @ReadOperation – HTTP GET에 매핑
- @WriteOperation – HTTP POST에 매핑
- @DeleteOperation – HTTP DELETE에 매핑
이 외에도 actuator 에 대한 많은 기능들이 있습니다. 엔드포인트를 확장한다거나 logger 에 관련된 것이라던가, 보안과 관련된 기능이라던가…
메트릭 설정을 추가하면서 맛보기로 알아본 것들을 api 문서 참고하면서 작성했기 때문에 빈약하거나, 잘못된 내용이 있을 수 있습니다.

참고

https://docs.spring.io/spring-boot/docs/current/reference/html/production-ready-features.html#production-ready

https://www.baeldung.com/spring-boot-actuators#boot-2x-actuator