액추에이터란?
스프링 부트 액추에이터(Spring Boot Actuator)
- 애플리케이션의 상태를 모니터링하고 관리하기 위한 도구
- 서비스의 다양한 측면을 모니터링하고 운영 환경에서 문제를 식별하고 감시한다.
HTTP Endpoint나JMX를 활용한다.
💡 Tip. JMX란?
JMX(Java Management Extensions)는 실행 중인 애플리케이션의 상태를 모니터링하고 설정을 변경할 수 있게 해주는 APP이다. JMX를 통해 리소스 관리를 하려면 MBeans(Managed Beans)를 생성해야 한다.
프로젝트 설정
- Maven
pom.xml
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-actuator</artifactId>
</dependency>- Gradle
implementation 'org.springframework.boot:spring-boot-starter-actuator'엔드포인트
액추에이터의 엔드포인트는 애플리케이션의 모니터링을 사용하는 경로이다. 스프링 부트에는 여러 내장 엔드포인트가 포함돼 있으며, 커스텀 엔드포인트를 추가할 수도 있다.
액추에이터를 추가하면 기본적으로 엔드포인트 URL로 /actuator가 추가되며 이 뒤에 경로를 추가해 상세 내역에 접근한다. 만약 /actuator 경로가 아닌 다른 경로를 사용하고 싶다면 아래와 같이 application.properties파일에 작성한다.
management.endpoints.web.base-path=/custom-path주요 엔드포인트
자주 활용되는 액추에이터의 엔드포인트는 다음과 같다.
| 엔드포인트 | 기능 | 반환 값 | 사용 예시 |
|---|---|---|---|
/actuator/health | 애플리케이션의 상태 확인 | UP, DOWN, OUT_OF_SERVICE, UNKNOWN | 애플리케이션의 상태 확인 |
/actuator/info | 애플리케이션 정보 제공 | JSON 형식의 애플리케이션 정보 | 애플리케이션 메타데이터 확인 |
/actuator/metrics | 애플리케이션 성능 지표 제공 | 다양한 메트릭스 데이터 | 시스템 자원 사용량 모니터링 |
/actuator/env | 환경 변수와 설정 정보 제공 | 현재 설정된 환경 변수와 프로퍼티 값 | 환경 변수 및 설정 값 확인 |
/actuator/beans | 로드된 모든 빈(bean) 나열 | 애플리케이션의 빈 정의 목록 | 로드된 빈 정보 확인 |
/actuator/loggers | 로깅 설정 조회 및 변경 | 현재 로거 설정 정보 | 로깅 설정 확인 및 변경 |
/actuator/threaddump | JVM의 쓰레드 덤프 제공 | 현재 쓰레드 상태 정보 | 쓰레드 상태 분석 |
/actuator/httptrace | 최근의 HTTP 요청/응답 추적 정보 제공 | HTTP 요청 및 응답 정보 | HTTP 요청/응답 로그 확인 |
/actuator/mappings | 모든 @RequestMapping 경로 나열 | 매핑된 경로 목록 | 요청 경로 정보 확인 |
/actuator/scheduledtasks | 스케줄된 작업 정보 제공 | 현재 스케줄된 작업 목록 | 스케줄된 작업 확인 |
이 중 중요한 몇 가지를 실습해 보도록 하겠다.
애플리케이션 정보 (/info)
액추에이터의 /info 엔드포인트를 활용하면 가동 중인 애플리케이션의 정보를 볼 수 있다. 제공하는 정보의 범위는 애플리케이션에서 몇 가지 방법을 거쳐 제공할 수 있으나 application.properties파일에 info. 로 시작하는 속성 값들을 정의하는 것이 가장 쉬운 방법이다.
## 액추에이터 info 정보 설정
info.organization.name=wikibooks
info.contact.email=thinkground.flature@email.com
info.contact.phoneNumber=010-1234-5678그러고 나서 애플리케이션을 가동한 후 브라우저에서 아래 URL에 접근하면 아래와 같은 결괏값이 확인된다.
http://localhost:8080/actuator/info
{
"organization":{
"name":"wikibooks"
},
"contact":{
"email":"thinkground.flature@email.com",
"phoneNumber":"010-1234-5678"
}
}애플리케이션 상태(/health)
1) 기본 동작
/health 엔드포인트를 활용하면 애플리케이션의 상태를 확인할 수 있다. 별도의 설정 없이 다음 URL에 접근하면 아래와 같은 결과를 확인할 수 있다.
http://localhost:8080/actuator/health
{"status":"UP"}예제에서는 UP만 표시되지만 status 속성에서 확인할 수 있는 상태 지표는 다음과 같다.
UPDOWNUNKNOWNOUT_OF_SERVICE
이 결과는 주로 네트워크 계층 중 L4(Loadbalancing) 레벨에서 애플리케이션의 상태를 확인하기 위해 사용된다. 상세 상태를 확인하고 싶다면 아래와 같이 설정하면 된다.
2) 상세 동작
## 액추에이터 health 상세 내역 활성화
management.endpoint.health.show-details=always위 예제의 show-details 속성에서 설정할 수 있는 값은 다음과 같다.
never(기본값) : 세부 사항은 표시하지 않는다.when-authorized: 승인된 사용자에게만 세부 상태를 표시한다. 확인 권한은application.properties에 추가한management.endpoint.health.roles속성으로 부여할 수 있다.always: 모든 사용자에게 세부 상태를 표시한다.
always로 설정을 변경하고 애플리케이션을 재가동한 후 애플리케이션 상태를 확인하면 아래와 같은 결괏값을 얻을 수 있다.
{
"status":"UP",
"components":{
"diskSpace":{
"status":"UP",
"details":{
"total":511013888000,
"free":214821752832,
"threshold":10485760,
"exists":true
}
},
"ping":{
"status":"UP"
}
}
}만약 애플리케이션에 데이터베이스가 연동 돼 있으면 인프라 관련 상태까지 확인할 수 있다.
빈 정보 확인(/beans)
액추애이터의 /beans 엔드포인트를 사용하면 스프링 컨테이너에 등록된 스프링 빈의 전체 목록을 표시할 수 있다. 이 엔드포인트는 JSON 형식으로 빈의 정보를 반환한다. 다만 스프링은 워낙 많은 빈이 자동으로 등록되어 운영되기 때문에 실제로 내용을 출력해서 육안으로 내용을 파악하기는 어렵다. 간단하게 출력된 내용을 보면 아래와 같다.
http://localhost:8080/actuator/beans
{
"contexts":{
"application":{
"beans":{
"endpointCachingOperationInvokerAdvisor":{
"aliases":[],
"scope":"singleton",
"type":"org.springframework.boot.actuate.endpoint.invoker.cache.CachingOperationInvokerAdvisor", ...
},
"parentId":null
}
}
}자동설정 내역 확인(/conditions)
스프링 부트의 자동설정(AutoConfiguration) 조건 내역을 확인하려면 /conditions 엔드포인트를 사용한다.
http://localhost:8080/actuator/conditions
{
"contexts":{
"application":{
"positiveMatches":{
"AuditEventsEndpointAutoConfiguration":[
{
"condition":"OnAvailableEndpointCondition",
"message":"@ConditionalOnAvailableEndpoint no property management.endpoint.auditevents.enabled found so using endpoint default; @ConditionalOnAvailableEndpoint marked as exposed by a 'management.endpoints.jmx.exposure' property"
}
],
"BeansEndpointAutoConfiguration":[
{
"condition":"OnAvailableEndpointCondition",
"message":"@ConditionalOnAvailableEndpoint no property management.endpoint.beans.enabled found so using endpoint default; @ConditionalOnAvailableEndpoint marked as exposed by a 'management.endpoints.jmx.exposure' property"
}
],
"BeansEndpointAutoConfiguration#beansEndpoint":[
{
"condition":"OnBeanCondition",
"message":"@ConditionalOnMissingBean (types: org.springframework.boot.actuate.beans.BeansEndpoint; SearchStrategy: all) did not find any beans"
}
],...
}
}
}
}출력 내용은 크게 positiveMatches 와 negativeMatches 속성으로 구분되는데, 자동설정의 @Conditional에 따라 평가된 내용을 표시한다.
스프링 환경변수 정보(/env)
/env 엔드포인트는 스프링의 환경변수 정보를 확인하는 데 사용된다. 기본적으로 application.properties 파일의 변수들이 표시되며, OS, JVM의 환경변수도 함께 표시된다.
http://localhost:8080/actuator/env
# 일부 내용만 발췌
{
"activeProfiles":[
],
"propertySources":[
{
"name":"server.ports",
"properties":{
"local.server.port":{
"value":8080
}
}
},
{
"name":"servletContextInitParams",
"properties":{
}
},
{
"name":"systemProperties",
"properties":{
"sun.desktop":{
"value":"windows"
},
"awt.toolkit":{
"value":"sun.awt.windows.WToolkit"
},
"java.specification.version":{
"value":"11"
},
"sun.cpu.isalist":{
"value":"amd64"
},
"sun.jnu.encoding":{
"value":"MS949"
},
...
}
}
}
}만약 일부 내용에 포함된 민감한 정보를 가리기 위해서는 management.endpoint.env.keys-to-sanitize 속성을 사용하면 된다. 해당 속성에 넣을 수 있는 값은 단순 문자열이나 정규식을 활용한다.
로깅 레벨 확인(/loggers)
애플리케이션의 로깅 레벨 수준이 어떻게 설정돼 있는지 확인하려면 /loggers 엔드포인트를 사용할 수 있다.
http://localhost:8080/actuator/loggers
# 일부 내용만 발췌
{
"levels":[
"OFF",
"ERROR",
"WARN",
"INFO",
"DEBUG",
"TRACE"
],
"loggers":{
"ROOT":{
"configuredLevel":"INFO",
"effectiveLevel":"INFO"
},
"_org":{
"configuredLevel":null,
"effectiveLevel":"INFO"
},
"_org.springframework":{
"configuredLevel":null,
"effectiveLevel":"INFO"
},
"_org.springframework.web":{
"configuredLevel":null,
"effectiveLevel":"INFO"
},
"_org.springframework.web.servlet":{
"configuredLevel":null,
"effectiveLevel":"INFO"
},
"groups":{
"web":{
"configuredLevel":null,
"members":[
"org.springframework.core.codec",
"org.springframework.http",
"org.springframework.web",
"org.springframework.boot.actuate.endpoint.web",
"org.springframework.boot.web.servlet.ServletContextInitializerBeans"
]
},
"sql":{
"configuredLevel":null,
"members":[
"org.springframework.jdbc.core",
"org.hibernate.SQL",
"org.jooq.tools.LoggerListener"
]
}
}
}위 예제는 GET 메서드로 호출한 결과이며, POST 형식으로 호출하면 로깅 레벨을 변경하는 것도 가능하다.
활성화 여부
엔드포인트 활성화는 기능 자체를 활성화할 것인지를 결정하는 것으로, 비활성화된 엔드포인트는 애플리케이션 컨텍스트에서 완전히 제거된다. 엔트포인트를 활성화하려면 application.propertis 파일에 속성을 추가하면 된다.
## 엔드포인트 활성화
management.endpoint.shutdown.enabled=true
management.endpoint.caches.enabled=true위 예제의 설정은 엔드포인트의 shutdown기능은 활성화하고 caches 기능은 비활성화하겠다는 의미이다.
노출 여부
또한 액추에이터 설정을 통해 기능 활성화/비활성화가 아니라 엔드포인트의 노출 여부만 설정하는 것도 가능하다. 노출 여부는 JMX를 통한 노출과 HTTP를 통한 노출이 있어 아래와 같이 설정이 구분된다.
## 엔드포인트 노출 설정
## 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위 설정을 해석하면 web과 jmx 환경에서 엔드포인트를 전체적으로 노출하며, 스레드 덤프(thread dump)와 힙 덤프(heap dump) 기능은 제외하겠다는 의미이다.
기본적으로 액추에이터 엔드포인트는 보안상의 이유로 비공개되어 있다. 엔드포인트는 애플리케이션에 관한 민감한 정보를 포함하고 있으므로 노출 설정을 신중하게 고려해야한다.
