스프링 부트 액추에이터
1. 개요
1. 개요
스프링 부트 액추에이터는 스프링 부트 기반 애플리케이션의 프로덕션 준비 기능을 제공하는 하위 프로젝트이다. VMware의 스프링 팀이 개발한 이 도구는 자바 가상 머신 위에서 실행되는 스프링 애플리케이션의 상태를 모니터링하고 관리하는 데 필요한 다양한 기능을 표준화된 방식으로 제공한다.
주요 용도는 애플리케이션의 헬스 체크, 메트릭 수집, 그리고 운영 중인 애플리케이션의 환경 설정이나 로깅 레벨과 같은 요소를 동적으로 관리하는 것이다. 이를 통해 개발자와 운영팀은 별도의 복잡한 모니터링 도구를 구축하지 않고도 애플리케이션의 내부 상태를 쉽게 점검하고 성능 데이터를 수집할 수 있다.
액추에이터는 HTTP 엔드포인트나 JMX를 통해 이러한 정보를 노출시킨다. 기본적으로 제공되는 엔드포인트를 통해 애플리케이션의 상태 정보, 환경 변수, 등록된 빈 목록, HTTP 매핑 정보 등에 접근할 수 있어, 디버깅과 운영 관리에 큰 편의성을 제공한다.
이 도구는 스프링 부트 생태계의 일부로 통합되어 있어, 의존성만 추가하면 간단히 사용을 시작할 수 있다. 따라서 마이크로서비스 아키텍처나 클라우드 환경에서 수많은 서비스를 운영할 때 각 서비스의 건강 상태와 성능을 중앙에서 효율적으로 관리하는 데 핵심적인 역할을 한다.
2. 주요 기능
2. 주요 기능
2.1. 헬스 체크(Health)
2.1. 헬스 체크(Health)
헬스 체크는 애플리케이션의 실행 상태와 주요 외부 의존성의 연결 상태를 점검하는 기능이다. /actuator/health 엔드포인트를 통해 접근할 수 있으며, 애플리케이션이 정상적으로 서비스 가능한 상태인지(UP), 아니면 문제가 있는 상태인지(DOWN)를 간략하게 표시한다. 이는 로드 밸런서나 컨테이너 오케스트레이션 플랫폼(예: 쿠버네티스)이 애플리케이션 인스턴스의 서비스 트래픽 전달 여부를 결정하는 데 핵심적인 지표로 활용된다.
기본적으로 애플리케이션 자체의 상태만을 확인하지만, 데이터베이스, 디스크 공간, 메일 서버, NoSQL 데이터 저장소 등 다양한 외부 컴포넌트에 대한 상태 확인(Health Indicator)을 자동으로 구성할 수 있다. 예를 들어, 스프링 데이터 JPA를 사용하면 해당 데이터소스의 연결 상태가 헬스 체크 결과에 자동으로 포함된다. 이렇게 수집된 각 컴포넌트의 상세 상태는 별도의 설정을 통해 확인할 수 있다.
헬스 체크의 상세 정보 노출 여부는 설정으로 제어할 수 있다. 기본적으로 보안을 위해 요약 정보만 보여주지만, 설정을 변경하면 각 헬스 인디케이터의 구체적인 상태(예: 데이터베이스 버전, 디스크 여유 공간)를 포함한 상세 리포트를 얻을 수 있다. 이를 통해 단순한 정상 여부를 넘어서 시스템의 전반적인 건강 상태를 심층적으로 진단하는 데 도움을 준다.
2.2. 메트릭스(Metrics)
2.2. 메트릭스(Metrics)
스프링 부트 액추에이터의 메트릭스 기능은 애플리케이션의 성능과 상태를 수치화하여 제공한다. 이 기능은 JVM 메모리 사용량, 가비지 컬렉션 횟수, 스레드 상태, HTTP 요청 처리 시간과 같은 광범위한 런타임 지표를 자동으로 수집하고 노출한다. 이러한 메트릭은 /actuator/metrics 엔드포인트를 통해 확인할 수 있으며, 특정 지표를 상세히 조회할 수도 있다.
메트릭스는 마이크로미터 라이브러리를 통합하여 동작한다. 마이크로미터는 프로메테우스, 그라파나, 인플럭스DB와 같은 다양한 모니터링 시스템에 메트릭을 전송할 수 있는 벤더 중립적인 파사드 인터페이스를 제공한다. 이를 통해 개발자는 코드를 변경하지 않고도 원하는 모니터링 백엔드로 메트릭을 쉽게 내보낼 수 있다.
사용자는 커스텀 메트릭을 정의하여 비즈니스 로직의 특정 지표를 추적할 수 있다. 예를 들어, 주문 처리 횟수나 특정 API의 평균 응답 시간을 측정하는 것이 가능하다. 이러한 메트릭은 애플리케이션의 운영 상태를 실시간으로 파악하고, 성능 병목 현상을 식별하며, 용량 계획을 수립하는 데 핵심적인 역할을 한다.
2.3. 환경 정보(Environment)
2.3. 환경 정보(Environment)
/env 엔드포인트는 현재 애플리케이션의 모든 환경 변수 정보를 한눈에 확인할 수 있게 해준다. 이는 애플리케이션이 실행되는 운영 체제의 환경 변수뿐만 아니라, 자바 가상 머신 시스템 속성, 스프링 부트의 application.properties나 application.yml 파일에서 로드한 구성 속성, 그리고 활성 프로파일에 의해 적용되는 모든 속성들을 포함한다. 이 정보는 키-값 쌍 형태로 체계적으로 표시되어, 특정 속성의 출처와 최종적으로 적용된 값을 쉽게 추적할 수 있도록 돕는다.
이 엔드포인트는 특히 구성 문제를 디버깅할 때 매우 유용하다. 예를 들어, 예상과 다른 값이 적용되었거나, 특정 프로파일이 활성화되지 않은 경우, 여러 구성 소스 간의 충돌이 발생한 경우 등을 신속하게 파악할 수 있다. 또한, 실행 중인 애플리케이션의 환경 정보를 실시간으로 확인할 수 있어, 배포 후 설정 변경의 즉각적인 확인이나, 클라우드 환경에서 주입되는 동적 구성 값을 검증하는 데 활용된다.
/env 엔드포인트는 읽기 전용으로 제공되지만, POST 요청을 통해 특정 속성 값을 동적으로 갱신할 수도 있다. 이 기능을 사용하면 애플리케이션을 재시작하지 않고도 로그 레벨 변경과 같은 일부 구성을 실시간으로 조정할 수 있어, 운영 중인 시스템의 유연한 관리를 가능하게 한다. 다만, 보안상의 이유로 이 기능은 신중하게 활성화하고 접근을 제한해야 한다.
2.4. 빈 정보(Beans)
2.4. 빈 정보(Beans)
빈 정보 엔드포인트는 실행 중인 스프링 부트 애플리케이션의 스프링 IoC 컨테이너에 등록된 모든 빈의 상세 내역을 조회할 수 있게 해준다. 이 엔드포인트를 통해 개발자는 애플리케이션 컨텍스트가 구성한 빈의 전체 목록과 각 빈의 정의 속성을 확인할 수 있다. 이는 복잡한 의존성 주입 구조를 이해하거나, 특정 빈이 예상대로 생성되었는지 검증할 때 유용하다.
/actuator/beans 엔드포인트에 접근하면 JSON 형식으로 빈의 상세 정보가 반환된다. 반환되는 정보에는 빈의 이름, 자바 클래스 타입, 싱글톤 여부, 그리고 해당 빈을 생성하는 데 사용된 의존성 목록이 포함된다. 이를 통해 빈 간의 의존 관계 그래프를 파악할 수 있어, 설정 오류를 디버깅하거나 애플리케이션 아키텍처를 분석하는 데 도움을 준다.
이 기능은 주로 개발 및 테스트 단계에서 활용되며, 프로덕션 환경에서는 보안상의 이유로 접근을 제한하는 경우가 많다. 스프링 부트 액추에이터의 다른 엔드포인트와 마찬가지로, 빈 정보 엔드포인트도 설정 파일을 통해 노출 여부와 접근 권한을 세밀하게 제어할 수 있다.
2.5. 매핑 정보(Mappings)
2.5. 매핑 정보(Mappings)
매핑 정보 엔드포인트는 애플리케이션 내부의 모든 HTTP 요청 경로와 이를 처리하는 컨트롤러 메서드 간의 연결 관계를 한눈에 확인할 수 있게 해준다. 이 정보는 /actuator/mappings 경로를 통해 JSON 형식으로 제공되며, 스프링 MVC, 스프링 웹플럭스, 서블릿 필터, 인터셉터 등 다양한 계층에서 정의된 매핑을 포함한다. 각 매핑 항목은 요청 프레디케이트, 처리기 메서드의 세부 정보, 선언된 HTTP 메서드 등을 상세히 보여준다.
이 기능은 특히 대규모 애플리케이션에서 특정 URL이 어떤 빈의 어떤 메서드로 라우팅되는지 추적하거나, 예상치 못한 경로 충돌을 디버깅할 때 유용하다. 개발 단계에서는 애플리케이션의 API 구조를 빠르게 파악하는 데 도움이 되며, 운영 환경에서는 현재 활성화된 모든 엔드포인트를 검증하는 목적으로 활용될 수 있다. 매핑 정보는 애플리케이션의 라우팅 구성을 투명하게 만들어 줌으로써 시스템의 이해와 유지보수성을 높인다.
2.6. 로그 관리(Loggers)
2.6. 로그 관리(Loggers)
로그 관리(Loggers) 엔드포인트는 애플리케이션 내부의 로깅 시스템을 실시간으로 확인하고 구성할 수 있는 기능을 제공한다. 이 엔드포인트를 통해 개발자나 운영자는 애플리케이션을 재시작하지 않고도 특정 패키지나 클래스의 로그 레벨을 동적으로 변경할 수 있다. 예를 들어, 프로덕션 환경에서 갑자기 발생한 문제를 디버깅하기 위해 특정 컴포넌트의 로그 레벨을 DEBUG로 일시적으로 높여 상세한 정보를 얻은 후, 다시 INFO 레벨로 복원하는 작업이 가능하다.
이 엔드포인트는 주로 두 가지 방식으로 접근한다. 첫째, GET 요청을 통해 애플리케이션에 구성된 모든 로거의 이름과 현재 로그 레벨 목록을 조회할 수 있다. 둘째, 특정 로거에 대해 POST 요청을 보내 새로운 로그 레벨을 설정할 수 있다. 이를 통해 문제 해결 시 필요한 로그 출력을 즉시 활성화하여 장애 조치 시간을 단축하고 시스템의 가동 중단을 최소화하는 데 기여한다.
HTTP 메서드 | 경로 예시 | 설명 |
|---|---|---|
GET |
| 모든 로거의 구성 상태를 조회 |
GET |
| 특정 로거의 상세 구성(유효 로그 레벨 등) 조회 |
POST |
| 특정 로거의 로그 레벨을 변경 (요청 본문에 |
이러한 동적 로그 관리 기능은 마이크로서비스 아키텍처나 클라우드 네이티브 환경에서 특히 유용하다. 여러 서비스가 분산되어 실행되는 환경에서는 특정 서비스의 내부 상태를 즉시 파악하는 것이 중요하며, 로그 관리 엔드포인트는 이러한 운영상의 요구에 부응하는 핵심 도구이다.
3. 엔드포인트 구성 및 보안
3. 엔드포인트 구성 및 보안
스프링 부트 액추에이터는 다양한 모니터링 및 관리 기능을 HTTP 엔드포인트를 통해 노출한다. 기본적으로 /actuator 경로 아래에 엔드포인트가 구성되며, 각 엔드포인트는 특정 정보를 제공하거나 애플리케이션 상태를 변경하는 기능을 수행한다. 예를 들어, /actuator/health는 애플리케이션의 헬스 체크 상태를, /actuator/metrics는 시스템 메트릭을 확인할 수 있다.
프로덕션 환경에서는 이러한 엔드포인트에 대한 접근 제어가 필수적이다. 스프링 부트는 스프링 시큐리티와의 통합을 통해 강력한 보안 설정을 제공한다. 기본적으로 대부분의 엔드포인트는 민감한 정보를 포함할 수 있어 보안이 활성화된 경우 접근이 제한된다. 개발자는 application.properties 또는 application.yml 설정 파일을 통해 각 엔드포인트의 활성화 여부와 노출 방식을 세밀하게 제어할 수 있다.
엔드포인트의 보안 구성은 크게 두 가지 방식으로 이루어진다. 첫째, 엔드포인트 자체를 활성화하거나 비활성화할 수 있다. 둘째, 엔드포인트를 HTTP로 노출할지, JMX로만 노출할지 선택할 수 있다. 민감한 엔드포인트는 기본적으로 JMX를 통해서만 접근 가능하도록 설정되어 있으며, HTTP 노출 시에는 반드시 인증 및 권한 부여 설정이 필요하다.
또한, 엔드포인트의 경로를 변경하거나, CORS 정책을 설정하며, 엔드포인트가 반환하는 정보의 상세 정도를 관리하는 것도 가능하다. 이러한 유연한 구성 옵션 덕분에 운영 환경의 보안 요구사항과 모니터링 정책에 맞춰 액추에이터를 안전하게 활용할 수 있다.
4. 사용 방법
4. 사용 방법
4.1. 의존성 추가
4.1. 의존성 추가
스프링 부트 액추에이터를 사용하기 위해서는 프로젝트에 해당 의존성을 추가해야 한다. 가장 일반적인 방법은 메이븐이나 그레이들 같은 빌드 도구를 통해 스프링 부트 스타터 액추에이터 의존성을 포함시키는 것이다.
메이븐 기반 프로젝트의 경우 pom.xml 파일의 <dependencies> 섹션에 다음 의존성을 선언한다. 그레이들 프로젝트에서는 build.gradle 파일의 dependencies 블록에 동일한 의존성을 추가하면 된다. 이 의존성은 스프링 부트의 자동 구성 기능을 활용하여 액추에이터의 핵심 엔드포인트와 기능을 애플리케이션에 자동으로 설정한다.
기본적인 액추에이터 스타터 외에도 특정 기능을 위해 추가 의존성이 필요할 수 있다. 예를 들어, 마이크로미터를 통한 상세한 메트릭스 수집을 위해 micrometer-registry-{시스템명} 의존성을, 또는 JMX나 HTTP를 통한 원격 관리를 보다 풍부하게 지원하기 위한 별도의 스타터를 추가할 수 있다. 프로젝트의 요구사항에 따라 이러한 의존성들을 조합하여 사용한다.
4.2. 엔드포인트 활성화
4.2. 엔드포인트 활성화
스프링 부트 액추에이터의 각 엔드포인트는 기본적으로 활성화 또는 비활성화 상태로 구성된다. 모든 엔드포인트를 한꺼번에 활성화하거나, 특정 엔드포인트만 선택적으로 활성화할 수 있다. 이는 application.properties 또는 application.yml 파일을 통해 설정한다.
기본적으로 health와 info 엔드포인트만 활성화되어 있으며, 다른 엔드포인트들은 보안을 위해 비활성화되어 있다. 모든 엔드포인트를 활성화하려면 management.endpoints.web.exposure.include=* 속성을 설정한다. 반대로, 특정 엔드포인트만 노출하려면 쉼표로 구분하여 나열하면 된다. 예를 들어, health, metrics, env 엔드포인트만 활성화하려면 management.endpoints.web.exposure.include=health,metrics,env와 같이 설정한다.
특정 엔드포인트를 명시적으로 제외할 수도 있다. management.endpoints.web.exposure.exclude 속성을 사용하면, include로 포함된 목록에서 다시 특정 엔드포인트를 제외시킬 수 있다. 이는 세밀한 제어를 가능하게 한다. 또한, 각 개별 엔드포인트의 활성화 여부는 management.endpoint.<엔드포인트ID>.enabled 속성으로도 제어할 수 있다.
JMX를 통한 엔드포인트 노출은 HTTP와 별도로 관리된다. 기본적으로 모든 액추에이터 엔드포인트는 JMX를 통해 노출되며, management.endpoints.jmx.exposure 속성을 사용하여 JMX 노출 범위를 조정할 수 있다. 이렇게 함으로써 운영 환경에서 필요한 모니터링 도구만 선택적으로 사용할 수 있도록 구성하는 것이 일반적이다.
4.3. 설정 커스터마이징
4.3. 설정 커스터마이징
스프링 부트 액추에이터의 설정 커스터마이징은 application.properties 또는 application.yml 파일을 통해 이루어진다. 기본적으로 활성화된 엔드포인트는 /actuator/health와 /actuator/info 뿐이므로, 다른 엔드포인트를 사용하려면 명시적으로 활성화해야 한다. 예를 들어, 모든 엔드포인트를 웹에 노출시키려면 management.endpoints.web.exposure.include=* 속성을 설정한다. 반대로 특정 엔드포인트만 노출하거나, 민감한 엔드포인트의 접근을 제한하는 것도 가능하다.
각 엔드포인트의 세부 동작도 설정을 통해 조정할 수 있다. 헬스 체크 엔드포인트의 경우, 특정 데이터베이스나 외부 서비스의 상태를 상세히 표시하도록 구성할 수 있으며, 메트릭스 엔드포인트는 수집할 지표의 범위나 마이크로미터와의 통합 방식을 설정한다. 또한, 엔드포인트의 접근 경로를 기본 /actuator에서 다른 경로로 변경하거나, 서블릿 컨테이너의 포트와는 별도의 관리용 포트를 지정하여 운영 환경에서의 보안을 강화할 수 있다.
보안 설정은 매우 중요한 커스터마이징 요소이다. 스프링 시큐리티가 프로젝트에 포함되어 있다면, 액추에이터 엔드포인트 경로에 대한 접근 제어 규칙을 정의해야 한다. 일반적으로 헬스 체크와 정보 엔드포인트는 공개적으로 접근 가능하게 하되, 시스템 환경 변수를 보여주는 /actuator/env나 애플리케이션 빈 목록을 보여주는 /actuator/beans와 같은 민감한 엔드포인트는 인증된 운영자만 접근할 수 있도록 제한하는 것이 일반적이다.
설정 항목 | 예시 값 | 설명 |
|---|---|---|
|
| 웹에 노출할 엔드포인트 목록 지정 |
|
| 헬스 체크 상세 정보 항상 표시 |
|
| 액추에이터 엔드포인트의 기본 경로 변경 |
|
| 액추에이터 엔드포인트 전용 포트 설정 |
이러한 설정을 통해 개발팀은 애플리케이션의 모니터링 정책과 운영 환경의 보안 요구사항에 맞춰 스프링 부트 액추에이터를 유연하게 적용할 수 있다.
5. 모니터링 및 운영 활용
5. 모니터링 및 운영 활용
스프링 부트 액추에이터는 애플리케이션의 운영 단계에서 효과적인 모니터링과 관리를 가능하게 하는 핵심 도구이다. 헬스 체크 엔드포인트를 통해 데이터베이스 연결 상태나 디스크 공간 같은 애플리케이션의 건강 상태를 실시간으로 확인할 수 있어, 장애 발생 시 빠른 대응의 근거를 제공한다. 또한 메트릭스 엔드포인트는 JVM 메모리 사용량, HTTP 요청 수, 시스템 부하 같은 다양한 런타임 지표를 수집하여 성능 추이를 분석하고 병목 현상을 진단하는 데 활용된다.
운영 환경에서는 이러한 엔드포인트 정보를 중앙 집중식 모니터링 시스템과 연동하여 활용한다. 대표적으로 프로메테우스 같은 시계열 데이터베이스가 메트릭스 데이터를 주기적으로 수집하고, 이를 그라파나 같은 대시보드 도구로 시각화한다. 이를 통해 여러 마이크로서비스 인스턴스의 상태를 한눈에 파악하고, 임계치를 초과할 경우 알림을 설정하는 등 선제적인 운영이 가능해진다.
애플리케이션의 동적 관리 측면에서도 유용하게 사용된다. 예를 들어, 로거 엔드포인트를 이용하면 애플리케이션을 재시작하지 않고도 특정 패키지의 로그 레벨을 실시간으로 변경하여 디버깅을 수행할 수 있다. 환경 정보 엔드포인트는 현재 적용 중인 모든 설정 값을 확인하게 해주어, 프로파일 전환이나 설정 오류를 신속히 점검하는 데 도움을 준다.
따라서 스프링 부트 액추에이터는 단순한 상태 확인을 넘어, 지속적인 성능 모니터링, 원격 애플리케이션 관리, 그리고 문제 발생 시의 신속한 원인 분석까지 포괄하는 프로덕션 운영의 필수 인프라 구성 요소 역할을 한다.
