노트

Spring Boot Actuator

Spring Boot Actuator

백엔드#spring · 연결된 개념 7개

쉽게 말하면

Actuator는 자동차 계기판처럼 돌아가는 앱의 건강 상태, 지표, 설정을 밖에서 들여다볼 수 있게 해 줘요. 로드밸런서나 쿠버네티스가 이걸 보고 고장 난 앱을 빼거나 교체하죠.

비유가 깨지는 곳 계기판은 운전석에서만 보이지만 Actuator는 HTTP 주소라 누구나 두드려 볼 수 있어요. 그래서 기본은 health만 노출하고, 비밀값이 섞일 수 있는 env·heapdump는 관리 포트나 시큐리티로 막아요.

Spring Boot Actuator는 운영 중인 앱의 상태를 HTTP 엔드포인트로 보여주는 모듈이다. 헬스 체크, 지표, 설정값, 로그 레벨, 등록된 빈 같은 정보를 /actuator/* 아래에 노출한다.

<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>

자주 쓰는 엔드포인트

  • health: 앱과 DB·디스크 등 의존 대상의 상태. 로드밸런서·쿠버네티스 핵심 개념의 liveness·readiness 프로브(probe)로 쓴다
  • metrics, prometheus: JVM(Java Virtual Machine) 메모리, 요청 수·지연 시간 같은 지표(metrics, Micrometer). 모니터링 시스템이 긁어 간다
  • info: 빌드 버전, git 커밋
  • loggers: 실행 중에 로그 레벨을 바꾼다(로그 레벨과 Logback)
  • env, configprops, beans, conditions: 설정값과 빈, 자동 설정 판단 결과(스프링 부트 자동 설정)

노출과 보안

management:
  endpoints:
    web:
      exposure:
        include: health, info, prometheus
      base-path: /internal/actuator
  endpoint:
    health:
      show-details: when-authorized
  • 기본으로는 HTTP에 health만 노출된다. include: "*"는 개발에서만 쓴다. env·heapdump에는 비밀값이 섞일 수 있다
  • 운영에서는 관리 포트를 따로 두거나(management.server.port), 스프링 시큐리티로 관리자만 접근하게 막는다(시큐리티 필터체인)

Spring Boot Admin

여러 앱의 Actuator 정보를 모아 웹 UI(User Interface)로 보여주는 서드파티 프로젝트다. Admin 서버를 따로 띄우고, 각 앱은 클라이언트 설정(spring.boot.admin.client.url)으로 자동 등록된다. 별도 앱이라 포트를 따로 잡는다.

컨테이너 오케스트레이터가 헬스 체크로 죽은 인스턴스를 교체하는 흐름은 kubectl 디버깅 치트시트에서 상태를 읽는 법과 함께 보면 좋다.

출처: Spring Boot 문서: Actuator · Exposing Endpoints · Security · Kubernetes Probes

연결된 개념

이 노트를 가리키는 문서

뜻이 가까운 노트

  • 스프링 설정 외부화와 프로파일

    스프링 부트는 설정값을 코드 밖(application.yml·환경변수·명령줄 인자 등)에 두고, 실행 환경에 따라 다른 값을 주입하게 해 준다. 같은 빌드 산출물을 개발·QA·운영에 그대로 쓰고 설정만 바꾸는 것이 목표다.

  • 스프링 REST 컨트롤러

    @RestController는 메서드의 반환값을 뷰 이름이 아니라 HTTP 응답 본문(보통 JSON)으로 쓰는 컨트롤러다. @Controller에 @ResponseBody를 합친 것으로, 직렬화(serialization)는 Jackson이 맡는다.

  • 스프링 빈과 IoC 컨테이너

    스프링 빈은 스프링 IoC(Inversion of Control, 제어의 역전) 컨테이너가 만들고, 의존성을 연결하고, 생명주기(lifecycle)를 관리하는 평범한 자바 객체(POJO, Plain Old Java Object)다. 컨테이너(ApplicationContext)는 이 빈들을 담는 공간이고, 내가 new로 만든 객체는 컨테이너가 모른다.

  • Bean Validation

    Bean Validation은 객체 필드에 제약 어노테이션(constraint annotation)을 붙여 입력을 검증하는 자바 표준이다(Jakarta Validation, 구현체는 Hibernate Validator). 스프링은 컨트롤러 파라미터에 @Valid가 붙으면 바인딩 직후 검증을 실행한다.

  • Lombok

    Lombok은 게터·세터·생성자·toString 같은 반복 코드를 어노테이션으로 대신 생성해 주는 자바 라이브러리다. 컴파일할 때 어노테이션 처리기(annotation processor)가 바이트코드(bytecode)에 메서드를 넣는다. 스프링과는 별개 라이브러리라 따로 추가한다.

보기 옵션