Spring & Java
Spring Boot Actuator 본문
이번 시간에는 Spring Boot Actuator 학습해 보도록 하겠습니다. 수동 헬스체크를 통해서 어떤 문제가 있는지 알아보고 Spring Boot Actuator를 확인해 보겠습니다.
학습 목표
● 수동 헬스체크
● Spring Boot Actuator란?
● Actuator 주요 엔드포인트
● Actuator 보안
Intelli J 를 열고 Spring 프로젝트를 생성 하도록 하겠습니다.
DB 생성 완료!
Health 패키지를 만들고 Controller와 Response를 생성 합니다.
HealthResponse 구현
@Getter
public class HealthResponse {
private final String status;
private final String timestamp;
public HealthResponse(String status, String timestamp) {
this.status = status;
this.timestamp = timestamp;
}
}
HealthController
@RestController
public class HealthController {
@GetMapping("/health")
public HealthResponse health() {
return new HealthResponse(
"UP",
LocalDateTime.now().toString()
);
}
}
스프링 애플리케이션 실행 후, /health API 호출
응답 :
문제 없이 잘 되고 응답 하는 것을 확인할 수 있습니다.
자 문제가 하나 있습니다. 앱이 떠있는건 확인이 되는데 db같은 요소의 상태는 알 수가 없습니다.
수동방식의 한계
기본 헬스체크는 동작하지만, DB 같은 의존성을 체크하려면 코드가 많이 필요합니다.
단순히 앱이 떠있다고 정상동작한다고 말할 수 없기 때문입니다!
만약 DB 체크를 추가해야 된다면? DB 연결 상태를 확인하려면 아래 코드 처럼 복잡한 코드 예시가 필요해요.
// 1. DTO 클래스 추가 (DatabaseStatus.java)
public class DatabaseStatus {
private String status;
private String database;
private String error;
// 생성자, getter...
}
// 2. DataSource 주입
private final DataSource dataSource;
public HealthController(DataSource dataSource) {
this.dataSource = dataSource;
}
// 3. DB 체크 메서드
private DatabaseStatus checkDatabase() {
try (Connection conn = dataSource.getConnection()) {
return new DatabaseStatus("UP", conn.getMetaData().getDatabaseProductName());
} catch (SQLException e) {
return DatabaseStatus.down(e.getMessage());
}
}
문제점
● 코드량 증가 : 수동으로 하나하나 구현
● 표준 없음 : 프로젝트마다 응답 형식 다름● 유지보수 부담 : 새 의존성 추가 시 헬스체크 코드도 수정● 중복 코드 : 모든 프로젝트에서 비슷한 코드 반복
과연! 이부분이 최선일까요? 의존성만 추가하면 자동으로 헬스체크에 포함되면 안 될까?
표준화된 응답 형식이 있으면 좋을것 같은데 ..
이미 누가 만들어놓은거 없나?
-> 그래서 스프링에서는 헬스체크의 편의성을 위해 Spring Boot Actuator 라이버리를 사용할 수 있게 되는 것입니다.
Health 의존성 추가
implementation 'org.springframework.boot:spring-boot-starter-actuator'
이게 끝? 진짜 이게 끝입니다. 의존성 추가 하고 DB 자동 감지 실습 해보겠습니다.
DB가 있으면 Actuator가 알아서 체크합니다. * 코드 추가 필요 없음
Actuator 주요 엔드포인트
- Actuator는 다양한 엔트포인트를 제공합니다. 하지만 꼭 필요한 것만 노출해야 됩니다!!
● 노출 범위
management.endpoints.web.exposure.include=health,info
management.info.env.enabled=true
# info 호출 시 나오는 정보
info.app.name=health-app
info.app.version=1.0.0여기를 복사해서 추가해 보겠습니다
포스트맨 결과 예시
# info 호출 시 나오는 정보
info.app.name=health-app
info.app.version=1.0.0
값을 바꿀수 있어요!
이렇게 설정 해주는 순간 기본 값이 삭제 됩니다.
이 것이 없을땐 호출이 문제 없었지만 여기서 health를 빼면 403 에러 나올겁니다.
info.app.name=health-app-hello
info.app.version=1.0.1
이런식으로 바꿔서 요청 하면 응답을 이렇게 똑같이 합니다.
/actuator/health 상세
이번에는 상태 종류들을 상세하게 응답 하는 것을 해보겠습니다. 원래는 어떻게 나왔나요 ?
이런식으로 응답 했었죠? 하지만, 이번에는 다르게 또 설정 해보겠습니다
# never는 상세 정보 숨김
management.endpoint.health.show-details=always
추가해서 테스트 해볼까요? 응답이 실제로 어떻게 했는지 바로 체크가 가능해졌습니다.
< 실제 응답 >
{
"components": {
"db": {
"details": {
"database": "MySQL",
"validationQuery": "isValid()"
},
"status": "UP"
},
"diskSpace": {
"details": {
"total": 498264408064,
"free": 32936304640,
"threshold": 10485760,
"path": "C:\\Users\\user\\nbcam-projcet\\.",
"exists": true
},
"status": "UP"
},
"livenessState": {
"status": "UP"
},
"ping": {
"status": "UP"
},
"readinessState": {
"status": "UP"
},
"ssl": {
"details": {
"expiringChains": [],
"invalidChains": [],
"validChains": []
},
"status": "UP"
}
},
"groups": [
"liveness",
"readiness"
],
"status": "UP"
}
이런건 그런데.. 너무 사용하지 않는게 좋겠죠? 이런게 있다는 정도만 알고 계시면 됩니다.
management.endpoints.web.exposure.include=health,info,env
management.endpoint.env.show-values=ALWAYSmanagement.endpoints.web.exposure.include=health,info,env
#management.endpoint.env.show-values=ALWAYS호출 했더니 노출하면 안되는 내용들까지 다 나오는걸 확인 했습니다.
env 하나의 옵션 포인트가 있다 정도로 확인하고 넘어갑시다.
이번에는 Srping Boot Actuator을 배워봤습니다.
✏️ 느낀점
이번 Spring Boot Actuator 학습을 통해 단순히 애플리케이션이 실행되고 있는지 확인하는 것과, 실제로 서비스가 정상 동작 가능한 상태인지 확인하는 것은 전혀 다른 문제라는 것을 알게 되었다.
기존에 직접 구현했던 수동 헬스체크 방식은 /health API를 통해 서버가 실행 중인지 정도만 확인할 수 있었고, 데이터베이스나 디스크 상태 같은 주요 의존성의 상태까지는 확인할 수 없다는 한계가 있었다. 이러한 문제를 해결하기 위해 DB 연결 상태를 직접 체크하려면 DataSource 주입, 커넥션 생성, 예외 처리 등 많은 코드가 필요했고, 프로젝트마다 비슷한 헬스체크 코드가 반복된다는 점에서 비효율적이라고 느꼈다.
Spring Boot Actuator는 이러한 문제를 의존성 추가만으로 해결해 주는 도구라는 점에서 매우 인상 깊었다. 별도의 코드를 작성하지 않아도 DB, 디스크, JVM 상태 등을 자동으로 감지하고 표준화된 응답 형식으로 제공해 주는 점은 운영 환경에서 큰 장점이라고 생각되었다.
또한 Health 상태가 단순한 성공·실패 개념이 아니라, 실제 서비스 가능 여부를 판단하기 위한 기준이라는 점이 인상 깊었다. DB 연결이 실패했을 경우 서버는 실행 중이더라도 Health 상태는 DOWN으로 판단되고 503 응답을 반환하는 동작을 직접 확인하면서, 운영 환경에서는 “서버가 켜져 있는 것”보다 “트래픽을 받아도 되는 상태인지”가 훨씬 중요하다는 것을 이해하게 되었다.
특히 Actuator 엔드포인트 노출 설정을 통해 필요한 정보만 선택적으로 공개해야 한다는 점에서 보안의 중요성도 함께 느낄 수 있었다. 모든 엔드포인트를 무분별하게 노출할 경우 환경 변수나 민감 정보까지 외부에 공개될 수 있기 때문에, 운영 환경에서는 반드시 최소한의 엔드포인트만 허용해야 한다는 이유를 실습을 통해 체감할 수 있었다.
이번 학습을 통해 Spring Boot Actuator는 단순한 부가 기능이 아니라, 운영 서버에서 장애를 감지하고 서버 상태를 판단하기 위한 핵심 인프라 도구라는 것을 알게 되었다. 앞으로는 단순히 기능 구현에만 집중하는 개발이 아니라, “이 서비스가 지금 정상적으로 운영 가능한 상태인가”를 함께 고려하는 시각을 가져야겠다고 느끼는 시간이었다.