문제: 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개 모두 문서에 있음).
124 lines
7.7 KiB
Markdown
124 lines
7.7 KiB
Markdown
# 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이 살아 있다.
|
|
|
|
```text
|
|
새 세대 만들기 → 검증 → 원자적 교체 → 새 호출이 그것을 쓴다
|
|
옛 세대 → DRAINING → 진행 중인 호출이 끝난다 → 새 재시도 없음 → drain 기한에 강제로 닫는다
|
|
```
|
|
|
|
## 종료
|
|
|
|
```text
|
|
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
|
|
|
|
```text
|
|
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과 원격 오류 본문은 절대 속성으로 기록하지 않는다.
|