bluetape4k-dependencies 1.3.0 활용기 Part 3: 운영에서 드러나는 신호

운영에서 중요한 변경은 새로운 API보다 관측 가능한 신호입니다. 실패가 시작된 경계를 조기에 확인할 수 있어야 합니다.

2026-06-28 · bluetape4k-dependencies 1.3.0 활용기 Part 3

운영에서 가장 까다로운 문제는 즉시 실패하지 않는 문제입니다. 즉시 실패하면 경보와 스택 추적을 근거로 원인을 조사할 수 있습니다.

반면 요청은 성공했지만 내부 데이터가 어긋날 수 있습니다. 캐시 flush가 중단되거나 메트릭이 잘못된 이름으로 전송되거나 리더가 변경된 흔적을 찾기 어렵다면 장애 발견과 복구가 지연됩니다.

dependencies 1.3.0에서 운영자가 확인할 수 있는 변화는 다음 신호에 있습니다.

• exposed 1.11.0: 캐시 상태를 상태 점검 응답에 노출한다.
• aws 0.4.0: Ktor/Spring에서 CloudWatch 메트릭과 로그 경계를 정의한다.
• leader 0.4.0: 공급자·저장소 선택과 메트릭 확인 지점을 명확히 한다.

여기서는 새로운 기능 목록보다 확인할 값과 조기에 발견할 수 있는 실패 유형에 초점을 맞춥니다.

플러그인 설치만으로 운영 신호가 완성되지는 않습니다. 애플리케이션이 상태와 이벤트를 명시적으로 노출하고, 운영자가 검색·경보를 진단 순서와 복구 결정으로 연결해야 합니다.

Exposed 캐시: flush 중단을 상태 응답에서 확인한다

write-behind 캐시는 쓰기 지연을 줄이지만 백그라운드 flush 실패 위험을 수반합니다. flush 작업이 중단되어도 애플리케이션이 일정 시간 정상처럼 보일 수 있습니다.

exposed 1.11.0의 주요 변경 중 하나는 캐시 상태 표시기입니다. 다음 응답은 해당 릴리스의 JDBC 상태 표시기 구조를 반영합니다.

{
  "status": "OUT_OF_SERVICE",
  "components": {
    "exposedCache": {
      "status": "OUT_OF_SERVICE",
      "details": {
        "reports": [
          {
            "name": "invoice-cache",
            "mode": "WRITE_BEHIND",
            "queueDepth": 384,
            "flushJobRunning": false,
            "lastFlushError": "Redis connection failed"
          }
        ]
      }
    }
  }
}

여기서 중요한 값은 status 하나가 아닙니다.

값	왜 봐야 하나
mode	write-through인지 write-behind인지에 따라 장애 의미가 달라진다.
queueDepth	flush가 밀리고 있는지 확인한다.
flushJobRunning	뒤에서 실제 flush 작업이 돌고 있는지 확인한다.
lastFlushError	캐시 문제가 데이터베이스, Redis, 직렬화 중 어느 경계에 가까운지 단서를 제공한다.

이 값이 없으면 운영자는 애플리케이션 로그와 데이터베이스 상태를 함께 조사해야 합니다.

사용자는 방금 저장했다고 말한다
  -> API 로그에는 200 응답이 기록되었다
  -> DB에는 없다
  -> 캐시 대기열 깊이는 얼마인가?
  -> flush 작업은 실행 중인가?
  -> Redis 연결은 정상인가?

상태 응답에 캐시 정보가 포함되면 조사 시작점을 정할 수 있습니다. 상태 표시는 장애를 제거하지 않지만 캐시 대기열, flush 작업, Redis 연결 순서로 진단 범위를 좁혀 줍니다.

AWS CloudWatch/Logs: 검색 가능한 이름 규칙을 정의한다

CloudWatch 메트릭과 로그는 전송만으로 충분하지 않습니다. 네임스페이스, 로그 그룹, 스트림 이름이 일관되지 않으면 여러 환경과 서비스가 같은 AWS 계정을 사용할 때 검색과 경보 구성이 어려워집니다.

aws 0.4.0에서는 Ktor/Spring에서 CloudWatch와 CloudWatch Logs를 연동하는 경로를 보강했습니다. Ktor에서는 애플리케이션 시작 지점에 이름과 수명 주기 설정을 모을 수 있습니다.

다음 예제는 aws 0.4.0의 실제 플러그인 이름과 설정 속성을 사용합니다.

fun Application.module() {
    install(CloudWatchKtorPlugin) {
        namespace = "bluetape4k/billing"
    }

    install(CloudWatchLogsKtorPlugin) {
        logGroupName = "/bluetape4k/billing-api"
        logStreamName = "${deployment.environment}/${deployment.instanceId}"
        flushInterval = Duration.ofSeconds(5)
        shutdownFlushTimeout = Duration.ofSeconds(5)
    }
}

메트릭 차원은 플러그인 설치 설정이 아니라 게시할 MetricDatum에 명시합니다. 또한 플러그인 설치만으로 메트릭이나 로그가 자동 전송되지는 않습니다. 애플리케이션이 명시적으로 게시하거나 로그 이벤트를 버퍼에 추가해야 합니다.

Spring Boot에서도 애플리케이션이 소유하는 설정에 같은 이름 규칙을 명시할 수 있습니다. 다음 YAML은 라이브러리가 제공하는 자동 구성 속성이 아니라 애플리케이션의 이름 정책을 설명하는 예시입니다.

