문서

Spring Boot Actuator의 헬스체크 살펴보기

양권성 · 토스 · 토스 기술 블로그

소개

서버의 상태를 알려주는 헬스 체크에 대해 알고 계시나요? 단순히 200 OK만 내려주겠거니 하고 별로 신경을 안 쓰고 계셨나요? 해당 포스트에서는 Spring Boot Actuaor가 제공해주는 헬스 체크는 어떤 식으로 서버의 상태를 점검하는지, 어떤 부분을 주의하며 사용해야하는지 알아봅니다.

AI 핵심 요약

Spring Boot Actuator의 헬스체크는 여러 HealthIndicator의 상태를 SimpleStatusAggregator가 합산하며, 기본 우선순위에서는 하나의 DOWN만 있어도 전체 서버 상태가 DOWN으로 판정됩니다. 이 때문에 비동기로 처리하는 로그 DB나 Elasticsearch처럼 핵심 요청 처리에 필수적이지 않은 의존성의 장애도 로드 밸런서가 서버를 제외하게 만들어 서비스 장애나 트러블슈팅 지연으로 이어질 수 있습니다. 글은 헬스체크에 포함되는 자동 설정 지표와 상태 집계 원리를 살펴보고, 필요에 따라 지표를 비활성화하거나 직접 헬스체크 API를 구현하는 방안을 제시합니다. 헬스체크를 단순한 200 OK 응답으로 여기지 말고, 서비스의 가용성 기준과 장애 격리 설계에 맞게 구성해야 한다는 점을 강조합니다.

Spring Boot Actuator는 의존성이 있을 때 관련 HealthIndicator를 자동 활성화하므로, 어떤 컴포넌트가 헬스 상태에 포함되는지 확인하세요.
기본 상태 우선순위는 DOWN, OUT_OF_SERVICE, UP, UNKNOWN이며, 하나라도 DOWN이면 전체 상태가 DOWN으로 집계됩니다.
서비스 핵심 경로에 필요하지 않은 DB나 외부 시스템의 장애가 전체 헬스체크에 전파되지 않도록 지표를 비활성화하거나 별도 엔드포인트를 설계할 수 있습니다.
상세 헬스 정보는 민감한 정보를 노출할 수 있으므로 운영 환경에서 공개 범위와 접근 권한을 신중히 설정하세요.