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

스프링 부트 액추에이터

개발 단계 이후 운영 단계에서 정상 동작 확인을 위해 모니터링 환경을 구축해야 한다.

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

액추에이터의 환경 설정과 활용 방법에 대해 알아보자.

 

액추에이터 의존성

implementation 'org.springframework.boot:spring-boot-starter-actuator'

 

의존성은 아래에서 확인 가능하다.

 

Production-ready Features

 

엔드포인트

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

여러 내장 엔트포인트가 스프링 부트에 포함되어 있고, 커스텀 엔드포인트도 추가 가능하다.

 

엑추에이터를 추가하면 기본 엔드포인트 URL로 /actuator가 추가된다.

이 뒤에 경로를 추가해 상세 내역에 접근한다.

 

액추에이터 엔드포인트  기본 경로 변경

application.properties 파일에서 기본 경로를 변경할 수 있다.

# 스프링 부트 문서의 3.1. Customizing the Management Endpoint Paths에서 확인 가능
management.endpoints.web.base-path=/manage

 

기본 엔드포인트 리스트

액추에이터의 기본 엔드포인트 리스트

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

 

엔드포인트 활성화, 노출

엔드포인트는 활성화 여부와 노출 여부를 설정할 수 있다.

엔드포인트 활성화

기본적으로 셧다운을 제외한 모든 엔드포인트가 활성화되어 있다.

엔드포인트를 활성화 하려면 application.properties 파일에 엔드포인트의 활성화를 구성하려면 해당 management.endpoint.<id>.enabled 속성을 사용하면 된다.

 

비활성화된 엔드포인트는 애플리케이션 컨텍스트에서 완전히 제거된다.

 

 속성을 추가하면 된다.

• 엔드포인트의 shutdown 기능 활성화, caches 기능 비활성화

# 엔드포인트 활성화
# 스프링부트 문서 2. Endpoints, 2.1. Enabling Endpoints 에서 확인
management.endpoint.shutdown.enabled=true
management.endpoint.caches.enabled=false

 

엔드포인트 노출

엔드포인트의 노출 여부만 설정하는 것도 가능하다.

노출 여부는 JMX를 통한 노출과 HTTP를 통한 노출이 있어 아래와 같이 설정이 구분된다.

 

• web과 jmx환경에서 엔드포인트를 전체적으로 노출하고, 
  스레드 덤프와 힙덤프 기능은 제외하는 설정

# 엔드포인트 노출 설정
# 스프링 부트 문서 2.2. Exposing Endpoints에서 확인

## 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

엔드포인트는 애플리케이션에 관한 민감한 정보를 포함하고 있어 노출 설정을 신중하게 해야한다.

특히 공개적으로 노출되는 애플리케이션이라면 더욱 신중히 고려해서 사용해야한다.

 

엔드포인트 노출 설정 기본값

ID	JMX	WEB
auditevents	O	X
beans	O	X
caches	O	X
conditions	O	X
configprops	O	X
env	O	X
flyway	O	X
health	O	O
heapdump	해당 없음	X
httptrace	O	X
info	O	X
integrationgraph	O	X
Jolokia	해당 없음	X
logfile	해당 없음	X
loggers	O	X
liquibase	O	X
metrics	O	X
mappings	O	X
Prometheus	해당 없음
quartz	O	X
scheduledtasks	O	X
sessions	O	X
shutdown	O	X
startup	O	X
threaddunp	O	X

액추에이터 기능 살펴보기

액추에이터 활성화하고 노출 지점도 설정하고 나면 애플리케이션에서 해당 기능을 사용할 수 있다.

 

기능 추가 없이 액추에이터 설정만으로 볼 수 있는 기능 위주로 살펴보자.

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

/info 엔드포인트로 가동 중인 애플리케이션의 정보를 볼 수 있다.

 

간단하게 application.properties 파일에 info. 로 시작하는 속성 값들을 이용해 애플리케이션 정보 속성을 정의할 수 있다.

# 액추에이터 info 정보 설정
info.organization.name=wikibooks
info.contact.email=thinkground.flature@gmail.com
info.contact.phoneNunber=010-1234-5678

http://localhost:8080/actuator/info 결과

{
	“organization”: 
	{
    	"name":"wikibooks"
    },
    “contact”:
	{
    	“email":"thinkground. flature@gmail.com”,
		"phoneNumber" : "010-1234-5678" 
	}
}

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

/health엔드포인트를 활용하면 애플리 케이션의 상태를 확인할 수 있다.

 

