[Spring] 스프링 액추에이터(Actuator)

이미지 출처: https://blog.onesaitplatform.com/wp-content/uploads/2022/05/header_spring_boot_actuators-800x445.jpg

스프링 부트 액추에이터

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

JMX(Java Management Extensions)는 실행 중인 애플리케이션의 상태를 모니터링하고 설정을 변경할 수 있게 해주는 API

액추에이터를 사용하려면 다음과 같이 spring-boot-starter-actuator의존성을 추가해야 한다.

Maven

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

Gradle

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-actuator'
}

엔드포인트

• 액추에이터의 엔드포인트는 애플리케이션의 모니터링을 사용하는 경로이다.
• 스프링 부트에는 여러 내장 엔트포인트가 포함돼 있으며, 커스텀 엔드포인트를 추가할 수도 있다.
• 액추에이터를 추가하면 기본적으로 엔드포인트 URL로 /acutator가 추가되며 이 뒤에 경로를 추가해 상세 내역에 접근한다.
• 만약 /acutator가 아닌 다른 경로를 사용하고 싶다면 application.properties파일에 다음과 같이 추가한다.
  management.endpoints.web.base-path=/custom-path

자주 활용되는 엔드포인트

기본 엔드포인트

• /health: 애플리케이션의 전체적인 상태(UP, DOWN, OUT_OF_SERVICE 등)를 반환합니다.
• /info: 애플리케이션, 환경, 디펜던시 등에 대한 상세 정보를 반환합니다.
• /beans: 애플리케이션 컨텍스트에 등록된 모든 Bean 목록을 반환합니다.
• /conditions: 애플리케이션 로딩 시 조건 평가 결과를 반환합니다.
• /env: 애플리케이션 환경 변수 목록을 반환합니다.
• /metrics: 다양한 애플리케이션 메트릭 정보를 반환합니다. (가능한 경우 추가 구성 필요)
• /mappings: 애플리케이션에 등록된 모든 요청 매핑 정보를 반환합니다. (웹 애플리케이션에만 해당)
• /logfile: 애플리케이션 로그 파일 내용을 반환합니다. (보안상 주의 필요)
• /shutdown: 애플리케이션을 종료합니다. (보안상 주의 필요)

Spring MVC, Spring WebFlux에서 추가로 사용할 수 있는 엔드포인트는 다음과 같다.

1. heapdump

• 이 엔드포인트는 현재 애플리케이션의 heap dump 스냅샷을 생성하여 반환한다.
• 핫스팟(HotSpot) VM 상에서 hporf포맷의 파일이 반환되며, OpenJ9 JVM에서는 PHD 포맷 파일을 반환한다.
• 메모리 누수(memory leak) 디버깅이나 메모리 사용량 분석에 유용하지만, 생성된 파일은 용량이 크므로 주의해서 사용해야 한다.
• 보안상의 이유로 기본적으로 활성화되지 않으므로 별도 설정이 필요하다. 다음과 같은 설정을 통해 활성화할 수 있다.

management.health.heapdump.enabled=true

2. /jolokia (Jolokia)

• Jolokia는 JVM(Java Virtual Machine)에 대한 원격 관리를 위한 HTTP 기반 프로토콜
• 이 엔드포인트를 통해 MBean(Management Bean)에 접근하여 다양한 애플리케이션 데이터를 조회하거나 제어할 수 있다.

3. /logfile (logfile)

• 이 엔드포인트는 애플리케이션 로그 파일 내용을 반환한다.
• 로그 정보는 중요한 시스템 정보이므로 노출 시 보안 문제가 발생할 수 있다. 따라서 테스트 환경이나 개발 환경에서만 사용하는 것이 좋다.

사용:

보안상의 이유로 기본적으로 활성화되지 않으므로 별도 설정이 필요하며 다음과 같은 설정을 통해 활성화할 수 있다.

management.endpoints.logfile.enabled=true

4. /prometheus (Prometheus)

• Prometheus는 모니터링 시스템이며, 이 엔드포인트를 통해 Prometheus가 쉽게 애플리케이션 메트릭 정보를 수집할 수 있도록 제공된다.

