11. 액추에이터 활용하기

• 애플리케이션을 개발하는 단계를 지나 운영 단계에 접어들면 애플리케이션이 정상적으로 동작하는지 모니터링하는 환경을 구착하는 것이 매우 중요하다.

11.2 엔드포인트

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

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

// application.yml
management:
	endpoints:
    	web:
        	base-path: /custom-path

• 엔드포인트 활성화 여부와 노출 여부를 설정할 수 있다.
  • 활성화는 기능 자체를 활성화할 것인지를 결정하는 것으로, 비활성화된 엔드포인트는 애플리케이션 컨텍스트에서 완전히 제외 됩니다.
  • 엔드포인트를 활성화하려면 application 환경 파일에 속성을 추가하면 된다.

// 엔드포인트 활성화
// application.properties
management.endpoint.shutdown.enable=true
management.endpoint.caches.enable=true

// application.yml
management:
	endpoint:
    	shutdown:
        	enable: true
management:
	endpoint:
    	caches:
        	enable: false

• shutdown 기능은 활성화 하고 caches 기능은 비활성화 하겠다는 설정

• 엔드포인트 노출 여부만 설정하는 것도 가능
  • 노출 여부는 JMX를 통한 노출과 HTTP를 통한 노출이 있다.

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

// application.yml
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

// application.yml
management:
	endpoints:
    	jmx:
        	exposure:
            	include: *
management:
	endpoints:
    	jmx:
        	exposure:
            	exlude: threaddump, heapdump

• web과 jmx 환경에서 엔드포인트를 전체적으로 노출하며, 쓰레드 덤프(threaddump)와 힙 덤프(heapdump) 기능은 제외하겠다.

엔드포인트는 애플리키에션에 관한 민간한 정보를 포함하고 있으므로 노출 설정을 신중하게 고려해야 한다.

Web 경우에는 health 기능만 노출한다.

 

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

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

• /info 엔드포인트를 활용하면 가동 중인 애플리케이션의 정보를 볼 수 있다.
  • application 환경 파일에 info 로 시작하는 속성 값들을 정의하여 정보의 범위를 설정할 수 있다.

// 액추에이터 info 정보 설정
info.organization.name=wikibooks
info.contack.email=aaa@gmail.com
info.contact.phoneNumber=010-1234-5678

// application.yml
info:
	organization:
    	name: wikibooks
info:
	contact:
    	email: aaa@gmail.com
info:
	contact:
    	phoneNumber: 010-1234-5678

• http://localhost:8080/actuator/info 로 호출하면 아래와 같이 정보를 확인 할 수 있다.

{
    "organization":
    {
    	"name":"wikibooks"
    }
    "contact":
    {
    	"email":"aaa@gmail.com"
        "phoneNumber":"010-1234-5678
    }
}

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

• /health 엔드포인트를 활용하면 애플리케이션 상태를 확인 할 수 있다.
  • 별도의 설정 없이 http://localhost:8080/actuator/health 로 접속하면 아래와 같은 json응답을 제공한다.

{"status": "UP"}

• status 속성에서 확인할 수 있는 상태 지표는 아래와 같다.
  • UP, DOWN, UNKNOWN, OUT_OF_SERVICE
  • 이 결과는 주로 네트워크 계충 중 L4(Loadbalancing) 레벨에서 애플리케이션의 상태를 확인하기 위해 사용
  • 상세 상태를 확인하고 싶다면 application 환경 설정을 추가하면 된다.

// 액추에이터 health 상세 내역 활성화
// application.properties
management.endpoint.health.show-details=always

// application.yml
management:
    endpoint:
        health:
            show-details: always

• always로 설정 후 애플리케이션 상태를 확인하면 아래와 같다.

{
    "status": "UP"
    "components": {...}
    "ping": {...}
    ...
}

 

11.3.3 빈 정보 확인(/beans)

• /bean 엔드포인트를 사용하면 스프링 컨테이너에 등록된 스프링 빈의 전체 목록을 표시 할 수 있다.
  • http://localhost:8080/actuator/beans

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

• 스프링 부트의 자동설정(AutoConfiguration) 조건 내역을 확인하려면  /conditions 엔드포인트를 사용한다.
  • http://localhost:8080/actuator/conditions

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

• /env 엔드포인트는 스프링의 환경변수 정보를 확인하는 데 사용한다. 기본적으로 application.properties 파일의 변수들이 표시되며, OS.JVM의 환경변수도 함께 표시된다.
  • http://localhost:8080/actuator/env

11.3.6 로깅 레벨 확인(/loggers)

• 애플리케이션 로깅 레벨 수준이 어떻게 설정되어 있는지 확인하려면 /loggers 엔드포인트를 사용
  • http://localhost:8080/actuator/loggers

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

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

• application.properties 파일 내에 내용을 추가하는 방법이 있는데 관리측면에서 좋지 않다.
• 별도의 구현체 클래스를 작성해서 내용을 추가하는 방법을 많이 사용한다.

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

• InfoContributor 인터페이스의 구현체로 설정하면  contribute 메서드를 오버라이딩 할 수 있다.
• 파리미터로 받는 Builder 객체는 액추에이터 패키지의 info 클래스안에 정의돼 있는 클래스로서 Info엔드포인에서 보여줄 내용을 담는 역할을 한다.

11.4.2 커스텀 엔드포인트 생성

• @Endpoint 어노테이션으로 bean에 추가된 객체들은 @ReadOperation, @WriteOperation, @DeleteOperation 어노테이션을 사용해 JMX나 HTTP를 통해 커스텀 엔드포인트를 노출시킬 수 있다.
  • 만약 JMX에서만 또는 HTTP 에서만 사용한느 것으로 제한하고 싶다면 @JmxEndpoint, @WebEndpoint 어노테이션을 사용하면 된다.

@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> deleteNode(String key) {
    	noteContent.remove(key);
        return noteContent;
    }
}

• @Endpoint 어노테이션을 선언하면 액추에이터에 엔드포인트로 자동으로 등록되며 id 속성값으로 경로를 정의할 수 있다.
• enableByDefault 라는 속성으로 현재 생성화는 엔드포인트의 기본 활성화 여부도 설정 가능
  • enableByDefault의 기본값은 true로서 값을 별도로 지정하지 않으면 활성화된다.
• 엔드포인트를 설정하는 클래스에는 @ReadOpeation(GET), @WriteOperation(POST), @DeleteOperation(DELETE) 을 이용해 각 동작 메서드를 생성할 수 있다.
• http://localhost:8080/actuator/note 로 요청하여 확인 가능하다.