[스프링 부트 핵심 가이드] 11 액추에이터 활용하기

## 엔드포인트 활성화
management.endpoint.shutdown.enabled=true
management.endpoint.caches.enabled=false

목차

11 액추에이터 활용하기

ㄴ11.1 프로젝트 생성 및 액추에이터 종속성 추가

ㄴ11.2 앤드포인트

ㄴ11.3 액추에이터 기능 살펴보기

    ㄴ11.3.1 애플리케이션 기본 정보(/info)

    ㄴ11.3.2 애플리케이션 상태(/health)

    ㄴ11.3.3 빈 정보 확인(/beans)

    ㄴ11.3.4 스프링 부트의 자동설정 내역 확인(/conditions)

    ㄴ11.3.5 스프링 환경변수 정보(/env)

    ㄴ11.3.6 로깅 레벨 확인(/logger)

ㄴ11.4 액추에이터에 커스텀 기능 만들기

    ㄴ11.4.1 정보 제공 인터페이스의 구현체 생성

    ㄴ11.4.2 커스텀 엔드포인트 생성

 

 

애플리케이션을 개발하고 나서 운영 단계에 접어들면 애플리케이션이 정상적으로 작동하는지 모니터링하는 것이 중요한데, 이것을 스프링 부트의 액추에이터에서 제공한다.

 

스프링 부트 액추에이터는 HTTP 엔드포인트나 JMX(Java Management Extensions)를 활용해 애플리케이션을 모니털이하고 관리하는 기능을 제공한다.

JMX는 실행중인 애플리케이션의 상태를 모니터링하고 설정을 변결할 수 있게 해주는 API이며, MBeans(Managed Beans)를 생성해서 JMX를 통해 리소스 관리를 하면 된다.

11.1 프로젝트 생성 및 액추에이터 종속성 추가

pom.xml

<dependencies>

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

</dependencies>

 

build.gradle

implementation("org.springframework.boot:spring-boot-starter-actuator")

 

11.2 엔드포인트

액추에이터의 엔드포인트 > 애플리케이션의 모니터링을 사용하는 경로.

 

액추에이터를 추가하면 기본적으로 엔드포인트 URL로 "/actuator"가 추가되며 이 뒤에 경로를 추가해 상세 내역에 접근 가능하다.

만일 "/actuator" 경로가 아닌 다른 경로를 사용하고 싶으면 application.properties or application.yml에서 기본 경로를 변경하면 된다.

 

application.properties

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

 

 

기본 엔드 포인트는 다음과 같다.

HTTP 메서드	경로	설명	디폴트 활성화
GET	/auditevents	호출된 감사(audit) 이벤트 리포트를 생성한다.	No
GET	/beans	스프링 애플리케이션 컨텍스트의 모든 빈을 알려준다.	No
GET	/conditions	성공 또는 실패했던 자동-구성 조건의 내역을 생성한다.	No
GET	/configprop	모든 구성 속성들을 현재 값과 같이 알려준다.	No
GET,POST,DELETE	/env	스프링 애플리케이션에 사용할 수 있는 모든 속성 근원과 이 근원들의 속성을 알려준다.	No
GET	/env/{toMatch}	특정 환경 속성의 값을 알려준다.	No
GET	/health	애플리케이션의 건강 상태 정보를 반환한다.	Yes
GET	/heapdump	힙(heap) 덤프를 다운로드한다.	No
GET	/httptrace	가장 퇴근의 100개 요청에 대한 추적 기록을 생성한다.	No
GET	/info	개발자가 정의한 애플리케이션에 관란 정보를 반환한다.	Yes
GET	/loggers	애플리케이션의 패키지 리스트(각 패키지의 로깅 레벨이 포함된)를 생성한다.	No
GET,POST	/loggers/{name}	지정된 로거의 로깅 레벨(구성된 로깅 레벨과 유효 로깅 레벨 모두)을 반환한다. 유효 로깅 레벨은 HTTP POST 요청으로 설정될 수 있다.	No
GET	/mappings	모든 HTTP 매핑과 이 매핑들을 처리하는 핸들러 메서드들의 내역을 제공한다.	No
GET	/metrics	모든 메트릭 리스트를 반환한다.	No
GET	/metrics/{name}	지정된 메트릭의 값을 반환한다.	No
GET	/scheduledtasks	스케줄링된 모든 태스크의 내역을 제공한다.	No
GET	/threaddump	모든 애플리케이션 스레드의 내역을 반환한다.	No

 

만일 Spring MVC, Spring WebFlux, Jersey를 사용하면 다음과 같은 엔드포인트를 사용할 수 있다.

