스프링 부트 액추에이터

헬스 체크는 애플리케이션의 실행 상태와 주요 외부 의존성의 연결 상태를 점검하는 기능이다. /actuator/health 엔드포인트를 통해 접근할 수 있으며, 애플리케이션이 정상적으로 서비스 가능한 상태인지(UP), 아니면 문제가 있는 상태인지(DOWN)를 간략하게 표시한다. 이는 로드 밸런서나 컨테이너 오케스트레이션 플랫폼(예: 쿠버네티스)이 애플리케이션 인스턴스의 서비스 트래픽 전달 여부를 결정하는 데 핵심적인 지표로 활용된다.

기본적으로 애플리케이션 자체의 상태만을 확인하지만, 데이터베이스, 디스크 공간, 메일 서버, NoSQL 데이터 저장소 등 다양한 외부 컴포넌트에 대한 상태 확인(Health Indicator)을 자동으로 구성할 수 있다. 예를 들어, 스프링 데이터 JPA를 사용하면 해당 데이터소스의 연결 상태가 헬스 체크 결과에 자동으로 포함된다. 이렇게 수집된 각 컴포넌트의 상세 상태는 별도의 설정을 통해 확인할 수 있다.

헬스 체크의 상세 정보 노출 여부는 설정으로 제어할 수 있다. 기본적으로 보안을 위해 요약 정보만 보여주지만, 설정을 변경하면 각 헬스 인디케이터의 구체적인 상태(예: 데이터베이스 버전, 디스크 여유 공간)를 포함한 상세 리포트를 얻을 수 있다. 이를 통해 단순한 정상 여부를 넘어서 시스템의 전반적인 건강 상태를 심층적으로 진단하는 데 도움을 준다.

스프링 부트 액추에이터의 메트릭스 기능은 애플리케이션의 성능과 상태를 수치화하여 제공한다. 이 기능은 JVM 메모리 사용량, 가비지 컬렉션 횟수, 스레드 상태, HTTP 요청 처리 시간과 같은 광범위한 런타임 지표를 자동으로 수집하고 노출한다. 이러한 메트릭은 /actuator/metrics 엔드포인트를 통해 확인할 수 있으며, 특정 지표를 상세히 조회할 수도 있다.

메트릭스는 마이크로미터 라이브러리를 통합하여 동작한다. 마이크로미터는 프로메테우스, 그라파나, 인플럭스DB와 같은 다양한 모니터링 시스템에 메트릭을 전송할 수 있는 벤더 중립적인 파사드 인터페이스를 제공한다. 이를 통해 개발자는 코드를 변경하지 않고도 원하는 모니터링 백엔드로 메트릭을 쉽게 내보낼 수 있다.

사용자는 커스텀 메트릭을 정의하여 비즈니스 로직의 특정 지표를 추적할 수 있다. 예를 들어, 주문 처리 횟수나 특정 API의 평균 응답 시간을 측정하는 것이 가능하다. 이러한 메트릭은 애플리케이션의 운영 상태를 실시간으로 파악하고, 성능 병목 현상을 식별하며, 용량 계획을 수립하는 데 핵심적인 역할을 한다.

/env 엔드포인트는 현재 애플리케이션의 모든 환경 변수 정보를 한눈에 확인할 수 있게 해준다. 이는 애플리케이션이 실행되는 운영 체제의 환경 변수뿐만 아니라, 자바 가상 머신 시스템 속성, 스프링 부트의 application.properties나 application.yml 파일에서 로드한 구성 속성, 그리고 활성 프로파일에 의해 적용되는 모든 속성들을 포함한다. 이 정보는 키-값 쌍 형태로 체계적으로 표시되어, 특정 속성의 출처와 최종적으로 적용된 값을 쉽게 추적할 수 있도록 돕는다.

이 엔드포인트는 특히 구성 문제를 디버깅할 때 매우 유용하다. 예를 들어, 예상과 다른 값이 적용되었거나, 특정 프로파일이 활성화되지 않은 경우, 여러 구성 소스 간의 충돌이 발생한 경우 등을 신속하게 파악할 수 있다. 또한, 실행 중인 애플리케이션의 환경 정보를 실시간으로 확인할 수 있어, 배포 후 설정 변경의 즉각적인 확인이나, 클라우드 환경에서 주입되는 동적 구성 값을 검증하는 데 활용된다.