이 결과는 주로 네트워크 계층 L4(Loadbalancing) 레벨에서 애플리케이션의 상태를 확인하기 위해 사용된다.

http://localhost:8080/actuator/health 결과(별도 설정 없이 결과 볼 수 있다.)

{"status":"UP"}

status 속성에서 확인할 수 있는 상태 지표
- UP
- DOWN
- UNKNOWN
- OUT_OF_SERVICE

 

상세 상태를 확인하고 싶다면 아래와 같이 설정하자.

# 액추에이터 health 상세 내역 활성화 
# 스프링 부트 문서 2.9. Health Information
management.endpoint.health.show-details=always

always로 설정을 변경하고 애플리케이션을 재가동한 후 애플리케이션 상태를 확인하면 아래와 같은 결과값을 얻을 수 있다.

{
	"status": "UP",
	"components": {
	"diskSpace":{
	"status": "UP",
	"details":
	{
		"total": 536818479104,
		"free": 419451326464,
		"threshold": 10485760,
		"exists": true
	}
},
"ping":
	{
		"status": "UP"
    }
}

DB에 연동되어 있으면 인프라 관련 상태까지 확인할 수 있다.

 

status상태가 UP이어야 애플리케이션 상태도 UP으로 표시된다.

 

show-details 속성에서 설정할 수 있는 값들

값	설명
never	Details are never shown. 세부 정보는 표시되지 않습니다.
when-authorized	Details are shown only to authorized users. Authorized roles can be configured by using management.endpoint.health.roles. 세부 정보는 권한이 부여된 사용자에게만 표시됩니다.  권한이 부여된 역할은 management.endpoint.health.roles를 사용하여 구성할 수 있습니다.
always	Details are shown to all users. 세부 정보는 모든 사용자에게 표시됩니다.

빈 정보 확인(/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' 엔드포인트를 사용한다.

출력 내용은 크게 positiveMatchers와 negativeMatcher속성으로 구분된다.

자동설정의 @Conditional에 따라 평가된 내용을 표시한다.

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.web.exposure' property""..."
        		},
        		"negativeMatches":{
                    "RabbitHealthContributorAutoConfiguration”:
                    {
                    "notMatched":[
                    {
                        "condition": "OnClassCondition”,
                        "message": "@ConditionalOnClass did not find required class 'org.springframework.amop.rabbit.core.RabbitTemplate'""---"
                    }
       				unconditiomalClasses™:[
						"org.springframework.boot.autoconfigure.context.ConfigurationPropertiesAutoConfiguration 
                        "org.springframework.boot.actuate.autoconfigure.availability.AvailabilityHealthContributorAutoConfiguration”,
						"org. springframework.boot.actuate.autoconfigure.info.InfoContributorAutoConfiguration", |
                        "..."
 	                   ]
                   }
                }
            }
        }
    }
}

 

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

/env 엔드 포인트는 스프링의 환경변수 정보를 확인하는데 사용된다.

 

기본적으로 application.properties 파일의 변수들이 표시된다.

OS, JVM 환경도 함께 표시된다.

 

민감한 정보를 가리기 위해서는 management.endpoint,env.keys-to-sanitize 속성을 사용하면 된다.

해당 속성에 넣을 수 있는 값은 단순 문자열이나 정규식을 활용한다.

http://localhost:8080/actuator/env

{
  "propertySources": [
    {
      "name": "systemProperties",
      "properties": {
        "java.runtime.name": {
          "value": "OpenJDK Runtime Environment"
        },
        "user.dir": {
          "value": "/path/to/project"
        },
        // 추가적인 시스템 속성들...
      }
    },
    {
      "name": "systemEnvironment",
      "properties": {
        "PATH": {
          "value": "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/games:/usr/local/games:/snap/bin"
        },
        "USER": {
          "value": "username"
        },
        // 추가적인 환경 변수들...
      }
    }
  ]
}

로깅 레벨 확인(/loggers)

애플리케이션의 로깅 레벨 수준이 어떻게 설정되어 있는지 확인하려면 /loggers 엔드포인트를 사용할 수 있다.

 

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

http://localhost:8080/actuator/loggers

{
  "levels": [
    "OFF",
    "ERROR",
    "WARN",
    "INFO",
    "DEBUG",
    "TRACE"
  ],
  "loggers": {
    "com.example": {
      "configuredLevel": "DEBUG",
      "effectiveLevel": "DEBUG"
    },
    "org.springframework": {
      "configuredLevel": null,
      "effectiveLevel": "INFO"
    },
    // 다른 로거들...
  }
}

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

