액츄에이터

프로덕션 준비 기능이란?

서비스 운영에 있어 장애는 얼마든지 발생할 수 있지만 모니터링(경계)을 잘 대응하는 것이 서비스를 운영하는 개발자에게 중요한 부분이다. 서비스가 장애를 일으키는 요소는 무수히 많다. 예상치 못하게 갑작스런 장애야 그렇다 치지만 서비스 운영 상태를 체크하면서 충분히 예상할 수 있는 문제들이었음에도 모니터링하지 않아 끝내 장애를 일으키고 말았다면 개발자로서 부끄러운 일일 것이다.

 

개발자는 애플리케이션을 개발할 때 기능 요구사항만 개발하는 것은 아니다. 서비스를 실제 운영단계에 올리게 되면 또 다른 중요한 업무인 서비스에 문제가 없는지 모니터링하고 지표들을 심어서 감시하는 활동이다.

 

운영 환경에서 서비스할 때 필요한 이런 기능들을 프로덕션 준비 기능이라고 한다.

 

• 지표(metric) : CPU 사용량
• 추적(trace) : 애플리케이션 코드가 어디서 문제가 되는지 찾는 과정
• 감사(auditing) : 서비스를 이용하는 유저들이 어떤 작업을 했는지 기록을 볼 수 있게 처리하는 것
• 모니터링 : 전체적인 운영서비스의 상태를 확인하는 것

좀 더 구체적으로 애플리케이션이 살아있는지, 로그 정보는 정상 설정 되었는지, 커넥션 풀은 얼마나 사용되고 있는지 등을 확인할 수 있어야 한다.

 

스프링 부트가 제공하는 액추에이터는 이런 프로덕션 준비 기능을 매우 편리하게 사용할 수 있는 다양한 편의 기능들을 제공한다.

더 나아가서 마이크로미터, 프로메테우스, 그라파나 같은 최신 유행하는 모니터링 시스템과 매우 쉽게 연동할 수 있는 기능도 제공한다.

 

액추에이터는 시스템을 움직이거나 제어하는데 쓰이는 기계 장치라는 뜻이다.

 

 

액츄에이터 시작

액츄에이터가 제공하는 프로덕션 준비 기능을 사용하려면 스프링 부트 액츄에이터 라이브러리를 추가해야 한다.

 

build.gradle -  추가

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

 

액츄에이터 동작 확인

{cotextPath}/actuator

• 액츄에이터는 /actuator 경로를 통해서 기능을 제공한다.
• 화면에 보이는 health 결과를 제공하는 다음 URL도 실행해 보자
• {contextPath}/actuator/health

• 이 기능은 현재 서버가 잘 동작하고 있는지 애플리케이션의 헬스 상태를 나타낸다.

지금 눈에 보이는 기능은 헬스 상태를 확인할 수 있는 기능 뿐이다. 액츄에이터는 헬스 상태 뿐만 아니라 수많은 기능을 제공하는데, 이런 기능이 웹환경에서 보이도록 노출해야 한다.

 

액츄에이터 기능을 웹에 노출 설정

application.yml에 액츄에이터 기능을 모두 노출시키는 설정 추가

 

액츄에이터가 제공하는 기능 하나하나를 엔드포인트라 한다.

application.yml 파일에 엔드포인트를 모두 노출로 설정하면 액츄에이터가 제공하는 수 많은 기능을 확인할 수 있다.

health는 헬스 정보를, beans는 스프링 컨테이너에 등록된 빈을 보여준다.

 

각각의 엔드포인트는 /actuator/{엔드포인트명} 형식으로 접근할 수 있다.

• {contextPath}/actuator/health : 애플리케이션 헬스 정보를 보여준다.
• {contextPath}/actuator/beans : 스프링 컨테이너에 등록된 빈을 보여준다.

http://localhost:8080/actuator/beans 스프링에 등록된 빈 확인

http://localhost:8080/actuator/threaddump 애플리케이션에서 동작중인 스레드 확인

http://localhost:8080/actuator/mappings 스프링 컨테이너에 매핑된 정보 확인

 

 

 

엔드포인트 설정

엔드포인트 사용시 2가지 과정이 필요하다

1. 엔드포인트 활성화
2. 엔드포인트 노출

엔드포인트를 활성화 한다는 것은 해당 기능 자체를 사용할지 말지 on/off 선택하는 것이고

엔드포인트를 노출하는 것은 활성화된 엔드포인트를 HTTP에 노출할지 아니면 JMX에 노출할지 선택하는 것이다.

엔드포인트를 활성화하고 추가로 HTTP를 통해서 노출할지 아니면 JMX를 통해서 노출할지 두 위치에 모두 노출할지 노출위치를 지정해야 한다.

물론 활성화 되어있지 않으면 노출도 되지 않는다.

