Spring Boot Actuator

actuator

애플리케이션의 운영 상태를 모니터링하고 관리할 수 있도록 다양한 내부 지표(endpoint) 를 자동으로 제공해주는 Spring Boot 서브 모듈이다.
서비스에 문제가 없는지 모니터링하고 지표들을 심어서 감시하여 장애에 대응할 수 있다.
쉽게말하면 Spring 애플리케이션의 상태를 실시간으로 보여주는 계기판이다.

build.gradle 설정

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

해당 디펜던시를 추가 후 실행한뒤 http://localhost:{본인포트}/actuator 로 접속하여 확인할 수 있다.

application.yml 설정

여러 기능들을 웹 환경에서 노출하기 위해서는 application.yml(.properties) 파일에 아래와 같이 추가해야 한다.

# 모든 엔드포인트를 웹에 노출
management:
    endpoints:  
      web:  
        exposure:  
          include: "*"

# 방법2. 특정 엔드포인트 활성화 
management:
    endpoint:
        flyway:
            enabled: true # 기본값 false
    endpoints:
        web:  
            exposure:  
              include: "*"

왜 사용할까?

• 운영 중 애플리케이션의 상태를 실시간으로 점검
• 문제가 생겼을 때 빠르게 원인을 파악
• 모니터링 도구와의 연동도 쉽게 할 수 있음

endpoint 접근

actuator가 제공하는 기능을 엔드포인트라한다.
각 엔드포인트는 /actuator/{엔드포인트명} 로 접근할 수 있다.
예시로 애플리케이션 헬스 정보는 아래와 같다.
http://localhost:{본인포트}/actuator/health

endpoint 종류

액츄에이터가 제공하는 엔드포인트 중에서 자주 사용하는 엔드포인트들을 보면 다음과 같다.

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

전체 엔드포인트 공식 메뉴얼

/actuator/info

info 엔드포인트는 애플리케이션의 기본 정보를 노출한다.
기본적으로 제공하는 기능들은 아래와 같다.

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

management:
    info:
        java:
            enabled: true # 기본값 false
        os:
            enabled: true
        env:
            enabled: true

여기서 build, git 은 별도 파일이 필요하다.

/actuator/metrics

metrics 엔드포인트를 사용하면 기본적으로 제공되는 metrics들을 확인할 수 있다.
수집된 metrics은 Prometheus, Grafana 에 전달하여 원하는 metrics(지표)를 편리하게 사용하고 볼 수 있다.

actuator 보안

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

actuator 를 다른 포트에서 실행

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

management:
    server:
        port:9090

핵심기능

기능	설명
상태 점검	/actuator/health : 애플리케이션이 정상인지 확인 (로드밸런서 헬스 체크용)
메트릭 수집	/actuator/metrics : JVM 메모리, GC, HTTP 요청 시간 등 지표 확인
설정 확인	/actuator/env, /actuator/configprops : 설정값 및 바인딩 정보 확인
경로 확인	/actuator/mappings : 어떤 URL이 어떤 컨트롤러로 연결되는지 확인
외부 연동	Prometheus, Grafana, ELK 등 외부 모니터링 시스템과 연동 가능 (Micrometer 기반)

---

ref

https://docs.spring.io/spring-boot/docs/3.0.5/reference/html/actuator.html#actuator
https://hstory0208.tistory.com/entry/Spring-%EC%8A%A4%ED%94%84%EB%A7%81%EB%B6%80%ED%8A%B8-%EC%97%91%EC%B8%84%EC%97%90%EC%9D%B4%ED%84%B0Actuator%EB%9E%80?category=1054975