Spring Boot Actuator - 애플리케이션 상태 확인, 모니터링 지원 기능
개요
여기에서 다양한 모니터링 및 관리 목적으로 부트 애플리케이션에 사용할 수 있는 내장 HTTP 엔드포인트(Endpoint)에 대해 알아본다. 스프링 프레임워크 이전에는 애플리케이션에 이러한 유형의 모니터링 기능을 도입해야 하는 경우 이러한 모든 구성 요소를 수동으로 개발해야 했으며, 이 또한 꼭 필요한 기능이기도 했다. 그러나, 스프링 부트에는 모니터링 기능을 매우 쉽게 만들 수 있는 Actuator 모듈이 있다.
몇 가지만 구성하면 완료되고, 모든 관리 및 모니터링 관련 정보를 쉽게 사용할 수 있다. Spring boot 2 Actuator Endpoint을 구성하는 방법을 알아보겠다.
Spring Boot Actuator Module
Spring boot의 모듈을 사용하면 Actuator 코딩 및 구성 없이 운영 환경에서 애플리케이션 사용을 모니터링하고 관리할 수 있다. 이러한 모니터링 및 관리 정보는 endpoint URL과 같은 REST를 통해 노출된다.
Actuator 종속성
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-actuator</artifactId>
</dependency>
dependencies {
implementation 'org.springframework.boot:spring-boot-starter-actuator'
}
중요한 Actuator Endpoint
대부분의 애플리케이션은 /actuator 접두사와 함께 엔드포인트의 ID가 URL에 매핑되는 HTTP를 통해 엔드포인트를 노출한다. 예를 들어, 기본적으로 상태 엔드포인트 /actuator/health에 매핑된다.
기본적으로 /health만 웹 API를 통해 노출되고, 나머지는 JMX를 통해 노출된다. Web API를 통해 모든 엔드포인트를 노출하려면 management.endpoints.web.exposure.include=*를 사용한다.
management.endpoints.web.exposure.include=*
# To expose only selected endpoints
#management.endpoints.jmx.exposure.include=health,info,env,beans
중요하고 많이 사용되는 사용되는 액추에이터 엔드포인트은 다음과 같다.
| 앤드포인트 | 설명 |
|---|---|
/auditevents |
모든 자동 구성 후보와 해당 후보가 ‘적용’ 또는 ‘적용되지 않은’ 사유를 반환한다. |
/beans |
애플리케이션에 있는 모든 Spring beans의 전체 목록을 반환한다. |
/mappings |
모든 @RequestMapping. 경로의 조합된 목록을 반환한다. |
/env |
현재 환경의 속성 목록을 반환한다. |
/health |
애플리케이션 상태 정보를 반환한다. |
/caches |
사용 가능한 캐시를 반환한다. |
/conditions |
구성 및 자동 구성에서 평가된 조건을 반환한다. |
/configprops |
모든 @ConfigurationProperties를 반환한다. |
/Intergrationgraph |
스프링 통합 그래프를 보여준다. spring-intergration-core 에 대한 종속성이 필요하다. |
/loggers |
응용 프로그램의 Logger 구성. |
/scheduledtasks |
애플리케이션에서 예약된 작업을 반환한다. |
/sessions |
추적 로그를 표시한다(기본적으로 마지막 100개의 HTTP 요청). HttpTraceRepository Bean이 필요하다. |
/httptrace |
Spring 세션 지원 세션 저장소에서 사용자 세션을 검색하고 삭제할 수 있다. Spring Session을 사용하는 Servlet 기반 웹 애플리케이션이 필요하다. |
/shutdown |
응용 프로그램을 정상적으로 종료할 수 있다. 기본적으로 비활성화되어 있다. |
/threaddump |
thread dump를 수행한다. |
/metrics |
사용된 JVM 메모리, 시스템 CPU 사용량, 열린 파일 등과 같은 몇 가지 유용한 메트릭 정보를 보여준다. |
Spring 웹 애플리케이션(Spring MVC, Spring WebFlux 또는 Jersey)은 다음과 같은 추가 엔드포인트를 제공한다.
| 앤드포인트 | 설명 |
|---|---|
/heapdump |
hprof 힙 덤프 파일을 반환한다. |
/logfile |
logging.file.name 또는 logging.file.path속성이 설정된 경우 로그 파일의 내용을 표시한다. |
엔드포인트 보안
기본적으로 클래스 경로에서 사용 가능한 경우 모든 액추에이터 엔드포인트에 대해 스프링 보안이 활성화된다.
예를 들어, HTTP 엔드포인트에 대한 사용자 지정 보안을 구성하려면 특정 역할을 가진 사용자만 액세스하도록 허용하고, 다음과 같은 방법으로 WebSecurityConfigurerAdapter를 설정한다.
@Configuration(proxyBeanMethods = false)
public class ActuatorSecurity extends WebSecurityConfigurerAdapter {
@Override
protected void configure(HttpSecurity http) throws Exception {
http.requestMatcher(EndpointRequest.toAnyEndpoint()).authorizeRequests((requests) ->
requests.anyRequest().hasRole("ENDPOINT_ADMIN"));
http.httpBasic();
}
}
위의 구성은 ENDPOINT_ADMIN 역할을 가진 사용자만 동작하는 엔드포인트에 액세스 할 수 있도록 한다.
엔드포인트 활성화
기본적으로 모든 엔드포인트(/shutdown 제외)이 활성화된다. 모든 엔드포인트를 비활성화하려면 다음과 같이 속성을 설정한다.
management.endpoints.enabled-by-default=false
그런 다음 애플리케이션을 사용하려는 앤드포인트를 management.endpoint.{id}.enabled. 패턴으로 노출해야 하는 엔드포인트를 활성화한다.
management.endpoint.health.enabled=true
management.endpoint.loggers.enabled=true
CORS 지원
CORS 지원은 기본적으로 비활성화되어 있고, .management.endpoints.cors.allowed-origins 속성을 설정해야 활성화된다.
management.endpoints.web.cors.allowed-origins=https://example.com
management.endpoints.web.cors.allowed-methods=GET,POST
여기서 관리 컨텍스트 경로는 /management이다.
응답 캐싱
액추에이터 엔드포인트은 매개 변수를 사용하지 않는 읽기 작업에 대한 응답을 자동으로 캐시한다. cache.time-to-live 속성은 엔드포인트가 응답을 캐시할 시간을 설정하는데 사용된다.
management.endpoint.beans.cache.time-to-live=20s
Spring Boot Actuator 프로젝트 생성
그럼, 간단한 Spring Boot 어플리케이션 예제 프로젝트를 생성해 보겠다. 이 예제로 액추에이터 엔드포인트에 액세스하여 자세한 내용을 알 수 있다.
신규 프로젝트 생성 명령
아래와 같이 curl 명령어를 사용하여 Spring Boot 신규 프로젝트를 생성한다.
curl https://start.spring.io/starter.tgz \
-d bootVersion=2.7.6 \
-d dependencies=web,actuator \
-d baseDir=spring-actuator \
-d groupId=com.devkuma \
-d artifactId=spring-actuator \
-d packageName=com.devkuma.actuator \
-d applicationName=ActuatorApplication \
-d javaVersion=11 \
-d packaging=jar \
-d type=gradle-project | tar -xzvf -
위 명령어에서는 Java 11, Gradle, Spring Boot 버전은 2.7.6을 사용하였고, 의존성으로 “web,actuator"를 추가하였다.
간단한 Rest 엔드포인트 추가
이제 하나의 간단한 Rest 엔드포인트 /hello를 애플리케이션에 추가한다.
package com.devkuma.actuator;
import java.util.Date;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
@RestController
public class HelloRestController {
@GetMapping("/hello")
public String hello() {
return "Hello User !! " + new Date();
}
}
모든 엔드포인트 노출 설정
Web API를 통해 모든 엔드포인트를 노출하기 위해 아래와 같이 설정 파일(application.properties)을 추가한다.
management.endpoints.web.exposure.include=*
Spring Boot Actuator 기동
이제 프로젝트를 기동해 보자.
엔드포인트 환경 출력
- http://localhost:8080/actuator/env
- 이 URL에서는 서버에 대한 모든 환경 구성 내용을 제공한다.
{
"activeProfiles": [],
"propertySources": [
{
"name": "server.ports",
"properties": {
"local.server.port": {
"value": 8080
}
}
},
{
"name": "servletContextInitParams",
"properties": {}
},
{
"name": "systemProperties",
"properties": {
"gopherProxySet": {
"value": "false"
},
"awt.toolkit": {
"value": "sun.lwawt.macosx.LWCToolkit"
},
"java.specification.version": {
"value": "11"
},
"sun.cpu.isalist": {
"value": ""
},
... 이하 생략 ...
엔드포인트 bean 출력
- http://localhost:8080/actuator/beans
- 이 URL에서는 컨텍스트에 로드된 모든 스프링 빈 목록 내용을 제공한다.
{
"contexts": {
"application": {
"beans": {
"endpointCachingOperationInvokerAdvisor": {
"aliases": [],
"scope": "singleton",
"type": "org.springframework.boot.actuate.endpoint.invoker.cache.CachingOperationInvokerAdvisor",
"resource": "class path resource [org/springframework/boot/actuate/autoconfigure/endpoint/EndpointAutoConfiguration.class]",
"dependencies": [
"org.springframework.boot.actuate.autoconfigure.endpoint.EndpointAutoConfiguration",
"environment"
]
},
"defaultServletHandlerMapping": {
"aliases": [],
"scope": "singleton",
"type": "org.springframework.web.servlet.HandlerMapping",
"resource": "class path resource [org/springframework/boot/autoconfigure/web/servlet/WebMvcAutoConfiguration$EnableWebMvcConfiguration.class]",
"dependencies": [
"org.springframework.boot.autoconfigure.web.servlet.WebMvcAutoConfiguration$EnableWebMvcConfiguration"
]
},
... 이하 생략 ...
엔드포인트 스레드 덤프 출력
- http://localhost:8080/actuator/threaddump
- 이 URL에서는 현재 서버 스레드 덤프가 제공됩니다.
{
"threads": [
{
"threadName": "Reference Handler",
"threadId": 2,
"blockedTime": -1,
"blockedCount": 5,
"waitedTime": -1,
"waitedCount": 0,
"lockName": null,
"lockOwnerId": -1,
"lockOwnerName": null,
"daemon": true,
"inNative": false,
"suspended": false,
"threadState": "RUNNABLE",
"priority": 10,
"stackTrace": [
{
"classLoaderName": null,
"moduleName": "java.base",
"moduleVersion": "11.0.16.1",
"methodName": "waitForReferencePendingList",
"fileName": "Reference.java",
"lineNumber": -2,
"className": "java.lang.ref.Reference",
"nativeMethod": true
},
... 이하 생략 ...
이러한 엔드포인트는 브라우저에 표준 정보를 제공한다. 여기에서는 우리가 일반적으로 참조하는 기본적인 중요 엔드포인트를 몇개 소개하였지만, 스프링 부트는 이 링크에서 언급한 것처럼 더 많은 엔드포인트를 제공한다.
액추에이터 고급 구성 옵션
관리 엔드포인트 컨텍스트 경로 변경
기본적으로 모든 엔드포인트는 /actuator을 시작으로 하는 응용프로그램의 기본 컨텍스트 경로에 제공된다. 어떤 이유로 든 애플리케이션에 /actuator로 시작하는 기존 앤드포인트를 다른 항목에 대한 기본 경로를 변경할 수 있다.
application.properties에 새로운 기본 경로를 지정하기만 하면 된다.
management.endpoints.web.base-path=/manage
이제 새 URL에서 모든 액추에이터 엔드포인트에 액세스할 수 있다. 예를 들면, 아래와 같다.
- /manage/health
- /manage/dump
- /manage/env
- /manage/beans
관리 서버 포트 변경
관리 엔드포인트 포트를 변경하려면 application.properties 설정 파일에 이 항목을 추가하면 된다.
management.server.port=8081
요약
이 스프링 부트 액추에이터 프로젝트 예제에서 몇 가지 쉬운 구성으로 관리 및 모니터링 엔드포인트를 구성하는 방법에 대해 알아보았다.
프로젝트 만들면서 애플리케이션 상태 확인 기능을 추가하거나 모니터링 지원을 추가해야 해야 한다면, Spring 액추에이터 도입을 검토해 보는 것도 좋은 방법일 것이다.
참조
- 위에 모두 완성된 프로젝트 코드는 여기에 올려 두었다.