--- title: Runbook — DEPENDENCY_CIRCUIT_OPEN (서킷 브레이커 개방) category: TRANSIENT_DEPENDENCY error_codes: [DEPENDENCY_CIRCUIT_OPEN] severity: P2 owner: oncall last_updated: 2026-11-13 status: 초안 --- # Runbook: DEPENDENCY_CIRCUIT_OPEN (`runbook://dependency/circuit-open`) ## 증상 - HTTP 503, `error.code=DEPENDENCY_CIRCUIT_OPEN`. - 어떤 의존성의 circuit breaker(Resilience4j)가 OPEN 상태다. - 이 코드는 서비스 코드가 `DependencyFailureException`을 던질 때만 나온다. httpclient 예외는 코드를 싣지 않아 500 `INTERNAL_ERROR`다(`dependency-unavailable.md`). - ERROR 줄 `dependency failure classified as DEPENDENCY_CIRCUIT_OPEN (category=TRANSIENT_DEPENDENCY, retryable=true, dependency=<이름>)`(`ServerFailureLog`, 원인 사슬 포함). ## 진단 - 그 줄의 `dependency=`가 서비스가 붙인 업스트림 이름이다. httpclient capability를 켠 서비스는 `http.client.circuit.state`(tag `clientName`, 1 = open)와 `http.client.circuit.state.rejected`(열려 거부한 호출)를 본다. Resilience4j 자체 지표(`resilience4j_*`)는 묶지 않았다. - 업스트림 상태를 확인한다. 실패가 임계를 넘으면 circuit이 열린다. ## 조치 - circuit의 half-open 시험을 기다린다(대기 시간이 지나면 자동으로 한다). - 업스트림 문제를 풀어 circuit이 닫히게 한다. ## 에스컬레이션 - 중요한 의존성의 circuit이 5분 넘게 열려 있으면 P1. --- > **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다.