[spring boot] 액츄에이터

현서황·2024년 10월 15일
Spring boot김영한

SPRING BOOT-핵심원리와활용

목록 보기
10/11

액츄에이터(Actuator)란 애플리케이션의 상태를 모니터링하고 관리하는 기능을 제공하는 모듈이다. 액츄에이터를 통해 애플리케이션의 운영환경에서 유용한 메트릭, 상태 정보, 성능 분석이나 문제 해결에 도움을 줄 수 있다.

주요 기능

  • 헬스체크
    애플리케이션의 상태를 확인할 수 있다. /actuator/health 엔드포인트를 통해 현재 애플리케이션이 정상인지, 데이터베이스나 다른 외부 서비스가 정상 동작 중인지 알 수 있다.
  • 매트릭
    메모리 사용량, CPU 사용률, 스레드 상태, HTTP 요청 수 등의 다양한 메트릭을 제공하여 애플리케이션의 성능을 모니터링할 수 있다. /actuator/metrics 엔드포인트에서 다양한 시스템 및 애플리케이션 메트릭을 확인할 수 있다.
  • 로그 레벨 관리
    실행 중인 애플리케이션의 로그 레벨을 동적으로 변경할 수 있는 기능을 제공한다. 이를 통해 디버깅이나 문제 상황에서 로그를 실시간으로 조정할 수 있다.
  • HTTP 트레이스
    최근에 발생한 HTTP 요청과 응답에 대한 정보(헤더, 응답 코드 등)를 확인할 수 있는 기능이다. 이를 통해 HTTP 요청 흐름을 추적하고 문제를 분석할 수 있다.

프로덕션 준비기능이란?

전투에서 실패한 지휘관은 용서할 수 있지만, 경계에서 실패하는 지휘관은 용서할 수 없다.라는 말이 있다. 이 말을 서비스를 운영하는 개발자에게 맞추어 보면 장애는 언제든지 발생할 수 있다. 하지만 모니터링(경계)는 잘 대응하는 것이 중요하다.

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

운영 환경에서 서비스할 때 필요한 이런 기능들을 프로덕션 준비 기능이라 한다. 쉽게 이야기해서 프로덕션을 운영에 배포할 때 준비해야하는 비 기능적 요소들을 뜻한다.

  • 지표(metric), 추적(trace), 감사(auditing)
  • 모니터링

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

스프링 부트가 제공하는 액추에이터는 이런 프로덕션 준비 기능을 매우 편리하게 사용할 수 있는 다양한 편의 기능들을 제공한다. 더 나아가서 마이크로미터, 프로메테우스, 그라파나 같은 최근 유행하는 모니터링 시스템과 매우 쉽게 연동할 수 있는 기능도 제공한다.
참고로 액추에이터는 시스템을 움직이거나 제어하는 데 쓰이는 기계 장치라는 뜻이다.
여러 설명보다 한번 만들어서 실행해보는 것이 더 빨리 이해가 될 것이다.

액츄에이터 시작

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



액츄에이터가 제공하는 수 많은 기능을 확인할 수 있다.
액츄에이터가 제공하는 기능 하나하나를 엔드포인트라 한다. health 는 헬스 정보를, beans 는 스프링 컨테이너에 등록된 빈을 보여준다.

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

엔드포인트 설정

엔드포인트를 사용하려면 다음 2가지 과정이 모두 필요하다.
1. 엔드포인트 활성화
2. 엔드포인트 노출

엔드포인트를 활성화 한다는 것은 해당 기능 자체를 사용할지 말지 on, off를 선택하는 것이다.
엔드포인트를 노출하는 것은 활성화된 엔드포인트를 HTTP에 노출할지 아니면 JMX에 노출할지 선택하는 것이다.
엔드포인트를 활성화하고 추가로 HTTP를 통해서 웹에 노출할지 아니면 JMX를 통해 노출할지 두 위치에 모두 노출할지 노출 위치를 지정해주어야 한다.
물론 활성화가 되어있지 않으면 노출도 되지 않는다.

그러나 엔드포인트는 대부분 기본으로 활성화되어있다. (shutdown 제외)
노출이 되어있지 않을 뿐이다.
따라서 어떤 엔드포인트를 노출할지를 선택하면 된다. 참고로 HTTP와 JMX를 선택할 수 있는데, 보통 JMX는 잘 사용하지 않으므로 HTTP에 어떤 엔드포인트를 노출할지 선택하면 된다.

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

management:
 	endpoints:
 	web:
 		exposure:
 			include: "*"

"*" 옵션은 모든 엔드포인트를 웹에 노출하는 것이다. 참고로 shutdown 엔드포인트는 기본으로 활성화 되지 않기 때문에 노출도 되지 않는다.
엔드포인트 활성화 + 엔드포인트 노출이 둘다 적용되어야 사용할 수 있다.

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

management:
 	endpoint:
 		shutdown:
 			enabled: true
 	endpoints:
 		web:
 			exposure:
 				include: "*"

특정 엔드포인트를 활성화 하려면 management.endpoint.{엔드포인트명}.enabled=true 를 적용하면 된다.
이제 Postman 같은 것을 사용해서 HTTP POST로 http://localhost:8080/actuator/shutdown 를 호출하면 다음 메시지와 함께 실제 서버가 종료되는 것을 확인할 수 있다. 