bluetape4k:
  aws:
    cloudwatch:
      namespace: bluetape4k/billing
      dimensions:
        service: billing-worker
        environment: prod
    cloudwatch-logs:
      log-group-name: /bluetape4k/billing-worker
      log-stream-name: prod/${HOSTNAME}

운영에서는 다음 이름을 일관되게 유지해야 합니다.

metric namespace: bluetape4k/billing
dimension.service: billing-worker
dimension.environment: prod
log group: /bluetape4k/billing-worker
log stream: prod/ip-10-0-12-34

일관된 이름은 경보와 대시보드 구성, 장애 후 로그 검색의 기준이 됩니다. CloudWatch 연동은 전송 코드뿐 아니라 운영자가 사용할 검색 키를 정의하는 경계입니다.

Leader: 공급자 선택에는 저장소와 런타임이 포함된다

leader 0.4.0에서 리더 공급자를 선택하는 일은 저장소와 런타임을 함께 선택하는 일입니다.

Redis 백엔드를 선택하면 Redis 장애 감지와 메트릭을 확인해야 합니다. Kubernetes Lease를 선택하면 Kubernetes 클라이언트 런타임이, DynamoDB를 선택하면 AWS 권한·테이블 용량·지연 시간이 함께 운영 경계에 들어옵니다.

리더 선출
  -> 공급자 선택
      -> 저장소 선택
          -> 클라이언트·런타임 선택
              -> 메트릭·로그·경보 선택

Kubernetes K3s 테스트 런타임 충돌도 이 경계에서 발생했습니다. Fabric8 Kubernetes 클라이언트가 요구하는 Vert.x 호환선과 테스트 런타임 클래스패스가 다르면 리더 선출 로직을 검증하기 전에 메서드 불일치가 발생할 수 있습니다.

운영에서는 공급자별로 확인할 값이 다릅니다.

공급자·저장소	우선 확인할 신호	장애 시 확인할 항목
Redis	잠금 갱신 지연 시간, Redis 연결 오류	Redis 장애 조치, 네트워크 분할, TTL 설정
SQL/Exposed	잠금 행 갱신 지연 시간, 트랜잭션 오류	데이터베이스 잠금 대기, 격리 수준, 커넥션 풀
Kubernetes Lease	lease 갱신 실패, API 서버 지연 시간	서비스 계정 권한, Fabric8·런타임 호환선
DynamoDB	조건부 쓰기 실패, 스로틀링	IAM, 용량, 리전, 테이블 키 설계

리더 선출의 운영 계약은 선택한 저장소에 따라 달라집니다. Redis 잠금, Kubernetes Lease 갱신, DynamoDB 조건부 쓰기는 서로 다른 장애 신호와 복구 절차를 가집니다.

메트릭 이름은 프로젝트마다 달라도 운영자가 확인할 질문은 유사합니다.

현재 리더는 누구인가?
마지막 갱신은 언제 성공했는가?
갱신 실패가 몇 번 연속 발생했는가?
리더 전환이 과도하게 자주 발생하는가?
백엔드 지연 시간이 평소보다 증가했는가?

리더 선출의 성공 여부와 리더 전환 원인을 설명할 수 있는지는 서로 다른 운영 요구사항입니다.

운영 점검표

dependencies 1.3.0으로 올린 뒤 운영 관점에서 확인할 항목을 간단히 정리하면 다음과 같습니다.

영역	확인할 질문
Exposed 캐시	/actuator/health에서 캐시 모드, 대기열 깊이, flush 상태를 확인할 수 있는가?
AWS 메트릭	네임스페이스와 차원 이름을 서비스·환경 기준으로 정리했는가?
AWS 로그	로그 그룹과 스트림 이름만으로 서비스와 인스턴스를 찾을 수 있는가?
Leader	공급자·저장소별 메트릭과 장애 신호를 구분하는가?
런타임 클래스패스	Kubernetes, Ktor, AWS SDK처럼 호환선에 민감한 의존성을 dependencyInsight로 확인했는가?

확인 명령은 상황에 맞게 좁혀서 쓰면 됩니다.

curl -s http://localhost:8080/actuator/health | jq '.components.exposedCache'

./gradlew dependencyInsight \
  --dependency vertx-web-client \
  --configuration k8sTestRuntimeClasspath

./gradlew dependencyInsight \
  --dependency software.amazon.awssdk \
  --configuration runtimeClasspath

마무리

queueDepth, flushJobRunning, 메트릭 네임스페이스, 공급자별 런타임 호환성을 관측할 수 있으면 장애 대응 시간을 줄일 수 있습니다.

dependencies 1.3.0의 운영상 가치는 결함을 제거하는 데만 있지 않습니다. 문제가 발생한 경계를 조기에 드러내고 조사 순서를 정할 수 있게 하는 데 있습니다.

시리즈 글

처음 bluetape4k-dependencies를 적용하는 방법부터 확인하려면 사용 가이드를 먼저 읽으면 됩니다.

• bluetape4k-dependencies 1.3.0 활용기 Part 1: 기능 보강과 경계 정리
• bluetape4k-dependencies 1.3.0 활용기 Part 2: 서비스 경계에 맞는 모듈 조합
• bluetape4k-dependencies 1.3.0 활용기 Part 3: 운영에서 드러나는 신호
• bluetape4k-dependencies 1.3.0 활용기 Part 4: 입력 경계와 자원 안전성

자료

• Exposed JDBC 캐시 상태 표시기 1.11.0
• CloudWatchKtorPluginConfig 0.4.0
• CloudWatchLogsKtorPluginConfig 0.4.0
• bluetape4k-leader CHANGELOG.md
• bluetape4k-leader issue #480