개발자 요구에 맞춘 커스텀 기능 성정도 가능하다.

커스텀 기능 개발 방식
1. 기존 기능에 내용 추가
2. 새로운 엔드 포인트를 개발

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

액추에이터를 커스터마이징하는 가장 간단한 방법은 application.properties파일에 내용을 추가하는 것이다.

이 방법은 많은 내용을 담을 때는 관리 측면에서 좋지 않다.

 

때문에 별도의 구현체 클래스를 작성해 내용을 추가하는 방법을 커스텀 기능을 설정할 때 많이 쓴다.

 

액추에이터에서는 InfoContributor 인터페이스를 제공한다.

이 인터페이스를 구현하는 클래스를 생성하면 된다.

 

InfoContributor 인터페이스 구현 클래스 생성

@Component
public class CustomInfoContributor implements InfoContributor { 
	@Override 
	public void contribute(Builder builder) { 
        Map<String, Object) content = new HashMapO(); 
        content.put("code-info", "InfoContributor 구현체에서 정의한 정보입니다."); 
        builder .withDetail( "custom-info-contributor”, content); 
    }
}

• contribute 메서드
  • Builder 파라미터: 액추에이터 패키지의 Info 클래스 안에 정의되어 있는 클래스
    • Info 엔드포인트에서 보여줄 내용을 담는 역할을 수행
      • 콘텐츠를 buildr에 포함하면 엔드포인트 출력 결과에서 확인할 수 있다.

InfoContributor 구현체를 활용한 /Info 엔드포인트 출력 결과

{
	“organization”: { 
        “name” : "wikibooks"
    },
    “contact”: {
        “email”: "thinkground.flature@gmail.com",
        “phoneNumber " : "010-1234-5678"
    },
    “custom-info-contributor":{
        “code-info": "InfoContributor 구현체에서 정의한 정보입니다."
    }
}

application.properties에서 정의한 속성값을 비롯해 구현체 클래스의 내용이 추가된 것을 볼 수 있다.

커스텀 엔드포인트 생성

@Endpoint 어노테이션으로 빈에 추가된 객체들은 @ReadOperation, @WriteOperation, @DeleteOperation 어노테이션을 사용해 JMX나 HTTP를 통해 커스텀 엔드포인트를 노출시킬 수 있다.

 

• @Endpoint 어노테이션
  • 액추에이터에 엔드포인트로 자동 등록
  • id 속성: 경로를 정의할 수 있다.
  • enableByDefault 속성: 현재 생성하는 엔드포인트의 기본 활성화 여부를 설정할 수 있다.
    • 기본값: true (별도 지정이 없으면 활성화)

HTTP method
HTTP 메서드는 다음 표와 같이 연산 유형에 따라 결정된다.

Operation	HTTP method
@Read Opreation	GET
@WriteOperation	POST
@DeleteOperation	DELETE

만약 JMX에서만 사용하거나 HTTP에서만 사용하는 것으로 제한하고 싶다면 @JmxEndpoint, @WebEndpoint 어노테이션을 사용할 수 있다.

 

관련 내용은 스프링 부트 문서 2.8.2. Custom Web Endpoints에서 확인이 가능하다.

import java.util.HashMap;
import java.util.Map;
import org.springframework.boot.actuate.endpoint.annotation.DeleteOperation;
import org.springframework.boot.actuate.endpoint.annotation.Endpoint;
import org.springframework.boot.actuate.endpoint.annotation.ReadOperation;
import org.springframework.boot.actuate.endpoint.annotation.WriteOperation;
import org.springframework.stereotype.Component;

@Component
@Endpoint(id = "note", enableByDefault = true) // 커스텀 엔드포인트 경로와 기본 황성화 여부 설정
public class NoteEndpoint {

    private Map<String, Object> noteContent = new HashMap<>();

    @ReadOperation // HTTP GET요청에 반응하는 메서드
    public Map<String, Object> getNote(){ 
        return noteContent; // Map타입 객체 전달
    }

    @WriteOperation // HTTP POST요청에 반응하는 메서드
    public Map<String, Object> writeNote(String key, Object value){
        noteContent.put(key,value);
        return noteContent;
    }

    @DeleteOperation // HTTP DELETE요청에 반응하는 메서드
    public Map<String, Object> deleteNote(String key){
        noteContent.remove(key);
        return noteContent;
    }

}