안녕하세요. J4J입니다.
이번 포스팅은 애플리케이션 모니터링을 위한 spring boot actuator 개념 정리 및 구성 가이드에 대해 적어보는 시간을 가져보려고 합니다.
Spring Boot Actuator 개념
spring boot actuator는 운영 환경에서 애플리케이션 관리와 모니터링을 위한 production-ready 기능을 제공하고 있습니다.
production-ready라고 하는 것은 애플리케이션이 운영 환경에서 안정적으로 사용되는 것을 의미하는데, 단순히 기능이 잘 동작한다는 의미만을 담고 있지 않습니다.
기능이 동작하는 것을 넘어서 memory/cpu 사용량과 요청에 대한 올바른 응답과 같은 성능적인 측면과 트래픽에 대한 안정성이 보장되는 것 등을 의미합니다.
즉, spring boot actuator는 서비스되고 있는 애플리케이션이 안정적으로 운영될 수 있는지에 대한 지표들을 제공하여 더 효율적인 관리를 할 수 있도록 도와줍니다.
spring boot actuator를 사용하여 모니터링을 하는 방법은 2가지가 있습니다.
- HTTP endpoint
- JMX
HTTP endpoint 같은 경우는 web 기반으로 모니터링 할 수 있는 정보를 제공하는 방식입니다.
JMX는 저도 사용해 본적은 없지만 MBean이라는 객체를 활용한 자바의 모니터링 방식입니다.
actuator에서 제공되는 정보 같은 경우 서비스 관리자가 직접적으로 정보를 확인하는 것보다는 모니터링 도구 등과 같은 외부 서비스에 의해 사용되는 경우가 더 빈번하게 발생합니다.
그래서 kubernetes를 이용하여 클라우드 환경을 구성하는 요즘 개발 환경에서는 HTTP endpoint를 많이 활용합니다.
물론 각 서비스의 상황에 따라 JMX를 이용하게 될 수 있습니다.
spring boot actuator에서 제공하는 정보들은 다음과 같은 것들이 있습니다.
- 애플리케이션 health check
- jvm / cpu / memory / http request 등에 대한 metric 정보
- 런타임 단계의 로그 레벨 확인 / 로그 레벨 변경
- 애플리케이션 환경 변수 정보
- 애플리케이션 java / os / process 정보
- zipkin과 같은 백엔드 서비스에 tracing 정보 전송
게다가 actuator는 다른 라이브러리를 함께 활용하여 다양한 기능도 제공할 수 있습니다.
예를 들어, prometheus micrometer를 이용하여 애플리케이션에서 수집하고자 하는 metric 정보를 추가적으로 수집하고 prometheus/grafana 등과 연계를 통한 모니터링 대시보드를 구성할 수 있습니다.
또한 tracing micrometer를 이용하여 zipkin과 같은 백엔드 서비스에 tracing 정보를 수집/전송할 수 있도록 구성할 수도 있습니다.
이 외에도 actuator에 대해 더 많은 것을 알고 싶으신 분들은 Spring Boot Actuator 공식 문서를 참고해주시면 됩니다.
Actuator 기본 설정
이번에는 actuator 기본 설정을 해보겠습니다.
모든 설정은 HTTP endpoint 사용에 대한 정보를 기반으로 이루어집니다.
[ 1. dependency 추가 ]
// build.gradle
dependencies {
// spring boot actuator
implementation 'org.springframework.boot:spring-boot-starter-actuator'
}
[ 2. endpoint 노출 관리 ]
// application.yml
management:
endpoints:
web:
exposure:
include: "*" # 제공되는 모든 정보 노출
# include: health, metrics # 노출에 포함되는 정보
# exclude: beans # 노출에 제외되는 정보
[ 3. endpoint 접근 확인 ]
spring boot actuator에서 사용할 수 있는 모든 endpoint 들에 대한 정보는 Spring Boot Actuator 공식 문서 Endpoint를 통해 확인할 수 있습니다.
그중 대표적인 것들은 다음과 같이 확인해볼 수 있습니다.
- [host]:[port]/actuator/health >> "health 확인 endpoint"
- [host]:[port]/actuator/metrics >> "metric 확인 enpdoint"
Actuator Health 설정
health는 애플리케이션의 현재 상태가 어떤지에 대해서 표현되는 정보입니다.
그리고 위에서 확인한 health endpoint를 확인해 보면 단순히 status 정보만 존재하는데, 이 정보를 어떻게 활용할 수 있는지에 대해서 의문이 생길 수 있습니다.
그러므로 적용 해볼 수 있는 health 설정에 대해서 조금 더 자세하게 살펴보겠습니다.
[ 상세 정보 확인 ]
먼저 status 정보는 UP 또는 DOWN 정보만 존재합니다.
그리고 status 정보가 UP인지 DOWN인지 판단하는 것에 대한 기준도 당연히 존재합니다.
Actuator Health Indicator를 확인해보면 disk, rdb, mongo, redis, elastic 등과 같이 status 정보가 어떤 것으로 보여야 하는지에 대해 체크되는 정보들을 확인할 수 있습니다.
disk, ping 같은 것들은 기본적으로 사용되는 정보이지만 그 외 rdb, redis 등과 같은 정보들은 애플리케이션의 사용 여부에 따라 활용되고 있습니다.
자동 설정되는 모든 indicator 들의 status 값이 별도로 존재하고 모든 indicator의 status가 UP인 상태가 되어야만 최종적으로 health status가 UP이 되어 애플리케이션이 안정적인 상태라는 것을 인지할 수 있습니다.
상세 정보를 확인하는 방법은 다음과 같이 리소스 정보를 추가해 주시면 됩니다.
// application.yml
management:
endpoint:
health:
show-details: always # 항상 상세 정보 노출
# show-details: when_authorized # spring security에 인증된 사용자에게만 노출
# show-details: never # 상세 정보 항상 노출하지 않음 (default)
설정을 하고 health endpoint에 다시 접근해보면 다음과 같이 현재 애플리케이션의 상태에 따라 자동 구성이 이루어진 정보들을 확인할 수 있습니다.
[ database auto configure 확인 ]
이번에는 database 설정을 추가하여 health 정보로 자동 설정되는 것을 확인해 보겠습니다.
일반적으로 많이 사용되는 mysql과 jpa 설정을 다음과 같이 해보겠습니다.
// build.gradle
dependencies {
// mysql / jpa
runtimeOnly 'com.mysql:mysql-connector-j'
implementation 'org.springframework.boot:spring-boot-starter-data-jpa'
}
// application.yml
spring:
datasource:
url: jdbc:mysql://localhost:3306/actuator
username:
password:
그 뒤 다시 health endpoint를 접속해보면 다음과 같이 db에 대한 정보도 추가된 것을 확인할 수 있습니다.
[ kubernetes 무중단 배포를 위한 liveness, readiness 설정 ]
actuator health에는 liveness와 readiness라는 정보에 대해서도 제공해주고 있습니다.
먼저 liveness라고 하는 것은 애플리케이션이 스스로 회복이 불가능한 상태 인지를 알려주는 정보입니다.
데드락, 리소스 정보 손실 등의 사유로 인해 애플리케이션이 스스로 회복이 불가능하여 재 시작을 필수적으로 해야 되는 상황을 의미합니다.
liveness 정보를 kubernetes에 공유한 상태에서 status 값이 DOWN이 된다면 kubernetes는 pod 내부에 실행되고 있는 container를 종료하고 자동으로 재 시작 할 수 있도록 도와줍니다.
그래서 liveness를 활용할 때 조심해야 되는 것은 사소한 정보 하나에도 지속적으로 container가 재 시작되는 상황이 발생하는 것을 방지하는 것입니다..
다음으로 readiness는 애플리케이션은 정상적으로 동작이 되고 있지만 일시적으로 요청 처리가 불가능한 상태 인지를 알려주는 정보입니다.
애플리케이션이 이제 막 시작되어 캐싱 처리 등과 같은 작업이 이루어지고 있는 단계이거나 외부 의존되고 있는 db, redis 등의 문제로 인해 요청 처리가 불가능한 상황을 의미합니다.
readiness 정보를 kubernetes에 공유한 상태에서 status 값이 DOWN이 된다면 kubernetes는 사용자의 요청을 해당 pod에 전달하지 않습니다.
kubernetes에서 무 중단 배포를 위해 해당 정보를 사용하는 이유는 무엇일까 ?
우선, 무 중단 배포를 위해 사용되는 정보는 readiness입니다.
readiness 정보를 kubernetes가 알지 못한다면 서비스에 새로운 버전이 배포되어 container가 재 시작이 이루어지는 과정에서 문제가 발생할 수 있습니다.
kubernetes는 pod가 running 상태가 된다면 pod 내부에 있는 container가 요청받을 준비가 되지 않았음에도 요청 정보가 pod에 전달될 수 있습니다.
그럴 경우 container가 아직 초기화가 되어 있지 않다면 해당 요청 정보는 올바르게 처리되지 않아 사용자에게 올바르게 응답 정보가 전달되지 않게 됩니다.
하지만 만약 readiness 정보를 kubernetes에 공유한 상태라면 container가 초기화되고 있는 중에는 요청 정보를 해당 pod에 전달하지 않게 됩니다.
그리고 모든 준비가 되어 요청을 처리할 수 있는 상태로 변경되면 그 이후부터 요청 정보를 해당 pod에 전달하게 됩니다.
kubernetes에서 liveness와 readiness 정보를 사용하기 위해서는 배포되는 애플리케이션 container 설정에 livenessProbe 설정과 readinessProbe 설정을 해주면 됩니다.
또한 상황에 따라 startupProbe도 함께 활용해볼 수 있습니다.
kubernetes의 자세한 설정에 대해서는 이곳에서 다루지 않을 예정입니다.
actuator에서 liveness와 readiness 정보를 추가하기 위해서는 다음과 같은 설정들이 필요합니다.
// application.yml
management:
endpoint:
health:
probes:
enabled: true # liveness, readiness probe 사용 설정
그 뒤 다시 health endpoint에 접속해 보면 다음과 같이 probe 값들이 추가된 것을 확인할 수 있습니다.
또한 readiness 정보에 db, redis와 같은 외부 의존성 indicator를 포함시키고 싶은 경우에 다음과 같은 group 설정이 필요합니다.
설정하지 않을 경우에는 readinessState 정보로만 status 정보를 판단합니다.
// application.yml
management:
endpoint:
health:
probes:
enabled: true # liveness, readiness probe 사용 설정
group:
readiness:
include: readinessState, db # readiness group 포함 정보 설정
최종적으로 kubernetes에 사용되는 liveness, readiness의 endpoint는 다음과 같습니다.
- [host]:[port]/actuator/health/liveness
- [host]:[port]/actuator/health/readiness
Actuator Logger 설정
logger는 애플리케이션의 현재 로깅 정보가 어떤지에 대해서 알려줍니다.
logger를 확인하는 endpoint는 다음과 같습니다.
- [host]:[port]/actuator/loggers
해당 정보는 우리가 아는 spring 내부 logging 설정이 적용된 것을 보여줍니다.
이 정보를 활용하면 애플리케이션에 우리가 설정 파일을 통해 적용한 로깅 정보가 올바르게 설정되어 있는지 확인할 수 있습니다.
간단하게 테스트를 해보기 위해 다음과 같이 logging 설정을 해보겠습니다.
// application.yml
logging:
level:
root: info # root 하위는 모두 info level
com.jforj.actuator: debug # com.jforj.actuator 패키지 하위는 모두 debug level
그 뒤 logger endpoint에 접속해보면 다음과 같이 설정한 패키지 하위에 존재하는 모든 곳에 debug level이 적용되어 있는 것을 확인할 수 있습니다.
logger 설정에 대해서 얘기하는 가장 큰 이유는 재 배포를 하지 않은 상황에서도 로깅 레벨을 변경하는 기능이 제공되는 것 때문입니다.
일반적으로는 로깅 레벨을 초기 설정한 대로 사용하겠지만 갑자기 애플리케이션의 로그 정보를 상세하게 확인해야 하는 경우 배포 없이 설정 값을 변경해야 되는 상황이 필요할 수 있습니다.
이런 상황에서 actuator 사용이 올바르게 되고 있다면 손쉽게 로깅 레벨을 변경할 수 있습니다.
로깅 레벨을 변경하는 방법은 actuator에서 제공하는 다음의 endpoint를 활용하면 됩니다.
- POST [host]:[port]/actuator/loggers/[변경할 logger 계층]
그래서 만약 애플리케이션을 재 시작하지 않은 상황에 다음과 같이 api를 호출하면 로깅 레벨이 변경되어 있는 것을 확인할 수 있습니다.
이와 같이 변경한 로깅 레벨은 재 배포가 이루어지기 전까지 계속 유지됩니다.
그렇기 때문에 만약 재 배포를 하거나 재 시작을 하게 되는 경우 actuator를 이용하여 변경한 로깅 레벨 설정은 모두 삭제되고 프로젝트에 설정되어 있는 로깅 레벨로 다시 변경 적용 됩니다.
Actuator Metric
metric은 애플리케이션 내부에서 수치적으로 측정할 수 있는 데이터 값들에 대한 정보입니다.
대표적으로 가장 많이 궁금해하는 정보들인 애플리케이션의 cpu/memory/disk 등에 대한 정보들을 확인할 수 있습니다.
metric 정보 같은 경우 가장 많이 사용되는 방식은 prometheus/grafana 등과 같은 외부 모니터링 도구들과 연계하는 방법입니다.
actuator에 prometheus micrometer를 함께 활용하여 애플리케이션에서 수집된 metric 정보를 수집하고, 수집된 정보를 grafana에서 대시보드로 구성하여 손쉽게 애플리케이션을 관리할 수 있도록 할 수 있습니다.
actuator의 metric에서 다른 중요한 요소 중 한 가지는 actuator가 기본적으로 수집하는 정보들 외에도 애플리케이션 내부에서 발생되는 정보를 이용하여 추가적인 metric을 구성할 수 있는 것입니다.
예를 들어, 사용자가 로그인 한 행위에 대한 결과 정보를 수집하여 하나의 metric으로 구성할 수 있고 최종적으로 grafana에서 사용자 로그인 행위에 대한 대시보드를 제공할 수 있습니다.
또한 grafana의 alert rule 설정을 통해 수집된 사용자 로그인 실패 정보를 이용하여 주기적인 알림을 제공할 수 있습니다.
이처럼 애플리케이션 내부의 비즈니스 도메인 정보를 별도로 수집하여 다른 도구들과 함께 활용되어 모니터링 및 관리를 하는데 많은 도움이 될 수 있습니다.
다음 글에서 애플리케이션 내부 비즈니스에서 발생되는 데이터들을 수집하여 kubernetes 기반 prometheus/grafana를 함께 활용하는 방법에 대해 소개해 보겠습니다.
이상으로 애플리케이션 모니터링을 위한 spring boot actuator 개념 정리 및 구성 가이드에 대해 간단하게 알아보는 시간이었습니다.
읽어주셔서 감사합니다.
댓글