{"message": "Shutting down, bye..."}

참고로 HTTP GET으로 호출하면 동작하지 않는다.
물론 이 기능은 주의해서 사용해야 한다. 그래서 기본으로 비활성화 되어 있다.

다양한 엔드포인트

각각의 엔드포인트를 통해서 개발자는 애플리케이션 내부의 수 많은 기능을 관리하고 모니터링 할 수 있다.
스프링 부트가 기본으로 제공하는 다양한 엔드포인트에 대해 알아보자.
다음은 자주 사용하는 기능 위주로 정리한 것이다.

엔드포인트 목록

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

health, info, loggers, httpexchanges. metrics는 뒤에서 더 자세히 알아보겠다.

헬스 정보

헬스 정보를 사용하면 애플리케이션에 문제가 발생했을 때 문제를 빠르게 인지할 수 있다.

기본 동작

{"status": "UP"}

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

헬스 정보를 더 자세히 보려면 옵션을 지정하면 된다.
management.endpoint.health.show-details=always

management:
 	endpoint:
 	health:
 		show-details: always

show-details 옵션

{
 	"status": "UP",
 	"components": {
 		"db": {
 			"status": "UP",
 			"details": {
 				"database": "H2",
 				"validationQuery": "isValid()"
 		}
 	},
 	"diskSpace": {
 		"status": "UP",
 		"details": {
 			"total": 994662584320,
 			"free": 303418753024,
 			"threshold": 10485760,
 			"path": ".../spring-boot/actuator/actuator/.",
 			"exists": true
 		}
 	},
 	"ping": {
 		"status": "UP"
 	}
 	}
}

각각의 항목이 아주 자세히 노출되는 것을 확인할 수 있다.
이렇게 자세히 노출되는 것이 부담스럽다면 show-details 옵션을 제거하고 대신에 다음 옵션을 사용하면 된다.

헬스 이상 상태

헬스 컴포넌트 중에 하나라도 문제가 있으면 전체 상태는 DOWN이 된다.

{
 "status": "DOWN",
 "components": {
 "db": {
 "status": "DOWN"
 },
 "diskSpace": {
 "status": "UP"
 },
 "ping": {
 "status": "UP"
 }
 }
}

여기서는 db에 문제가 발생했다. 하나라도 문제가 있으면 DOWN으로 보기 때문에 전체 상태도 DOWN이다.

참고로 액츄에이터는 db , mongo , redis , diskspace , ping 과 같은 수 많은 헬스 기능을 기본으로 제공한다.

애플리케이션 정보

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

기본으로 제공하는 기능은 다음과 같다.

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





로거

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

LogController 생성

@Slf4j
@RestController
public class LogController {
 	@GetMapping("/log")
 	public String log() {
 		log.trace("trace log");
 		log.debug("debug log");
 		log.info("info log");
 		log.warn("warn log");
 		log.error("error log");
 		return "ok";
 	}
}

여러 레벨 로그를 남기는 단순한 컨트롤러이다.

실시간 로그 레벨 변경

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

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

loggers 엔드포인트를 사용하면 애플리케이션을 다시 시작하지 않고, 실시간으로 로그 레벨을 변경할 수 있다.

HTTP 요청 응답 기록

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

HttpExchangeRepository 인터페이스의 구현체를 빈으로 등록하면 httpexchanges 엔드포인트를 사용할 수 있다.
(주의! 해당 빈을 등록하지 않으면 httpexchanges엔드포인트가 활성화되지 않는다)

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

실행해보면 지금까지 실행한 HTTP 요청과 응답 정보를 확인할 수 있다.
참고로 이 기능은 매우 단순하고 기능에 제한이 많기 때문에 개발 단계에서만 사용하고, 실제 운영 서비스에서는 모니터링 툴이나 핀포인트, Zipkin 같은 다른 기술을 사용하는 것이 좋다.

액츄에이터와 보안

보안 주의

액츄에이터가 제공하는 기능들은 우리 애플리케이션의 내부 정보를 너무 많이 노출한다. 그래서 외부 인터넷 망이 공개된 곳에 액츄에이터이 엔드포인트를 공개하는 것은 보안상 좋은 방법이 아니다.
액츄에이터의 엔드포인트들은 외부 인터넷에서 접근이 불가능하게 막고, 내부에서만 접근 가능한 내부망을 사용하는 것이 안전하다.

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

예를 들어서 외부 인터넷 망을 통해서 8080포트에만 접근할 수 있고, 다른 포트는 내부망에서만 접근할 수 있다면 액츄에이터에 다른 포트를 설정하면 된다.
액츄에이터의 기능을 애플리케이션 서버와는 다른 포트에서 실행하려면 다음과 같이 설정하면 된다.
이 경우 기존 8080포트에서는 액츄에이터에 접근할 수 있다.

profile
현서황
노는 게 제일 좋은 뽀로로
이전 포스트

[spring boot] 외부 설정과 프로필2

다음 포스트

[spring boot] 마이크로미터, 프로메테우스, 그라파나

0개의 댓글