엔드포인트는 대부분 기본으로 활성화 되어있어서(shutdown 제외) 노출이 되어있지 않을 뿐

따라서 어떤 엔드포인트를 노출할지 선택하면된다.

 

*JMX(Java Management eXtentions) : 자바 5 버전부터 제공하는 실행중인 애플리테이션의 상태를 모니터링 하고, 설정을 변경할 수 있게 해주는 API. JMX를 통해 리소스 관리하려면 MBean을 생성하여 자원을 MBean으로 감싸 외부에서 API 설정, 데이터수집, 원격제어 등을 할 수 있게 만들어 준다. JConsole.JVisualVM등 JMX를 이용해 구현된 모니터링 도구가 있다.

*JMX MBean(Managed Bean) : JMX의 MBean은 JMX Agent를 통해 관리되는 응용프로그램 또는 시스템 리소스이다.

 

 

 

application.yml - 모든 엔드포인트를 웹에 노출

"*" 옵션은 모든 엔드포인트를 웹에 노출한다. (shutdown 엔드포인트 제외. 기본 활성화 되지 않아 노출도 되지 않는다.)

엔드포인트 활성화 + 엔드포인트 노출 둘다 적용되어야 사용할 수 있다.

 

엔드포인트활성화

application.yml - shutdown 엔드포인트 활성화

특정 엔드포인트 활성화 하려면

management.endpoint.{엔드포인트명}.enable=true

shutdown 엔드포인트가 활성화 되고 전체 노출로 설정되어 보인다.

해당 shutdown 기능은 서버를 내리는 기능을 가지고 있어서 GET방식으로는 사용할 수 없고 POST 방식으로 요청보내야 한다.

GET 방식은 지원 안해~

 

POST 방식으로 요청보내면

서버가 stop 된다.

이 기능은 주의해서 사용해야하는 기능이므로 기본으로 비활성화 되어 있다.

 

 

엔드포인트 노출

jmx에 "health,info"를 노출한다.

web에 모든 엔드포인트를 노출하지만 env, bean는 제외

 

 

 

 

다양한 엔드포인트

각각 엔드포인트를 통해서 개발자는 애플리케이션 내부의 수 많은 기능을 관리하고 모니터링 할 수 있다.

스프링 부트가 기본으로 제공하는 다양한 엔드포인트를 알아본다.

 

• beans : 스프링 컨테이너에 등록된 스프링 빈을 보여준다.
• conditions : condition을 통해서 빈을 등록할 때 평가 조건과 일치하거나 일치하지 않은 이유를 표시한다.
• configprops : @ConfigurationProperties를 보여준다.
• env : Environment 정보를 보여준다.
• health : 애플리케이션 헬스 정보를 보여준다.
• httpexchanges : HTTP 호출 응답 정보를 보여준다. HttpExchangeReporitory를 구현한 빈을 별도로 등록해야 한다.
• info : 애플리케이션 정보를 보여준다.
• loggers : 애플리케이션 로거 설정을 보여주고 변경도 할 수 있다.
• metrics : 애플리케이션의 메트릭 정보를 보여준다.
• mappings : @RequestMapping 정보를 보여준다.
• threaddump : 쓰레드 덤프를 실행하서 보여준다.
• shutdown :  애플리케이션을 종료한다. 이 기능은 기본으로 비활성화 되어 있다.

엔드포인트 공식 메뉴얼

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

 

 

헬스 정보

health 엔드포인트는 스프링 애플리케이션에 통합할 수 있는 많은 외부 시스템의 건강 상태 정보를 제공한다.

단순히 애플리케이션이 요청에 응답할 수 있는지 판단하는 것을 넘어서 애플리케이션이 사용하는 데이터베이스가 응답하는지, 디스크 사용량에는 문제가 없는지 같은 다양한 정보들을 포함해서 만들어진다.

http://localhost:8080/actuator/health

기본 동작

 

헬스 정보를 더 자세히 보는 옵션

management.endpoint.health.show-details=always

DB 상태정보 와 어떤 데이터베이스 종류를 쓰는지, validationQuery는 JDBC에서 제공되는 기능으로 애플리케이션과 DB가 연결 되었는지 확인하는 기능

디스크 상태정보로 총 디스크 용량과 사용가능한 용량, 경로 등이 자세히 표시된다.

 

어플리케이션 상태 정의

• UP : 외부 시스템이 작동중이고 접근 가능
• DOWN : 외부 시스템이 작동하지 않거나 접근 불가능
• OUT_OF_SERVICE : 외부 시스템 상태가 분명하지 않음
• UNKNOWN : 외부 시스템 접근 가능하지만 현재 사용 불가

모든 상세 옵션 상태가 UP 이어야 health 상태가 UP으로 표시되고

하나 이상의 DWON 상태가 있다면 health 상태도 DOWN으로 표시된다.

