관측 registry가 코드와 양쪽으로 어긋난다. metrics.yaml에는 아무 코드도 등록하지 않는 행 열하나와 코드에 없는 tag 값이 있고, 코드가 등록하는 graphql·notification·http.client·fileserver·mongodb·jpa.query 지표 다수가 없다. mdc-keys.yaml은 18키 중 코드가 넣는 5키만 맞고 required_in이 틀렸다. headers.yaml은 X-Request-Id·X-Correlation-Id를 ulid로 적고 아무도 쓰지 않는 Deprecation·Sunset·tracestate를 적는다. 전송마다 correlation 규칙이 다른데 registry는 하나로 적는다. 단일 인스턴스 in-process lock은 lock.acquisition을 세지 않아 그 지표가 0이다. 밑줄 든 meter 이름 둘이 이름 규칙을 어긴다. - 행마다 등록하는 main 파일(source)·상수(constant)·등록 주체 (registered_by)를 적고, MetricsRegistryCodeAlignmentTest가 행 → 코드(이름이 상수면 그 상수를 쓰는 곳까지)와 코드(글자·상수 이름의 builder·registry· Metrics 호출) → 행 두 방향을 본다. 템플릿이 부르지 않는 공개 메서드로만 생기는 job.* 행은 emitted_when을 적는다. 버린 안: 행만 지우기(새 지표가 다시 빠진다). - mdc-keys는 5키와 전송별 표, headers는 source가 든 33행(서비스 controller용 상수는 service: 출처), StructuredLog·HeaderRegistry 시험이 코드 상수와 집합을 대조한다. 두 registry 시험은 시험 도우미 MainSources를 같이 쓴다. - slo_driven 행은 MetricsDistributionMeterFilter 대상과 같은 집합이다(두 방향 시험). histogram을 켜지 않는 hikaricp timer 행은 평균으로 경보한다. graphql.datafetcher·dataloader 행에 Spring 기본 tag를 적는다. - in-process lock을 MeteredDistributedLock으로 감싼다. - http.client.ratelimit.rejected, fileserver.upload.offset.mismatch로 이름을 바꾸고 http.client.circuit.state.rejected를 상수로 둔다. - CardinalityBounds(status 40·outcome 6·uri), MetricNaming 단위 규칙, SLO filter 대상(http.server.requests·jvm.gc.pause)을 문서와 맞춘다. 위험: 지표 이름 둘이 바뀌고 단일 인스턴스 lock 지표가 생긴다. 그 이름으로 만든 대시보드·경보를 옮겨야 한다(docs/upgrade/2026-11-round9-observability.md 8~13행). ApachePoolMetricsBinder·MongoTransactionRetry 지연은 다른 묶음이 맡는다. 검증: 위와 같은 desktop 실행(묶음 셋을 합친 트리) rc=0. Refs: RR9-02-05, RR9-02-07, RR9-02-08, RR9-02-27, RR9-03-05 BREAKING CHANGE: http.client.rate_limit.rejected → http.client.ratelimit.rejected, fileserver.upload.offset_mismatch → fileserver.upload.offset.mismatch, CardinalityBounds 상수. docs/upgrade/2026-11-round9-observability.md 8~13행.
8.3 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.pool.connections |
빌려 간 connection과 남은 connection |
http.client.pool.pending |
pool 대기자 |
http.client.circuit.state |
circuit 상태(1 = open) |
http.client.circuit.state.rejected |
circuit이 열려 거부한 호출 |
http.client.bulkhead.rejected |
bulkhead 거부 |
http.client.ratelimit.rejected |
로컬 속도 제한 거부 |
http.client.ssrf.rejected |
dynamic target 거부 |
이름은 정했지만 아직 아무 코드도 내지 않는 metric이다(HttpClientObservationNames 상수, DeclaredMetricsAreEmittedTest의
「아직 안 냄」 목록). 대시보드·경보에 쓰지 않는다. docs/registries/metrics.yaml에도 행이 없다.
| Metric | 내려면 필요한 것 |
|---|---|
http.client.active |
논리 호출 observation 수명에 묶인 진행 중 gauge |
http.client.pool.acquire.duration |
engine마다 요청 단계 시간 |
http.client.dns.duration |
engine마다 요청 단계 시간 |
http.client.connect.duration |
engine마다 요청 단계 시간 |
http.client.tls.duration |
engine마다 요청 단계 시간 |
http.client.oauth.refresh |
token loader가 MeterRegistry를 받는 것 |
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.pending, pool.connections |
| circuit이 열렸다 | 계속된 upstream 실패: transport 오류, 5xx, 408, 429 | http.client.circuit.state, http.client.circuit.state.rejected. 로컬 거부와 그 밖의 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과 원격 오류 본문은 절대 속성으로 기록하지 않는다.