/env 엔드포인트는 읽기 전용으로 제공되지만, POST 요청을 통해 특정 속성 값을 동적으로 갱신할 수도 있다. 이 기능을 사용하면 애플리케이션을 재시작하지 않고도 로그 레벨 변경과 같은 일부 구성을 실시간으로 조정할 수 있어, 운영 중인 시스템의 유연한 관리를 가능하게 한다. 다만, 보안상의 이유로 이 기능은 신중하게 활성화하고 접근을 제한해야 한다.

빈 정보 엔드포인트는 실행 중인 스프링 부트 애플리케이션의 스프링 IoC 컨테이너에 등록된 모든 빈의 상세 내역을 조회할 수 있게 해준다. 이 엔드포인트를 통해 개발자는 애플리케이션 컨텍스트가 구성한 빈의 전체 목록과 각 빈의 정의 속성을 확인할 수 있다. 이는 복잡한 의존성 주입 구조를 이해하거나, 특정 빈이 예상대로 생성되었는지 검증할 때 유용하다.

/actuator/beans 엔드포인트에 접근하면 JSON 형식으로 빈의 상세 정보가 반환된다. 반환되는 정보에는 빈의 이름, 자바 클래스 타입, 싱글톤 여부, 그리고 해당 빈을 생성하는 데 사용된 의존성 목록이 포함된다. 이를 통해 빈 간의 의존 관계 그래프를 파악할 수 있어, 설정 오류를 디버깅하거나 애플리케이션 아키텍처를 분석하는 데 도움을 준다.

이 기능은 주로 개발 및 테스트 단계에서 활용되며, 프로덕션 환경에서는 보안상의 이유로 접근을 제한하는 경우가 많다. 스프링 부트 액추에이터의 다른 엔드포인트와 마찬가지로, 빈 정보 엔드포인트도 설정 파일을 통해 노출 여부와 접근 권한을 세밀하게 제어할 수 있다.

매핑 정보 엔드포인트는 애플리케이션 내부의 모든 HTTP 요청 경로와 이를 처리하는 컨트롤러 메서드 간의 연결 관계를 한눈에 확인할 수 있게 해준다. 이 정보는 /actuator/mappings 경로를 통해 JSON 형식으로 제공되며, 스프링 MVC, 스프링 웹플럭스, 서블릿 필터, 인터셉터 등 다양한 계층에서 정의된 매핑을 포함한다. 각 매핑 항목은 요청 프레디케이트, 처리기 메서드의 세부 정보, 선언된 HTTP 메서드 등을 상세히 보여준다.

이 기능은 특히 대규모 애플리케이션에서 특정 URL이 어떤 빈의 어떤 메서드로 라우팅되는지 추적하거나, 예상치 못한 경로 충돌을 디버깅할 때 유용하다. 개발 단계에서는 애플리케이션의 API 구조를 빠르게 파악하는 데 도움이 되며, 운영 환경에서는 현재 활성화된 모든 엔드포인트를 검증하는 목적으로 활용될 수 있다. 매핑 정보는 애플리케이션의 라우팅 구성을 투명하게 만들어 줌으로써 시스템의 이해와 유지보수성을 높인다.

로그 관리(Loggers) 엔드포인트는 애플리케이션 내부의 로깅 시스템을 실시간으로 확인하고 구성할 수 있는 기능을 제공한다. 이 엔드포인트를 통해 개발자나 운영자는 애플리케이션을 재시작하지 않고도 특정 패키지나 클래스의 로그 레벨을 동적으로 변경할 수 있다. 예를 들어, 프로덕션 환경에서 갑자기 발생한 문제를 디버깅하기 위해 특정 컴포넌트의 로그 레벨을 DEBUG로 일시적으로 높여 상세한 정보를 얻은 후, 다시 INFO 레벨로 복원하는 작업이 가능하다.

이 엔드포인트는 주로 두 가지 방식으로 접근한다. 첫째, GET 요청을 통해 애플리케이션에 구성된 모든 로거의 이름과 현재 로그 레벨 목록을 조회할 수 있다. 둘째, 특정 로거에 대해 POST 요청을 보내 새로운 로그 레벨을 설정할 수 있다. 이를 통해 문제 해결 시 필요한 로그 출력을 즉시 활성화하여 장애 조치 시간을 단축하고 시스템의 가동 중단을 최소화하는 데 기여한다.