하나 이상의 OUT_OF_SERVICE 상태가 있다면 health 상태도 OUT_OF_SERVICE로 표시된다.

UNKNOWN의 건강 상태는 무시된다.

 

헬스 정보 간략한 정보 옵션

management.endpoint.health.show-components=always

 

헬스 공식 메뉴얼

https://docs.spring.io/spring-boot/docs/current/reference/html/actuator.html#actuator.endpoints.health.auto-configured-health-indicators

헬스 기능 직접 구현

https://docs.spring.io/spring-boot/docs/current/reference/html/actuator.html#actuator.endpoints.health.writing-custom-health-indicators

 

 

 

 

애플리케이션 정보

info 엔드포인트는 애플리케이션의 기본 정보를 노출한다.

 

• java : 자바 런타임 정보
• os : OS 정보
• env : Environment 에서 info. 으로 시작하는 정보
• build : 빌드 정보, META-INF/build-info.properties 파일이 필요하다.
• git : git 정보, git.propertis 파일이 필요하다.

java, os, env는 기본으로 비활성화 되어 있다. build와 git은 properties 파일이 필요하다.

http://localhost:8080/actuator/info

설정전에는 정보들이 표시되지 않는다.

 

 

java와 os, env 옵션 설정

management.info.java.enabled = true
management.info.os.enabled = true
management.onfo.os.enabled = true

자바 버전, JVM 정보, os 종류를 자세히 볼 수 있다.

env 정보는 properties에 info로 시작되는 정보를 출력할 수 있는데 actuator로 확인해야하는 정보를 남길 때 properties에 설정하면 확인할 수 있다.

 

build 옵션 추가

빌드 정보를 노출하려면 빌드 시점에 META-INF/build-info.properties 파일을 만들어야 한다.

gradle 사용시 편리하게 파일을 만들 수 있다.

 

build.gradle - 빌드 정보 추가

빌드 정보 추가후 부트를 빌드하면 build 폴더에 resources/main/META-INF/build-info.properties 파일이 만들어진다.

애플리케이션 기본 정보와 빌드된 시간을 확인할 수 있다.

 

git 옵션 추가

build와 유사하게 빌드시점에 사용한 git 정보를 노출하려면 git.properties 파일이 필요하다.

gradle 사용시 편리하게 파일을 만들 수 있다.

 

build.gradle - git 정보 추가

*만약 프로젝트가 깃으로 관리되어 있지 않다면 플러그인이 깃을 찾지 못하여 에러가 난다.

플러그인 추가후 부트를 빌드하면 build 폴더에 resources/main/git.properties 파일이 만들어진다.

브랜치 정보와 커밋id, 커밋 시간을 확인할 수 있다.

더 많은 정보를 확인하려면 다음 설정을 application.properties 파일에 추가해주면 된다.

management.info.git.mode = full

 

info 사용자 정의 기능 추가 - 공식 메뉴얼

https://docs.spring.io/spring-boot/docs/current/reference/html/actuator.html#actuator.endpoints.info.writing-custom-info-contributors

 

 

로거

loggers 엔드포인트를 사용하면 로깅과 관련된 정보를 확인하고, 또 실시간으로 변경할 수 있다.

 

LogController 생성

로그 레벨을 남기는 단순한 컨트롤러

http://localhost:8080/log

컨트롤러 접근 시 INFO, WARN, ERROR 3개의 로그만 출력된다.

현재 로깅 레벨이 INFO로 설정되어 있기 때문에 INFO보다 높은 로깅레벨이 출력된다.

 

만약 로깅레벨을 DEBUG로 변경한다면

hello.controller 패키지와 그 하위는 DEBUG 레벨을 출력하도록 했다.

DEBUG 레벨부터 출력된다.

 

loggers 엔드포인트 호출

http://localhost:8080/actuator/loggers

• 로그를 별도로 설정하지 않으면 스프링 부트는 기본적으로 로그레벨을 INFO로 설정된다. 실행 결과를 보면 ROOT의 configuredLevel이 INFO인 것을 확인할 수 있다. 따라서 그 하위도 모두 INFO레벨이 적용된다.
• 개별 설정한 hello.controller는 DEBUG로 설정하여 configuredLevel이 DEBUG로 설정된 것을 확인할 수 있다. 그 하위인 LogController또한 DEBUG 레벨이 적용된다.

 

로거 자세히 조회하기

{contextPath}/actuator/loggers/{로거이름}

 

실시간 로그 레벨 변경

개발 서버는 보통 DEBUG 로그로 사용하지만, 운영 서버는 보통 요청이 아주 많다. 따라서 로그도 너무 많이 남기 때문에 DEBUG 로그까지 모두 출력하게 되면 성능이나 디스크에 영향을 주게 된다. 그래서 운영서버는 중요하다고 판된되는 INFO 로그 레벨을 사용한다.

