문제: docs/httpclient 아래 살아 있는 문서 9개가 영어였다(language 예외). repository-adaptation.md는 registry의 leaf 수를 「exactly 19 leaf identities」로, Spring Boot 버전을 4.0.8로 옮겨 적었다(number 예외 두 줄). 같은 문서가 testkit을 `testkit` source set이라고 했지만 1절 표와 실제 코드는 `testFixtures`다. 고친 방법: 뜻을 그대로 옮기고 식별자·명령·경로·설정 key·예외·metric·위반 코드·표 구조는 원문으로 둔다. scripts/verify-httpclient-docs.py가 코드에서 뽑는 이름이 모두 문서에 남는다. leaf 수는 registry(src/config/architecture/modules.json)를, 버전은 src/gradle/libs.versions.toml의 `springBoot`를 가리킨다. 등급 이름(Stable, Default, Restricted, Internal, Experimental)은 꼬리표라 원문으로 둔다. env-fields.yaml은 머리 주석만 옮겼다. HttpClientPlatformEnvManifestTest는 주석을 읽지 않는다(`- field:`·`env:` 줄만). configuration-reference.md의 「Three of these」 뒤 목록이 다섯이라 「아래 코드들」로 고쳤다. 버린 대안: 리뷰 번호(RR-03-14 등)를 걷어 내기. 이 작업은 번역이고 내용 감사는 다음 리뷰 몫이라 날짜와 함께 그대로 둔다. 위험·한계: 내용 감사는 하지 않았다. 검증: python3 scripts/check-docs.py rc=0(이 폴더 예외 줄 0). python3 scripts/verify-httpclient-docs.py PASS(코드에서 뽑은 이름 156개 모두 문서에 있음).
7.7 KiB
HTTP Client 플랫폼 — 운영 runbook
Metric
| Metric | 뜻 |
|---|---|
http.client.requests |
물리 시도 timer(Spring 표준 이름. 일부러 그대로 둔다) |
http.client.logical.calls |
사용자에게 보이는 논리 호출 timer |
http.client.attempts |
시도 counter |
http.client.retry.count |
이유별 재시도 |
http.client.retry.exhausted |
재시도 예산 소진 |
http.client.ambiguous |
결과를 모르는 경우 |
http.client.timeout |
단계별 시간 초과 |
http.client.request.bytes |
요청 wire 바이트 |
http.client.response.bytes |
응답 바이트 |
http.client.active |
진행 중인 시도 |
http.client.pool.connections |
빌려 간 connection과 남은 connection |
http.client.pool.pending |
pool 대기자 |
http.client.pool.acquire.duration |
pool 대기 시간 |
http.client.dns.duration |
DNS 시간 |
http.client.connect.duration |
연결 시간 |
http.client.tls.duration |
TLS 시간 |
http.client.circuit.state |
circuit 상태 |
http.client.bulkhead.rejected |
bulkhead 거부 |
http.client.rate_limit.rejected |
로컬 속도 제한 거부 |
http.client.oauth.refresh |
token 갱신 결과 |
http.client.ssrf.rejected |
dynamic target 거부 |
http.client.requests는 시도를 세고 http.client.logical.calls는 사용자 호출을 센다. 둘이 벌어지면 재시도가
실패를 흡수하고 있다는 뜻이다. 장애 때 가장 먼저 볼 곳이다.
장애 읽기
| 증상 | 그럴듯한 원인 | 볼 곳 |
|---|---|---|
| 논리 호출은 괜찮은데 시도가 치솟는다 | upstream이 나빠졌고 재시도가 흡수하고 있다 | 이유별 http.client.retry.count |
http.client.ambiguous가 0이 아니다 |
멱등이 아닌 쓰기가 SENT_NO_RESPONSE에 닿는다 |
upstream과 맞춰 본다. 멱등 key를 검토한다 |
| pool 대기가 오른다 | pool이 작거나 upstream이 느리다 | http.client.pool.acquire.duration, pool.connections |
| circuit이 열렸다 | 계속된 upstream 실패: transport 오류, 5xx, 408, 429 | http.client.circuit.state. 로컬 거부와 그 밖의 4xx는 circuit을 열지 않는다 |
http.client.ssrf.rejected가 0이 아니다 |
호출자가 내부 URL을 넣고 있다 | Dynamic Target 정책과 감사 기록 |
Actuator
GET /actuator/httpclients는 profile 이름, 런타임 세대, 상태, transport, API, protocol, 진행 중인 lease, pool
상한, credential 유형, TLS profile id, redirect flag, 재시도 정책, capability 경고를 보고한다. Base URL, credential,
trust store 경로, 푼 IP는 일부러 뺐다. actuator endpoint에는 secret 저장소보다 많은 사람이 닿는다.
교체
인증서와 secret은 살아 있는 client를 바꾸지 않고, 새 런타임 세대를 만들어 registry pointer를 바꿔 끼우는 식으로 교체한다. connection pool은 앞 신원으로 맺은 socket을 쥐고 있다. 그래서 pool은 그대로 두고 재료만 바꾸면, 없어져야 할 인증서로 인증한 connection이 살아 있다.
새 세대 만들기 → 검증 → 원자적 교체 → 새 호출이 그것을 쓴다
옛 세대 → DRAINING → 진행 중인 호출이 끝난다 → 새 재시도 없음 → drain 기한에 강제로 닫는다
종료
RUNNING → DRAINING
새 논리 호출을 거부하거나 새 세대로 보낸다
진행 중인 시도가 끝난다
새 재시도를 거부한다
종료 시간 초과
남은 호출을 취소한다
pool을 닫는다
재시도 소유
애플리케이션 client, 외부 SDK, service mesh 중 정확히 하나만 재시도를 가진다. 소유자가 둘이면 장애 중에 트래픽이 곱절로 는다. upstream마다 소유자를 적고, mesh 재시도 정책이 바뀔 때마다 확인한다.
오류 모델
모든 외부 호출 실패는 아래 안정된 타입 중 하나다. 타입은 엔진이 마침 던진 것이 아니라 분류한 실패 범주에서
정한다. 그래서 Apache와 JDK에서 같은 뜻이다. 모두 HttpFailureMetadata를 가진다: client, 연산, method, URI
template, 증거, 재전송 가능성, 단계, 재시도 가능 여부, 시도 번호, 흐른 시간, 남은 기한, 상태, trace id.
그 밖의 것은 없다.
| 예외 | 던지는 때 | 재시도 |
|---|---|---|
HttpConfigurationException |
profile, 연산, capability 설정이 잘못됐다 | 안 함 |
HttpTargetRejectedException |
대상 URI, host, port, 헤더, 주소 정책이 요청을 거부했다 | 안 함 |
HttpDnsException |
hostname 풀기가 실패하거나 시간이 넘었다 | 예산 안에서 함 |
HttpPoolAcquireTimeoutException |
대기 예산 안에 connection이나 stream을 얻지 못했다 | 예산 안에서 함 |
HttpConnectException |
socket 연결이 실패했다 | 예산 안에서 함 |
HttpProxyException |
proxy 연결, CONNECT tunnel, proxy 인증이 실패했다 | 예산 안에서 함 |
HttpTlsException |
TLS handshake가 실패했다 | 일시적인 handshake 시간 초과만 |
HttpRequestWriteException |
요청 헤더나 본문을 다 쓰지 못했다 | 안전하게 멱등일 때만 |
HttpResponseTimeoutException |
최종 헤더나 본문 chunk가 제때 오지 않았다 | 안전하게 멱등일 때만 |
HttpResponseTruncatedException |
본문이 끝나기 전에 응답이 끝났다 | 안전하게 멱등이고 아직 넘기지 않았을 때만 |
HttpRemoteErrorException |
problem document 없는 실패 상태 | 상태 규칙대로 |
HttpProblemDetailException |
크기가 제한된 RFC 9457 document가 있는 실패 상태 | 상태 규칙대로 |
HttpRedirectRejectedException |
hop이 hop 수, origin, method, 재전송 정책을 어겼다 | 안 함 |
HttpAuthenticationException |
credential 만들기나 갱신이 실패했다 | 안 함 |
HttpSerializationException |
요청 인코딩이나 응답 디코딩이 실패했다 | 안 함 |
HttpResponseTooLargeException |
wire나 디코딩한 바이트가 profile 한도를 넘었다 | 안 함 |
HttpDeadlineExceededException |
실제 기한에 닿았다 | 안 함 |
HttpCircuitOpenException |
upstream circuit이 열렸다 | 안 함 |
HttpBulkheadRejectedException |
시도나 논리 허가를 얻지 못했다 | 안 함 |
HttpRateLimitRejectedException |
로컬 시도 속도 제한이 시도를 거부했다 | 안 함 |
HttpRetryBudgetExhaustedException |
upstream별 재시도 예산이 다음 시도를 거부했다 | 안 함 |
HttpRuntimeDrainingException |
허락한 재시도가 시작되기 전에 profile 런타임이 내려갔다(인증서 교체) | 안 함 — 새 호출은 바뀐 런타임에서 돈다 |
HttpUnknownTransportException |
위 범주 어느 것도 설명하지 못하는 방식으로 엔진이 실패했다. 보냈는지는 타입이 아니라 metadata의 증거가 말한다 | 안 함 |
HttpAmbiguousExecutionException |
멱등이 아닌 요청을 보냈고 결과를 모른다 | 안 함 — 대신 맞춰 본다 |
이 예외들이 감싸져서 오는 곳은 하나다. 넘긴 뒤 실패한 스트리밍 본문이다. read가 HttpBodyReadException을
던진다. InputStream이 약속한 대로 IOException이고, 그 failure()가 위의 HttpResponseTimeoutException이나
HttpResponseTruncatedException이다(재리뷰 2026-11-04 RR-03-14).
Trace
http.client.operation 논리 호출의 내부 span
└─ http.client.request 시도 1의 CLIENT span
└─ http.client.request 시도 2의 CLIENT span
W3C Trace Context를 Baggage 허용 목록과 함께 전파한다. Dynamic Target은 기본으로 trace context를 전파하지 않는다. 재시도 이유와 증거는 span event로 기록한다. credential과 원격 오류 본문은 절대 속성으로 기록하지 않는다.