엔드포인트 활성화

management.endpoint.shutdown.enabled=true
management.endpoint.caches.enabled=false

• 위 예제의 설정은 엔드포인트의 shutdown 기능은 활성화하고 caches 기능은 비활성화하겠다는 의미이다.
• 또한 엔드포인트의 노출 여부만 설정하는 것도 가능하다. 노출 여부는 JMX를 통한 노출과 HTTP를 통한 노출이 있어 다음과 같이 설정이 구분된다.

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

• 위 설정을 해석하면 web과 jmx 환경에서 엔드포인트를 전체적으로 노출하며, 스레드 덤프(threaddump)와 힙 덤프(heapdump_ 기능은 제외하겠다는 의미이다.
• 엔드포인트는 애플리케이션에 관한 민감한 정보를 포함하고 있으므로 노출 설정을 신중하게 고려해야 한다.

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

액추에이터의 /info 엔드포인트를 활용하면 가동 중인 애플리케이션의 정보를 볼 수 있다.

• build: META-INF/build-info.properties file의 빌드 정보를 보여줌
• env: info로 시작하는 모든 속성 값을 보여줌
• git: git.properties의 정보를 보여줌
• java: Java runtime 정보를 보여줌
• os: OS 정보를 보여줌

  management.info.env.enabled=true
  management.info.build.enabled=true
  management.info.git.enabled=true
  management.info.java.enabled=true
  management.info.os.enabled=true

제공하는 정보의 범위는 application.properties 파일에 info.로 시작하는 속성 값들을 정의하여 정할 수 있다.

management.info.env.enabled=true
info.application.name = Actuator info
info.application.description= A demo Spring project with information
info.organization = How to do in Java

localhost:8080/actuator/info를 입력하면 다음과 같은 페이지가 출력된다.

"application":{"name":"Actuator info","description":"A demo Spring project with information"},"organization":"How to do in Java","java":{"version":"21.0.2","vendor":{"name":"Oracle Corporation"},"runtime":{"name":"OpenJDK Runtime Environment","version":"21.0.2+13-58"},"jvm":{"name":"OpenJDK 64-Bit Server VM","vendor":"Oracle Corporation","version":"21.0.2+13-58"}},"os":{"name":"Mac OS X","version":"14.2.1","arch":"aarch64"}}

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

액추에이터의 /health를 입력하면 애플리케이션의 상태를 확인할 수 있다.
상태를 확인할 수 있는 상태 지표는 다음과 같다.

• UP
• DOWN
• UNKNOWN
• OUT_OF_SERVICE

이 결과는 주로 네트워크 계층 중 L4(Loadbalancing) 레벨에서 애플리케이션의 상태를 확인하기 위해 사용된다.
상세 상태를 확인하고 싶다면 application.properties에 다음과 같은 속성을 추가하면 된다.
management.endpoint.health.show-details=always

show-details에서 확인할 수 있는 값은 다음과 같다.

• never(기본값): 세부 사항은 표시하지 않음
• when-authorized: 승인된 사용자에게만 세부 상태를 표시함. 확인 권한은 application.properties에 추가한 management.endpoint.health.roles 속성으로 부여할 수 있음.
• always: 모든 사용자에게 세부 상태를 표시.

아래는 /actuator/info 경로로 접속했을 때 보여지는 예시 페이지

{"status":"UP",
"components":
{"db":{"status":
"UP","details":
{"database":"PostgreSQL","validationQuery":"isValid()"}},
"diskSpace":{"status":"UP","details":
{"total":245107195904,"free":140235055104,"threshold":10485760,
"path":"..../Spring/spring-study/.","exists":true}},"ping":{"status":"UP"}}}

참고로 인프라 관련 상태까지 확인할 수 있다. (위에서 PostgreSQL)

Bean 정보 확인(/beans)