그런데 서비스 운영중 문제가 있어서 급하게 DEBUG나 TRACE 로그를 남겨서 확인해야 한다면 일반적으로 로깅레벨 설정을 변경하고 서버를 다시 시작해야 한다.

 

loggers 엔드포인트를 사용하면 애플리케이션 재시작 없이 실시간 로그 레벨 변경이 가능하다.

 

POST 요청으로 로깅레벨 변경을 보낸다.

요청방식을 POST로 변경하고, 변경할 로깅레벨 URL을 적은 후 요청 Body에 JSON 형식으로 configuredLevel을 설정하고 싶은 레벨로 설정 후 요청을 보내면 204 성공 코드가 떨어진다. 응답받는 별도의 내용은 없다.

http://localhost:8080/log

TRACE 레벨까지 로그 출력이 되고

로그 레벨도 변경되어 있다.

서버를 재시작 하면 application.yml에 적혀있는 로깅 레벨로 다시 설정된다.

 

 

HTTP 요청 응답 기록

HTTP 요청과 응답의 과거 기록을 확인하고 싶다면 httpexchanges 엔드포인트를 사용하면된다.

HttpExchangeRepository 인터페이스의 구현체를 빈으로 등록하면 httpexchanges 엔드포인트를 사용할 수 있다.

스프링부트는 기본으로 InMemoryHttpExchangeRepository 구현체를 제공한다.

 

InMemoryHttpExchangeRepository 추가

• httpExchange : HTTP 요청 및 응답 및 교환을 캡슐화한 객체. HTTP 헤더와 같은 컨텍스트 정보를 분석하는데 사용한다.
• httpExchangeReposiroty : httpExchange 인스턴스용 저장소 인터페이스. httpExchange 인스턴스를 추가하거나 저장소에 포함된 모든 httpExchange를 찾는기능이 서술되어 있다. 이 인터페이스를 구현한 것이 InMemoryHttpExchangeRepository 
• InMemoryHttpExchangeRepository : HTTP요청이 들어올 때 메모리에 히스토리를 저장할 범위를 설정하는 기능이 추가된 구현체이다. 이 구현체는 최대 100개의 HTTP 요청을 제공한다. 최대 요청이 넘어가면 과거 설정을 삭제한다. setCapacity()로 최대 요청수를 변경할 수 있다.

 

http://localhost:8080/actuator

액츄에이터에 기능이 추가 되었다.

그동안 요청했던 HTTP 요청과 응답 정보가 출력된다.

참고로 이 기능은 매우 단순하고 기능에 제한이 많기 때문에 개발 단계에서만 사용하고, 실제 운영 서비스에서는 모니터링 툴이나 핀포인트, Zipkin같은 다른 기술을 사용하는 것이 좋다.

 

 

 

 

액츄에이터와 보안

보안주의

액츄에이터가 제공하는 기능들은 우리 애플리케이션의 내부 정보를 너무 많이 노출한다. 외부 인터넷 망이 공개된 곳에 액츄에이터의 엔드포인트를 공개하는 것은 보안상 좋은 방안이 아니다.

액츄에이터의 엔드 포인트들은 외부 인터넷에서 접근이 불가능하게 막고, 내부에서만 접근 가능하게 내부망을 사용하는 것이 안전하다.

 

액츄에이터를 다른 포트에서 실행

외부 인터넷망에서는 8080 포트로만 접근할 수 있고 다른 포트는 내부망에서만 접근할 수 있다면 액츄에이터에 포트를 설정하면 된다.

 

액츄에이터 포트 설정

management.server.port=9292

엔드포인트 접근 가능 포트 9292로 설정

컨테이너 실행시 로그를 보면 8080포트와 9292포트가 2개 뜨는 것을 볼 수 있다.

8080포트로 접근이 안되고 9292포트만 접속이 가능한 것을 확인

 

액츄에이터 URL 경로에 인증 설정

포트를 분리하는 것이 어렵고 어쩔 수 없이 외부 인터넷망을 통해서 접근해야하면 /actuator 경로에 서블릿 필터, 스프링 인터셉터 또는 스프링 시큐리티를 통해서 인증된 사용자만 접근 가능하도록 추가 개발이 필요하다.

 

엔드포인트 경로 변경

엔드포인트의 기본 경로를 변경하려면 다음과 같이 설정하면 된다.

application.yml

management.endpoints.web.base-path = "/manage"

• /actuator/{엔드포인트} 대신 /manage/{엔드포인트}로 변경된다.

 

 

 

https://www.inflearn.com/course/%EC%8A%A4%ED%94%84%EB%A7%81%EB%B6%80%ED%8A%B8-%ED%95%B5%EC%8B%AC%EC%9B%90%EB%A6%AC-%ED%99%9C%EC%9A%A9/dashboard