이러한 동적 로그 관리 기능은 마이크로서비스 아키텍처나 클라우드 네이티브 환경에서 특히 유용하다. 여러 서비스가 분산되어 실행되는 환경에서는 특정 서비스의 내부 상태를 즉시 파악하는 것이 중요하며, 로그 관리 엔드포인트는 이러한 운영상의 요구에 부응하는 핵심 도구이다.

스프링 부트 액추에이터를 사용하기 위해서는 프로젝트에 해당 의존성을 추가해야 한다. 가장 일반적인 방법은 메이븐이나 그레이들 같은 빌드 도구를 통해 스프링 부트 스타터 액추에이터 의존성을 포함시키는 것이다.

메이븐 기반 프로젝트의 경우 pom.xml 파일의 <dependencies> 섹션에 다음 의존성을 선언한다. 그레이들 프로젝트에서는 build.gradle 파일의 dependencies 블록에 동일한 의존성을 추가하면 된다. 이 의존성은 스프링 부트의 자동 구성 기능을 활용하여 액추에이터의 핵심 엔드포인트와 기능을 애플리케이션에 자동으로 설정한다.

기본적인 액추에이터 스타터 외에도 특정 기능을 위해 추가 의존성이 필요할 수 있다. 예를 들어, 마이크로미터를 통한 상세한 메트릭스 수집을 위해 micrometer-registry-{시스템명} 의존성을, 또는 JMX나 HTTP를 통한 원격 관리를 보다 풍부하게 지원하기 위한 별도의 스타터를 추가할 수 있다. 프로젝트의 요구사항에 따라 이러한 의존성들을 조합하여 사용한다.

스프링 부트 액추에이터의 각 엔드포인트는 기본적으로 활성화 또는 비활성화 상태로 구성된다. 모든 엔드포인트를 한꺼번에 활성화하거나, 특정 엔드포인트만 선택적으로 활성화할 수 있다. 이는 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 노출 범위를 조정할 수 있다. 이렇게 함으로써 운영 환경에서 필요한 모니터링 도구만 선택적으로 사용할 수 있도록 구성하는 것이 일반적이다.

스프링 부트 액추에이터의 설정 커스터마이징은 application.properties 또는 application.yml 파일을 통해 이루어진다. 기본적으로 활성화된 엔드포인트는 /actuator/health와 /actuator/info 뿐이므로, 다른 엔드포인트를 사용하려면 명시적으로 활성화해야 한다. 예를 들어, 모든 엔드포인트를 웹에 노출시키려면 management.endpoints.web.exposure.include=* 속성을 설정한다. 반대로 특정 엔드포인트만 노출하거나, 민감한 엔드포인트의 접근을 제한하는 것도 가능하다.

각 엔드포인트의 세부 동작도 설정을 통해 조정할 수 있다. 헬스 체크 엔드포인트의 경우, 특정 데이터베이스나 외부 서비스의 상태를 상세히 표시하도록 구성할 수 있으며, 메트릭스 엔드포인트는 수집할 지표의 범위나 마이크로미터와의 통합 방식을 설정한다. 또한, 엔드포인트의 접근 경로를 기본 /actuator에서 다른 경로로 변경하거나, 서블릿 컨테이너의 포트와는 별도의 관리용 포트를 지정하여 운영 환경에서의 보안을 강화할 수 있다.

보안 설정은 매우 중요한 커스터마이징 요소이다. 스프링 시큐리티가 프로젝트에 포함되어 있다면, 액추에이터 엔드포인트 경로에 대한 접근 제어 규칙을 정의해야 한다. 일반적으로 헬스 체크와 정보 엔드포인트는 공개적으로 접근 가능하게 하되, 시스템 환경 변수를 보여주는 /actuator/env나 애플리케이션 빈 목록을 보여주는 /actuator/beans와 같은 민감한 엔드포인트는 인증된 운영자만 접근할 수 있도록 제한하는 것이 일반적이다.

이러한 설정을 통해 개발팀은 애플리케이션의 모니터링 정책과 운영 환경의 보안 요구사항에 맞춰 스프링 부트 액추에이터를 유연하게 적용할 수 있다.