pr / done (pull_request) Canceled after 0s
관측 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행.
131 lines
8.3 KiB
Markdown
131 lines
8.3 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.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이 살아 있다.
|
|
|
|
```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과 원격 오류 본문은 절대 속성으로 기록하지 않는다.
|