수동 헬스체크 구현

@Getter
public class HealthResponse {
    private final String status;
    private final String timestamp;

    public HealthResponse(String status, String timestamp) {
        this.status = status;
        this.timestamp = timestamp;
    }
}

@RestController
public class HealthController {

    @GetMapping("/health")
    public HealthResponse health() {
        return new HealthResponse(
            "UP",
            LocalDateTime.now().toString()
        );
    }
}

/health API 호출 시

{
    "status": "UP",
    "timestamp": "2026-09-28T16:41:20.878053700"
}

한계

• 서버 앱이 작동중인 건 알 수 있지만, 그것만으로 정상 동작한다고 말할 수는 없음
• 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

앱의 상태, 메트릭, 환경 정보를 HTTP 엔드포인트로 제공

• 헬스체크: DB, Redis 등 자동 감지
• 앱 정보: 버전, Git 커밋 정보
• 메트릭: CPU, 메모리, 요청 수
• 환경 정보: 설정값, 환경변수

의존성 추가 및 API 실습

implementation 'org.springframework.boot:spring-boot-starter-actuator'

이제 앞서 구현한 HealthController 같은 코드 없이도 자동으로 API 응답 로직이 생성됨

정상 응답	MySQL 도커 컨테이너를 끈 경우

spring-boot-starter-data-jpa 같은 의존성을 자동으로 감지하고, 모든 의존성이 정상일 때만 UP 응답을 돌려준다!

주요 엔드포인트

기본적으론 /actuator/health만 노출되어 사용 가능하다.

엔드포인트	용도	민감도	기본 노출
/actuator/health	앱 상태 확인	🟢 낮음	✅
/actuator/info	앱 정보	🟢 낮음	❌
/actuator/metrics	성능 지표	🟡 중간	❌
/actuator/env	환경변수, 설정값	🔴 높음	❌
/actuator/configprops	모든 설정값	🔴 높음	❌
/actuator/heapdump	JVM 메모리 덤프	🔴 높음	❌
/actuator/threaddump	스레드 정보	🟡 중간	❌

상세 응답 활성화

# never는 상세 정보 숨김
management.endpoint.health.show-details=always

활성화 예시

management.endpoints.web.exposure.include=health,info
management.info.env.enabled=true

# info 호출 시 나오는 정보
info.app.name=health-app
info.app.version=1.0.0

Actuator 보안

위험한 설정 예시

management.endpoints.web.exposure.include=health,info,env
management.endpoint.env.show-values=ALWAYS

민감도가 높은 /actuator/env 등은 외부로 노출해서는 안된다!

일반적으로 prod(라이브서버)에서는 health, info 정도만 노출해야 함