HTTP 메서드	경로	설명	디폴트 활성화
GET	/heapdump	힘 덤프 파일을 반환한다. 핫스팟(HotSpot) VM 상에서 hprof 포맷의 파일이 반환되며, OpenJ9JVM에서는 PHD 포맷 파일을 반환한다.	No
GET	/jolokia	Jolokia가 클래스 패스에 있을 때 HTTP를 통해 JMX 빈을 표시한다. jolokia-core 모듈에 대한 의존성 추가가 필요하며, WebFlux에서는 사용할 수 없다.	No
GET	/logfile	logging.file.name 또는 logging.file.path 속성이 설정 되어 있는 경우 로그 파일의 내용를 반환한다.	No
GET	/Prometheus	Prometheus 서버에서 스크랩할 수 있는 형시긍로 메트릭을 표시한다. micrometer-registry- prometheus 모듈의 의존성 추가가 필요하다.	No

 

엔드포인트는 활성화 여부와 노출 여부를 설정할 수 있다. 비활성화 된 엔드포인트는 애플리케이션 컨텍스트에서 완전히 제거된다.

 

application.properties

## 엔드포인트 활성화
management.endpoint.shutdown.enabled=true
management.endpoint.caches.enabled=false

## 엔드포인트 노출 설정
## HTTP 설정
management.endpoint.web.exposure.include=*
management.endpoint.web.exposure.exclude=threaddump,heapdump

## JMX 설정
management.endpoint.jmx.exposure.include=*
management.endpoint.jmx.exposure.exclude=threaddump,heapdump

 

해석 >

web과 jmx 환경에서 엔드포인트를 전체적으로 노출하고, 스레드 덤프와 힙 덤프 기능을 제외하겠다는 의미

 

엔드포인트 노출 설정 시 애플리케이션에 관한 민감 정보를 포함하기 때문에 신중히 고려해서 사용해야함.

 

11.3 액추에이터 기능 살펴보기

• info : 애플리케이션 기본 정보

http://localhost:8080/actuator/info

> 현재 가동중인 애플리케이션의 정보를 표시함

 

• health : 애플리케이션 상태

 http://localhost:8080/actuator/health

> 애플리케이션의 현재 상태 정보를 표시함

 

• beans : 빈 정보 확인

http://localhost:8080/actuator/beans

> 애플리케이션의 모든 Spring Bean 목록을 표시함

 

• conditions : 스프링 부트의 자동설정 내역 확인

http://localhost:8080/actuator/conditions

> 스프링부트의 자동설정(Auto-configuration)과 직접 설정한 configuration class 들의 성공 여부와 이유를 설명함.

 

• env : 스프링 환경변수 정보

http://localhost:8080/actuator/env

> 스프링의 모든 환경변수 정보를 표시함

 

• loggers : 로깅 레벨 확인

http://localhost:8080/actuator/loggers

> 애플리케이션의 로깅레벨 수준 설정 표시함

 

 

공식 문서에서 액추에이터의 기능을 더 자세히 살펴 볼 수 있다.

https://docs.spring.io/spring-boot/docs/3.0.x/actuator-api/htmlsingle/#httpexchanges

Spring Boot Actuator Web API Documentation

 

11.4 액추에이터에 커스텀 기능 만들기

액추에이터는 다양한 정보를 가공해서 제공하는데, 이렇게 공식으로 제공하는 기능 이외에 개발자가 기능을 커스텀할 수 있다.

 

커스텀 기능을 개발하는 방식

• 기존 기능에 내용을 추가하는 방식
• 새로운 엔드포인트를 개발하는 방식

예를 들어 ' http://localhost:8080/actuator/note' 라는 새로운 엔드포인트를 개발할 때는 다음과 같이 하면 된다.

@Component
@EndPoint(id = "note")
public class NoteEndpoint {

	private Map<String, Object> noteContent = new HashMap<>();
    
    @ReadOperation
    public Map<String, Object> getNote() {
    	return noteContent;
    }
    
    @WriteOperation
    public Map<String, Object> writeNote(String key, Object value) {
    	noteContent.put(key, value);
    	return noteContent;
    }
    
    @DeleteOperation
    public Map<String, Object> deleteNote(String key) {
    	noteContent.remove(key);
    	return noteContent;
    }
}

각 Read, Write, Delete Operation을 설정하여 엔드포인트에서 해당 HTTP 메서드를 사용하면 설정한대로 작동된다.

 

 

스프링 부트 액추에이터에 대한 자세한 내용은 공식 홈페이지에서 확인 가능

> https://docs.spring.io/spring-boot/docs/current/reference/html/actuator.html

Production-ready Features