--- title: Runbook — 외부 의존성 unavailable category: TRANSIENT_DEPENDENCY error_codes: [DEPENDENCY_TIMEOUT, DEPENDENCY_CONNECT_FAILED, DEPENDENCY_DNS_FAILED, DEPENDENCY_CIRCUIT_OPEN, DEPENDENCY_5XX_SERVER, DB_UNAVAILABLE] severity: P1 owner: oncall last_updated: 2026-11-13 status: 초안 --- # Runbook: 외부 의존성 unavailable ## 증상 - DB: 503 `DB_UNAVAILABLE`과 ERROR 줄 `persistence failure classified as DB_UNAVAILABLE (category=TRANSIENT_DEPENDENCY, retryable=true)`(`ServerFailureLog`, 원인 사슬은 붙지 않는다). - outbound HTTP: 지금 httpclient 예외는 코드를 싣지 않아 500 `INTERNAL_ERROR`와 ERROR 줄 `unhandled exception on …`이 된다. registry의 `DEPENDENCY_*` 코드는 `DependencyFailureException`을 던지는 서비스 코드에서만 나오고, ERROR 줄 `dependency failure classified as DEPENDENCY_… (category=TRANSIENT_DEPENDENCY, retryable=…, dependency=<이름>)`을 남긴다. - Redis: `CACHE_UNAVAILABLE` 코드는 없다. cache 읽기가 실패하면 원천에서 읽고 HTTP 오류는 없다. WARN 줄 `Redis semantic operation degraded; capability=… operation=… failureType=…`(`RedisSemanticFailureLogger`)이 남는다. cache만이 아니라 idempotency·rate-limit·lease도 같은 줄을 낸다. 같은 capability·operation·failureType은 1분에 한 번만 WARN이고 나머지는 DEBUG라, 경보는 건수가 아니라 그 줄이 나왔는지로 건다. - 이 템플릿은 경보 규칙·대시보드를 두지 않는다. 서비스가 위 줄의 고정 문구(`persistence failure classified as`, `dependency failure classified as`, `unhandled exception on`, `Redis semantic operation degraded`)와 `http.server.requests`(tag `status`, `uri`)로 만든다. 업스트림 이름은 `dependency=` 값뿐이다. 위 줄들에는 `dependency_name` 칸이 없다. ## 진단 - outbound HTTP 지표(httpclient capability를 켠 서비스): `http.client.requests`(tag `clientName`, `outcome`=`success`|`failure`), `http.client.retry.count`, `http.client.retry.exhausted`, `http.client.circuit.state`(1=open), `http.client.circuit.state.rejected`(`docs/registries/metrics.yaml`). Resilience4j 자체 지표(`resilience4j_*`)는 묶지 않았다. - DB 풀: `hikaricp.connections.active`·`hikaricp.connections.pending`·`hikaricp.connections.timeout`(persistence-jpa를 켠 서비스). - readiness는 DB와 required Redis만 본다. outbound HTTP 의존은 readiness에 들지 않는다. ## 조치 - DB·required Redis 장애면 readiness가 트래픽을 뺀다. 회복을 기다린다. - outbound 의존 장애면 그 클라이언트의 timeout·retry·circuit 설정(`docs/httpclient/`)을 본다. circuit을 손으로 되돌리는 actuator는 없다(`circuitbreakerevents`는 노출하지 않는다). - 풀이 고갈되면 풀 크기와 오래 쥔 트랜잭션을 본다. ## 에스컬레이션 - required 의존이 5분 안에 돌아오지 않으면 그 의존의 담당이나 vendor에 넘긴다. --- > **Stub 상태 안내**: 이 runbook은 skeleton 단계의 stub. 도메인 도입 시 실제 dependency 목록·required/optional 분류·vendor 연락 체계·circuit/timeout 임계로 보강 필요.