Files
clean-architecture-backend-…/docs/httpclient/operations.md
T
DongHyeonka 354b7fc959
pr / done (pull_request) Canceled after 0s
fix(observability)!: 지표·MDC·헤더 registry를 코드가 실제로 내는 것과 맞춘다
관측 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행.
2026-11-13 13:12:27 +09:00

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과 원격 오류 본문은 절대 속성으로 기록하지 않는다.