Spring Boot 실무 가이드 · 관측과 운영

이 파트에서 다루는 내용

Actuator로깅 전략메트릭과 추적패키징과 배포

Actuator는 유용한 만큼 위험합니다

Actuator를 추가하면 애플리케이션 상태를 확인할 수 있는 엔드포인트가 생깁니다. 헬스체크, 메트릭, 환경 정보, 빈 목록까지 제공합니다.

문제는 이 정보가 외부에 그대로 노출되면 공격에 활용된다는 점입니다. 기본값은 제한적이지만, 설정을 잘못 열어 두는 사고가 자주 발생합니다.

liveness / readiness

컨테이너 환경

liveness는 프로세스가 살아 있는지, readiness는 트래픽을 받을 준비가 됐는지입니다. 구분하지 않으면 기동 중인 인스턴스에 요청이 들어갑니다.

관리 포트 분리

접근 통제

운영 포트와 다른 포트로 열면 외부 노출을 네트워크 단에서 막기 쉽습니다.

health 상세 정보

주의

DB 연결 정보나 디스크 경로가 담길 수 있습니다. 인증된 요청에만 상세를 보여 줍니다.

노출 범위 제한yaml

management:
  endpoints:
    web:
      exposure:
        include: health,info,prometheus   # 필요한 것만 명시합니다
  endpoint:
    health:
      show-details: when-authorized       # 상세 정보는 인증된 경우만
      probes:
        enabled: true                     # liveness, readiness 분리
  server:
    port: 9090                            # 운영 포트와 분리

include에 * 를 쓰면 env, beans, configprops 같은 민감한 엔드포인트까지 열립니다. 운영 설정에서 별표를 발견하면 즉시 점검 대상입니다.

로그는 나중에 찾을 수 있어야 의미가 있습니다

장애 대응에서 로그를 못 찾으면 원인 분석이 불가능합니다. 무엇을 남기느냐보다 어떻게 찾느냐를 먼저 정해야 합니다.

요청 식별자

가장 중요

요청마다 고유 아이디를 부여해 모든 로그에 함께 남깁니다. 사용자 문의 한 건을 전체 로그에서 추적할 수 있습니다.

구조화 로그

검색 가능

JSON 형식으로 남기면 로그 수집 시스템에서 필드로 검색할 수 있습니다. 문자열 파싱보다 안정적입니다.

민감정보 마스킹

필수

비밀번호, 주민번호, 카드번호, 토큰이 로그에 남지 않게 합니다. 요청 본문 전체를 그대로 찍는 코드가 사고 원인입니다.

레벨 기준

노이즈 관리

정상 흐름은 info 이하, 대응이 필요한 것만 error로 남깁니다. error가 많으면 알림이 무의미해집니다.

파일 관리

디스크

로테이션과 보관 기간을 설정하지 않으면 디스크가 찹니다. 컨테이너 환경에서는 표준 출력으로 내보내고 수집은 외부에 맡깁니다.

지표는 문제를 미리 알려 줍니다

로그는 이미 벌어진 일을 확인하는 수단이고, 지표는 상태가 나빠지는 과정을 보여 줍니다. 둘 다 필요합니다.

Spring Boot는 Micrometer를 통해 지표를 수집하고, Prometheus 같은 수집 시스템으로 내보낼 수 있습니다.

꼭 봐야 할 지표

최소 구성

HTTP 요청 수, 응답 시간, 상태 코드 분포
커넥션 풀 사용량과 대기 수
JVM 힙 사용량과 GC 시간
스레드 수와 대기 상태

분산 추적

서비스가 여럿일 때

요청이 여러 서비스를 거치면 어디서 느려졌는지 로그만으로는 알기 어렵습니다. 추적 도구로 구간별 소요 시간을 확인합니다.

알림 기준

운영

임계값을 정하지 않으면 지표를 수집해도 아무도 보지 않습니다. 응답 시간과 오류율 기준을 먼저 정합니다.

배포 단위는 jar 하나 또는 이미지 하나입니다

빌드하면 실행 가능한 jar가 나옵니다. 서버에 JDK가 있으면 그대로 실행하고, 컨테이너 환경이면 이미지로 감싸 배포합니다.

이미지를 만들 때는 계층 구조를 활용하면 빌드와 배포가 빨라집니다. 의존성은 잘 바뀌지 않고 애플리케이션 코드만 자주 바뀌기 때문입니다.

설정 주입

Part 4 연계

이미지는 환경에 관계없이 동일하게 만들고, 환경별 값은 실행 시 환경변수로 주입합니다.

무중단 배포

readiness 활용

새 인스턴스가 준비 완료를 알린 뒤 트래픽을 받게 합니다. 헬스체크 설정과 배포 도구 설정이 맞아야 합니다.

종료 처리

graceful shutdown

처리 중인 요청을 마치고 종료하도록 설정합니다. 그렇지 않으면 배포할 때마다 일부 요청이 실패합니다.

CI/CD 연결

Jenkins 코스

빌드, 테스트, 이미지 생성, 배포를 파이프라인으로 묶습니다. 배포 stage에는 브랜치 제한과 승인 조건을 둡니다.

계층을 나눈 Dockerfiledockerfile

# 1단계: 빌드
FROM eclipse-temurin:17-jdk AS builder
WORKDIR /app
COPY . .
RUN ./gradlew clean bootJar -x test

# 2단계: 실행 (JRE만 포함해 이미지 크기를 줄입니다)
FROM eclipse-temurin:17-jre
WORKDIR /app
COPY --from=builder /app/build/libs/*.jar app.jar

# 컨테이너 메모리 한도를 JVM이 인식하게 합니다
ENTRYPOINT ["java", "-XX:MaxRAMPercentage=75.0", "-jar", "app.jar"]

컨테이너 메모리 한도를 지정하지 않으면 JVM이 호스트 전체 메모리를 기준으로 힙을 잡아 강제 종료될 수 있습니다. Docker 코스와 함께 보면 이해가 빠릅니다.

운영 전 최소 점검 항목

Actuator 노출 엔드포인트를 필요한 것만 열었다.
헬스체크가 liveness와 readiness로 구분돼 있다.
요청 식별자가 모든 로그에 남는다.
로그에 비밀번호·토큰·개인정보가 남지 않는다.
응답 시간, 오류율, 커넥션 풀 지표를 확인할 수 있다.
graceful shutdown이 설정돼 있다.
환경별 설정이 이미지가 아니라 실행 환경에서 주입된다.

버전

3.x와 4.x 차이

본문은 현장에서 가장 많이 쓰는 3.x 기준입니다. 4.x에서 달라진 부분만 아래에 정리합니다.

3.x와 4.x 모두 Actuator와 Micrometer 구성 방식은 같습니다.
4.1은 관측 기능이 강화됐고 OpenTelemetry 지원이 확대됐습니다. 분산 추적을 새로 도입한다면 4.x 기준 문서를 확인하는 편이 낫습니다.
4.1은 Log4j 파일 로테이션 지원과 gRPC 지원이 추가됐습니다. 해당 기술을 쓰는 조직이라면 업그레이드 이유가 될 수 있습니다.

체크