• 액추에이터의 /beans 엔드포인트를 사용하면 스프링 컨테이너에 등록된 스프링 Bean의 전체 목록을 표시할 수 있다.
• 이 엔드포인트는 JSON 형식으로 빈의 정보를 반환한다.
• 간단하게 출력된 내용은 다음과 같다.

{"contexts":
{"application":
{"beans":
{"spring.jpa-org.springframework.boot.autoconfigure.orm.jpa.JpaProperties":
{"aliases":[],"scope":"singleton",
"type":"org.springframework.boot.autoconfigure.orm.jpa.JpaProperties",
"dependencies":[]},:
...

자동설정 내역 확인(/conditions)

• 스프링 부트의 자동설정(AutoConfiguration) 조건 내역을 확인하려면 /conditions 엔드포인트를 사용한다.
• 아래는 /actuator/conditions 경로로 접속했을 때 보여지는 페이지 일부이다.

{"contexts":
{"application":{
"positiveMatches":
{"SpringDocConfiguration":
[{"condition":"OnWebApplicationCondition",
"message":"@ConditionalOnWebApplication (required) found 'session' scope"},
{"condition":"OnPropertyCondition","message":"@ConditionalOnProperty 
(springdoc.api-docs.enabled) matched"}],
"SpringDocConfiguration#fileSupportConverter"
                                               ...

출력 내용은 크게 positiveMatches와 negativeMatches 속성으로 구분되는데, 자동설정의 @Conditional에 따라 평가된 내용을 표시한다.

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

• /env 엔드포인트는 스프링의 환경변수 정보를 확인하는 데 사용됩니다. 기본적으로 application.properties 파일의 변수들이 표시되며, OS, JVM의 환경변수도 함께 표시된다.
• 아래는 /actuator/env 경로로 접속했을 때 보여지는 페이지 일부이다.

{"activeProfiles":[],
"propertySources":
[{"name":"server.ports","properties":
{"local.server.port":{"value":"******"}}},
{"name":"servletContextInitParams","properties":{}},
{"name":"systemProperties","properties":
{"java.specification.version":{"value":"******"},
"sun.jnu.encoding":{"value":"******"},"java.class.path"
:{"value":"******"},"java.vm.vendor":{"value":"******"},"sun.arch.data.model":
...

만약 일부 내용에 포함된 민감한 정보를 가리기 위해서는

management.endpoint.env.keys-to-sanitize 속성을 사용하면 된다. 해당 속성에 넣을 수 있는 값은 단순 문자열이나 정규식을 활용한다.

로깅 레벨 확인(/loggers)

• 애플리케이션의 로깅 레벨 수준이 어떻게 설정돼 있는지 확인하려면 /loggers 엔드포인트를 사용할 수 있다.
• 아래는 /actuator/loggers 경로로 접속했을 때 보여지는 페이지 일부이다.

{"levels":["OFF","ERROR","WARN","INFO","DEBUG","TRACE"],
"loggers":{"ROOT":{"configuredLevel":"INFO","effectiveLevel":"INFO"},
"_org":{"effectiveLevel":"INFO"},"_org.springframework":{"effectiveLevel":"INFO"},
"_org.springframework.web":{"effectiveLevel":"INFO"},
"_org.springframework.web.servlet":{"effectiveLevel":"INFO"},
"_org.springframework.web.servlet.HandlerMapping":{"effectiveLevel":"INFO"},
"_org.springframework.web.servlet.HandlerMapping.Mappings":{"effectiveLevel":"INFO"},
"com":{"effectiveLevel":"INFO"},"com.zaxxer":{"effectiveLevel":"INFO"},
"com.zaxxer.hikari":{"effectiveLevel":"INFO"},"com.zaxxer.hikari.HikariConfig":
{"effectiveLevel":"INFO"},"com.zaxxer.hikari.HikariDataSource":{"effectiveLevel":"INFO"},"com.zaxxer.hikari.pool":
                                                                   ...

만약 POST 형식으로 호출하면 로깅 레벨을 변경하는 것도 가능하다.

참고

• 스프링 부트 핵심 가이드 "스프링 부트를 활용한 애플리케이션 개발 실무" , 장정우, 2022