[Spring Boot] 액추에이터(Actuator) 정리

≣ 목차

 

액추에이터란?

스프링 부트는 프로덕션 환경에서 애플리케이션을 모니터링하고 관리하는데 필요한 감사(auditing), 추적(trace), 지표(metric)을 자동으로 수집하는 기능을 제공하며, HTTP 엔드포인트와 JMX를 통해 애플리케이션의 상태를 확인하고 관리할 수 있습니다.

 

그럼 해당 기능들이 왜 필요할까??

모니터링을 통해 개발자는 애플리케이션의 상태를 쉽게 파악하고 문제를 신속하게 해결할 수 있으며, 시스템의 부하나 성능 저하를 조기에 감지할 수 있습니다. 또한, 보안 설정을 통해 중요한 정보에 대한 접근을 제어할 수 있어 민감한 데이터의 노출을 방지할 수 있습니다. 이러한 이유로 스프링 액추에이터는 애플리케이션의 효율적인 관리와 운영에 필수적인 도구로 자리잡고 있습니다.

 

build.gradle

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

Spring Boot Actuator를 사용하려면 build.gradle 파일에 다음과 같이 라이브러리를 추가하면 Actuator를 사용할 수 있습니다.

 

이제 http://localhost:8080/actuator에 접속하면 JSON 형식으로 서버의 상태 정보를 확인할 수 있습니다. Actuator는 서버 상태 외에도 여러 유용한 기능을 제공하는데, 이러한 기능을 사용하기 위해서는 설정 파일에 추가적인 설정이 필요합니다.

 

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

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

 

설정 파일 설정 후 http://localhost:8080/actuator로 접속

이렇게 액추에이터가 제공하는 url를 확인하면 /actuator/{xxx} 형식인 걸 확인할 수 있으며, 이러한 url들을 모두 엔드포인트라고 합니다.

 

 

엔드포인트란?

엔드포인트는 컴퓨터 네트워크에 연결되는 모든 장치를 말합니다. Bob과 Alice가 전화로 통화할 때 두 사람의 연결은 한 사람에서 다른 사람으로 확장되며, 연결의 "엔드포인트" 는 각자의 전화입니다. 마찬가지로 네트워크에서 컴퓨터 장치들은 서로 "대화"를 주고받으며 정보를 주고받습니다. Bob과 Alice의 대화에서 Bob이 하나의 엔드포인트인 것처럼, 네트워크에 연결된 컴퓨터는 지속해서 데이터가 교환되는 하나의 엔드포인트입니다. - CLOUDFLARE https://www.cloudflare.com/ko-kr/learning/security/glossary/what-is-endpoint/

 

액추에이터 엔드포인트 사용 방법

액추에이터 엔드포인트를 사용하기 위해서는 다음과 같은 절차가 필요합니다.

1. 엔드포인트 활성화: 사용하고자 하는 엔드포인트를 먼저 활성화해야 합니다.
2. 엔드포인트 노출: 활성화한 엔드포인트를 HTTP 또는 JMX로 노출할지를 결정합니다.

중요한 점은 엔드포인트를 활성화하고 노출해야만 사용할 수 있다는 것입니다. 대부분의 엔드포인트는 기본적으로 활성화되어 있지만, 서버 종료 기능을 가진 shutdown 엔드포인트는 서비스 가용성 문제로 기본적으로 비활성화되어 있습니다. 이 말은 은 즉  shutdown을 제외한 다른 엔드포인트들은 노출하기만 하면 사용할 수 있습니다.

 

 

자주 사용하는 엔드포인트 종류

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

 

다른 엔드포인트는 다음 공식 메뉴얼을 참고 부탁드립니다.

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

 

 

health - 서버 상태

health 엔드포인트는 애플리케이션의 상태를 신속하게 파악할 수 있도록 도와줍니다. 단순히 애플리케이션 서버의 상태를 확인하는 것에 그치지 않고, 데이터베이스의 응답 여부, 디스크 사용량 등 다양한 정보를 포함하여 종합적인 상태를 보여줍니다. 이를 통해 문제가 발생했을 때 빠르게 인지하고 대응할 수 있습니다. 그리고 health 컴포넌트 중 하나라도 문제가 발생하면 전체 상태는 DOWN으로 표시됩니다.

 

 

application.yml

management:
  endpoint:
    health:
      show-details: always     # 컴포넌트의 상세한 정보를 보여줌
      show-components: always  # 컴포넌트의 상태 정보만 보여줌

해당 설정을 추가하면 애플리케이션의 health 엔드포인트에서 상세한 상태 정보를 확인할 수 있습니다.

 

 

info - 애플리케이션 정보

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

 

info가 제공하는 옵션

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

 

application.yml

management:
  info:
    java:
      enabled: true
    os:
      enabled: true
    env:
      enabled: true
      
info:
  app:
    name: info-name-actuator
    company: yh

java, os, env 옵션을 활성화하며,  env옵션을 활용해 info.app.로 시작하는 정보를 제공합니다.

 

결과

 

 

 

build

빌드 정보를 노출하기 위해서는 빌드 시점에 META-INF/build-info.properties 파일을 생성해야 합니다. 이를 위해 build.gradle 파일에 다음과 같은 설정을 추가합니다.

 

build.gradle

springBoot {
    buildInfo()
}

이 설정을 추가한 후 http://localhost:8080/actuator/info에 접속하면 애플리케이션의 기본 정보, 버전, 빌드된 시간을 확인할 수 있으며, build 폴더 내의 resources/main/META-INF/build-info.properties 파일이 생성됩니다. 

 

참고로 저는 info 엔드포인트에 접속했을 때 build-info.properties 파일이 생성되었습니다. 하지만 다른 분들은 빌드 과정에서 자동으로 파일이 생성되는 경우도 있다고 하네요.  혹시 build-info.properties 파일 생성 시점이 다른 이유에 대해서 아시는 분 있으면 댓글 부탁드릴게요 ㅠㅠㅠ

 

 

Git

Git 관련 정보를 노출하기 위해서는 git.properties 파일이 필요하며, 프로젝트가 Git과 연결되어 있어야 합니다. 이 파일도 직접 생성하는 것이 아니라 아래와 같은 설정을 하면 자동으로 생성됩니다.

plugins {
    id "com.gorylenko.gradle-git-properties" version "2.4.2"
}

 

git에 대한 더 자세한 정보를 보고 싶다면 다음 옵션을 적용하면 됩니다.

management:
  info:
    git:
      mode: "full"

 

 

loggers - 로깅

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

 

 

실시간 로그 레벨 변경 방법

POST 요청으로 http://localhost:8080/actuator/loggers/{특정 로깅 이름} url에 요청을 보내고, 요청 데이터로 아래처럼 JSON 형식으로 데이터를 보내면 로깅 레벨을 변경할 수 있습니다.

 

POST 요청 : http://localhost:8080/actuator/loggers/로깅 이름

{
 "configuredLevel": "TRACE"
}

 

httpexchanges - HTTP 요청 응답 기록

사용자가 요청한 HTTP 요청과 응답 기록을 확인하려면 httpexchanges 엔드포인트를 활용할 수 있습니다. 이 엔드포인트를 사용하기 위해서는 HttpExchangeRepository 인터페이스의 구현체를 빈으로 등록해야 합니다. 기본적으로 100개의 요청이 기록되며, 해당 설정은 setCapacity() 메서드를 통해 변경할 수 있습니다.

 

 

 

 

 

참고

[1] - https://techblog.woowahan.com/9232/

[2] - https://ksl2950.tistory.com/147

[3] - 스프링 부트 핵심 원리와 활용(김영한)