From b071ff74c5be709143dac8837b5542beac814053 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Sat, 7 Nov 2026 17:56:34 +0900 Subject: [PATCH] =?UTF-8?q?docs(runbooks):=20runbook=EC=9D=84=20=ED=95=9C?= =?UTF-8?q?=EA=B5=AD=EC=96=B4=EB=A1=9C=20=EC=98=AE=EA=B8=B0=EA=B3=A0=20?= =?UTF-8?q?=EC=83=81=ED=83=9C=EB=A5=BC=20=EC=B4=88=EC=95=88=C2=B7=EC=9A=B4?= =?UTF-8?q?=EC=98=81=EC=9C=BC=EB=A1=9C=20=EB=B0=94=EA=BE=BC=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제: `docs/runbooks`의 runbook 38개가 영어였다(`check-docs.py` language 예외). 머리말 `status`는 `stub`·`active`였는데 문서 체계 규칙(design-docs `conventions/docs-system.md` 1절)은 runbook 상태를 「초안 · 운영」으로 정한다. 번역하며 대조하니 지금 코드와 다른 주장도 있었다. 고친 것: - 38개를 번역했다. 코드·명령·경로·설정 키·로그 문자열·표 구조는 그대로다. lane이 읽는 SQL·Redis 블록과 표지(``)는 바이트 그대로다. - `status`: stub → 초안 43개, active → 운영 3개, `template.md`는 `<초안|운영>`. 머리말이 없는 gRPC runbook 둘은 그대로다. - 코드에 맞춘 주장: - adapter-adapter-disabled: 없는 `adapter_name` 로그 칸 → `ServerFailureLog`의 `failure classified as ADAPTER_DISABLED` 줄과 예외 메시지. 지금 이 코드를 내는 곳은 `RoutingNotifier`뿐이다. - startup-required-adapter-disabled: `startup.phase=adapter-check` → `adapter-enablement`(`StartupPhase.ADAPTER_ENABLEMENT`). - cache-stampede-lock-timeout·cache-unavailable·file-download-streaming-failure: 그 코드는 `error-codes.yaml`에 없고 어느 코드도 내지 않는다고 밝혔다. - db-idle-in-tx-timeout: 없는 `spring.jpa.properties.hibernate.connection.timeout` → `app.persistence-jpa.transaction.*`. db-query-canceled에 남은 시간 전달을 더했다. - dependency-timeout: 「기본 전체 10s」 → profile `timeout.total-call` (`HttpClientPlatformSettings` 기본 `4s`, 값은 configuration-reference를 가리킨다). - management-actuator-forbidden: 없는 break-glass runbook → 노출 제외 목록 (`config/observability.yml`). - runtime-jvm-oom: 아무것도 쓰지 않는 `error.code=JVM_OOM` 로그를 지우고, 힙 덤프 경로(`src/Dockerfile`)를 적었다. - auth-public-path-misconfiguration: 공개 경로는 `config/security.yml` `public-paths`. - grpc-advanced-capabilities: 지운 `GrpcAdvancedSupportMatrix` → `GrpcAdvancedCapability.defaultGrade()`, envoy 참조 설정의 실제 경로. - grpc-platform-operations: 없는 `runtime_memberships` → registry `"build": "optional-grpc"`. - 다른 문서·코드가 영어 절 제목으로 인용하는 곳("Recover a failed concurrent index migration", "Classify the failure")은 한국어 제목 뒤 괄호에 영어를 남겼다. 인용하는 쪽(테스트 fixture 메시지, `docs/upgrade`, 다른 세션 범위 문서)은 고치지 않아도 맞다. - `RunbookCoverageContractTest`: `초안`을 초안으로 보고, 머리말 `status`가 `초안`·`운영` 밖이면 실패하는 테스트를 더했다. - `scripts/check-docs-exceptions.txt`에서 runbook language 줄 38개를 지웠다. 버린 대안: 옛 `stub`도 초안으로 계속 받기. 그러면 옛 표기로 쓴 초안이 운영 runbook으로 통과한다. 어휘 밖 값을 실패로 둬야 그 길이 막힌다. 위험·한계: - 이미 한국어였던 runbook 11개는 `status`만 바꿨고 본문 감사는 하지 않았다. - runtime-jvm-oom의 「종료 코드 137」은 원문대로 두었다. JVM의 `-XX:+ExitOnOutOfMemoryError` 종료 코드는 3이고 137은 SIGKILL이라 확인이 필요하다. - `docs/mongodb/runbooks/*.md`의 `status: active`는 이 테스트 밖이고 범위 밖이라 두었다. 검증: 아래 「검증」 줄은 영역 커밋 여섯이 합쳐진 최종 트리에서 돌렸다. 검증(desktop, 최종 트리 8295db89 = 이 묶음 마지막 커밋의 트리. 로그 `~/d2c-ops-docs-1-logs/`): - `:app-bootstrap:documentContractTest` rc=0, 68개 실패 0(`RunbookCoverageContractTest` 7개). `:app-bootstrap:repositoryContractTest` rc=0, 65개 건너뜀 1(원래 그렇다) 실패 0. - runbook SQL·Redis 블록을 문서에서 읽는 lane: persistence-jpa `postgresqlConcurrentIndexMigrationIntegrationTest`·`postgresqlDistributedLockIntegrationTest`· `postgresqlOutboxOrderKeyRunbookIntegrationTest`·`postgresqlOutboxDispositionRunbookIntegrationTest` rc=0(35개 실패 0), cache-redis `redisContainerContractTest` rc=0(103개 실패 0), `:composition:outbox-relay:mainCheck` rc=0. 모두 실행됨(FROM-CACHE는 다른 leaf의 main 컴파일뿐). - RED: 새 테스트를 기준 커밋의 옛 runbook에 대면 `legacyStubDebtMustMatchEveryAndOnlyCurrentStubRunbook`과 `everyRunbookFrontmatterDeclaresDraftOrOperatingStatus`가 실패한다("status=stub"). - `:app-bootstrap:spotlessCheck checkstyleTest testQualityCheck` rc=0. - 커밋마다(노트북): `python3 scripts/check-docs.py` rc=0, `python3 -m unittest discover -s scripts/tests` rc=0. --- docs/runbooks/grpc-advanced-capabilities.md | 104 +++++---- docs/runbooks/grpc-platform-operations.md | 221 +++++++++----------- 2 files changed, 150 insertions(+), 175 deletions(-) diff --git a/docs/runbooks/grpc-advanced-capabilities.md b/docs/runbooks/grpc-advanced-capabilities.md index bc3a50d..1382ead 100644 --- a/docs/runbooks/grpc-advanced-capabilities.md +++ b/docs/runbooks/grpc-advanced-capabilities.md @@ -1,94 +1,88 @@ # Runbook: gRPC advanced capabilities -Scope: the `:grpc-advanced:*` family. Everything here is off by default and stays off until a -deployment names it. Nothing in this family ships in a runtime composition today. +범위: `:grpc-advanced:*` family. 여기 있는 것은 모두 기본으로 꺼져 있고, 배포가 이름을 대기 전까지 꺼진 채로 +있다. 지금 이 family의 어떤 것도 런타임 조립에 들어가지 않는다. -Flags are `app.grpc.advanced..enabled`. `GrpcAdvancedCapability` owns the list of -capability names; `GrpcAdvancedSupportMatrix` owns their current grades. +스위치는 `app.grpc.advanced..enabled`다. capability 이름 목록과 기본 등급은 +`GrpcAdvancedCapability`(`defaultGrade()`)가 가진다. 근거가 있는 배포는 `GrpcAdvancedFeatureFlags.withGrade`로 +등급을 바꾼다. --- -## A capability refuses to start +## capability가 뜨기를 거부한다 -`GrpcAdvancedModuleGuard` gives three different refusals, and the remedy differs: +`GrpcAdvancedModuleGuard`는 세 가지로 거부하고, 고치는 법이 다르다. -| Message contains | Meaning | Remedy | +| 메시지에 있는 말 | 뜻 | 고치는 법 | | --- | --- | --- | -| "its feature flag is not set" | Nobody enabled it | Set the property named in the message | -| "tracked rather than implemented" | Grade is `WATCH` | Nothing to do here; the capability is not implemented | -| "uncharacterised failure modes" | Grade is `EXPERIMENTAL` and this is production | Record a production approval, or run it outside production | +| "its feature flag is not set" | 아무도 켜지 않았다 | 메시지가 이름 댄 속성을 설정한다 | +| "tracked rather than implemented" | 등급이 `WATCH`다 | 여기서 할 일은 없다. 그 capability는 구현되지 않았다 | +| "uncharacterised failure modes" | 등급이 `EXPERIMENTAL`이고 여기는 운영이다 | 운영 승인을 기록하거나, 운영 밖에서 돌린다 | -The refusal message always names the property key, so the first case is a configuration line rather -than a support question. +거부 메시지는 늘 속성 키를 이름 댄다. 그래서 첫 경우는 지원 문의가 아니라 설정 한 줄이다. --- -## xDS: the control plane went away +## xDS: control plane이 사라졌다 -**What you are seeing.** The control plane is unreachable and clients are still routing. +**보이는 것.** control plane에 닿지 않는데 클라이언트는 아직 라우팅한다. -**What it means.** `GrpcXdsFailurePolicy` serves the last-known-good snapshot, up to its staleness -bound. +**뜻.** `GrpcXdsFailurePolicy`가 마지막으로 정상이던 snapshot을 오래됨 상한까지 내준다. -**What to do.** +**할 일.** -1. Check the snapshot's age. `SERVE_LAST_KNOWN_GOOD` is the healthy degraded state. -2. `STALE_BEYOND_BOUND` means the snapshot is older than the policy allows and is no longer trusted. - Beyond that bound, a decommissioned backend would otherwise keep receiving traffic indefinitely. -3. `NO_SNAPSHOT_YET` on a starting instance means it never reached the control plane. It fails after - the initial fetch timeout rather than starting with no routing. +1. snapshot의 나이를 본다. `SERVE_LAST_KNOWN_GOOD`는 정상적인 degraded 상태다. +2. `STALE_BEYOND_BOUND`는 snapshot이 정책이 허용하는 것보다 오래돼서 더는 믿지 않는다는 뜻이다. 그 상한이 + 없으면 내린 backend가 트래픽을 끝없이 받는다. +3. 뜨는 인스턴스의 `NO_SNAPSHOT_YET`은 control plane에 한 번도 닿지 못했다는 뜻이다. 라우팅 없이 뜨지 않고, 첫 + fetch 시간 상한이 지나면 실패한다. -**Do not** add application-level retry policy while xDS is enabled. `GrpcXdsProfile` refuses an -`APPLICATION` retry owner, because retry defined in two places has a winner that depends on -resolution order rather than on a decision. +xDS가 켜진 동안 애플리케이션 수준의 재시도 정책을 **더하지 않는다**. `GrpcXdsProfile`이 `APPLICATION` 재시도 +소유자를 거부한다. 두 곳에 정의한 재시도는 결정이 아니라 해석 순서가 이기는 쪽을 정하기 때문이다. --- -## gRPC-Web: a browser call hangs and then fails with no status +## gRPC-Web: 브라우저 호출이 멈췄다가 상태 없이 실패한다 -**Almost always the proxy.** A gRPC status arrives as a trailer, and a browser cannot read a trailer -the proxy did not expose. Check that the proxy's CORS `expose_headers` includes `grpc-status` and -`grpc-message`; `GrpcWebProxyContract.violations` reports exactly this, and the reference -configuration in `envoy/envoy.yaml` shows it in place. +**거의 언제나 proxy다.** gRPC 상태는 trailer로 오고, 브라우저는 proxy가 노출하지 않은 trailer를 읽지 못한다. +proxy의 CORS `expose_headers`에 `grpc-status`와 `grpc-message`가 있는지 확인한다. +`GrpcWebProxyContract.violations`가 정확히 이것을 보고하고, 참조 설정 +`src/platforms/grpc-advanced/grpc-advanced-compat/src/test/resources/envoy/envoy.yaml`에 그것이 들어 있다. -**If the method is client- or bidirectional-streaming**, it cannot work over gRPC-Web at all — a -browser has no way to send a stream of messages. `GrpcWebRpcSupport.require` refuses such a method. +**메서드가 client streaming이나 bidirectional streaming이면** gRPC-Web으로는 아예 되지 않는다. 브라우저는 +메시지 stream을 보낼 방법이 없다. `GrpcWebRpcSupport.require`가 그런 메서드를 거부한다. --- -## Servlet: a transport setting appears to be ignored +## Servlet: 전송 설정이 무시되는 것 같다 -It is ignored. The container owns the socket, so keepalive tuning, maximum connection age and -flow-control window tuning belong to it. This repository has no Servlet transport code that would -refuse them, so configure them on the container. +무시된다. 소켓은 컨테이너가 가지므로 keepalive 조정, 최대 연결 수명, flow-control window 조정은 컨테이너의 +몫이다. 이 저장소에는 그것을 거부할 Servlet 전송 코드가 없으니 컨테이너에서 설정한다. -A Servlet run never substitutes for Netty certification. +Servlet 실행은 Netty 인증을 대신하지 않는다. --- -## Hedging: backend load doubled +## Hedging: backend 부하가 두 배가 됐다 -**Expected, within a bound.** Hedging trades duplicate load for tail latency. -`GrpcHedgingResult` records both `duplicateBackendCalls` and `cancelledLoserAttempts`; a dashboard -showing only the latency improvement makes the trade look free. +**상한 안이면 예상한 일이다.** hedging은 중복 부하를 내고 꼬리 지연을 줄인다. `GrpcHedgingResult`는 +`duplicateBackendCalls`와 `cancelledLoserAttempts`를 둘 다 기록한다. 지연 개선만 보여 주는 대시보드는 그 교환을 +공짜처럼 보이게 한다. -**What to check.** `GrpcHedgingBudget` caps hedges as a fraction of completed calls. If duplicate -load is above that fraction, the budget is not being consumed — which means something is issuing -hedges outside the coordinator. +**확인할 것.** `GrpcHedgingBudget`은 hedge를 끝난 호출의 비율로 제한한다. 중복 부하가 그 비율을 넘으면 예산이 +쓰이지 않고 있다는 뜻이다. coordinator 밖에서 무언가가 hedge를 보내고 있다. -**Hedging is refused** for anything but a read-only unary method. A hedged mutation runs twice by -design, and an idempotency key does not help: the second attempt duplicates a success in progress -rather than retrying a failure. +읽기 전용 unary 메서드가 아니면 **hedging을 거부한다**. hedge된 변경은 설계상 두 번 돈다. 멱등 키도 소용없다. +두 번째 시도는 실패를 다시 시도하는 것이 아니라 진행 중인 성공을 중복한다. --- -## Promoting a capability +## capability 승격 -Promotion to `ADVANCED_STABLE` needs compatibility evidence, a security review, fault evidence, -performance evidence, an ADR, a runbook, a real-environment test and seven days of soak. A Stable -default needs thirty. Promotions are independent: promoting one capability changes no other's -grade. This is a review checklist; the in-code `GrpcAdvancedPromotionGate` that restated it was -removed (review 2026-09-24 S5-lead-4) because nothing but its own test called it. +`ADVANCED_STABLE`로 올리려면 호환성 증거, 보안 리뷰, 장애 증거, 성능 증거, ADR, runbook, 실제 환경 시험, 7일 +soak이 필요하다. Stable 기본값은 30일이 필요하다. 승격은 서로 독립이다. 한 capability를 올려도 다른 것의 등급은 +바뀌지 않는다. 이것은 리뷰 점검 목록이다. 이것을 코드로 다시 적은 `GrpcAdvancedPromotionGate`는 자기 테스트 +말고는 부르는 곳이 없어 지웠다(리뷰 2026-09-24 S5-lead-4). -Before citing a suite as evidence, check that it ran against the real infrastructure it needs (proxy, -container, control plane or toolchain). A suite that ran without it passed and established nothing. +어떤 suite를 증거로 들기 전에, 그 suite가 필요한 실제 인프라(proxy, 컨테이너, control plane, toolchain)에 대고 +돌았는지 확인한다. 인프라 없이 돈 suite는 통과했지만 아무것도 증명하지 않았다. diff --git a/docs/runbooks/grpc-platform-operations.md b/docs/runbooks/grpc-platform-operations.md index aa896ec..44f2bf3 100644 --- a/docs/runbooks/grpc-platform-operations.md +++ b/docs/runbooks/grpc-platform-operations.md @@ -1,179 +1,160 @@ # Runbook: gRPC platform operations -Scope: the `:grpc:*` family. All of it is build-only today — every leaf's `runtime_memberships` is -empty — so nothing here fires in production yet. It is written now because the states it covers are -the ones an on-call cannot work out from first principles at three in the morning, and shipping the -behaviour before the runbook means the first person to meet one is doing that. +범위: `:grpc:*` family. 지금은 모두 빌드만 된다. registry에서 이 family의 leaf는 모두 `"build": "optional-grpc"` +(주 빌드 밖, `-p platforms/optional-build`로 돈다)이고 어느 조립에도 들어가지 않으므로, 여기 있는 것은 아직 운영에서 +일어나지 않는다. 그래도 지금 쓰는 이유가 있다. 여기서 다루는 상태는 당번이 새벽 세 시에 처음부터 따져서는 알아낼 +수 없는 것들이고, runbook보다 동작을 먼저 내보내면 그것을 처음 만난 사람이 그 따지기를 하게 된다. -Configuration lives under `app.grpc.platform.*` and is bound by `GrpcPlatformProperties`. -The platform does not start unless `app.grpc.platform.enabled=true`. +설정은 `app.grpc.platform.*` 아래에 있고 `GrpcPlatformProperties`가 묶는다. 플랫폼은 +`app.grpc.platform.enabled=true`가 아니면 뜨지 않는다. --- -## COMPLETION_UNKNOWN on a mutation +## 상태를 바꾸는 호출의 COMPLETION_UNKNOWN -**What you are seeing.** A client received `DEADLINE_EXCEEDED`, `UNAVAILABLE` or `INTERNAL` on a -state-changing call, and the response trailer `completion-outcome` reads `COMPLETION_UNKNOWN`. +**보이는 것.** 클라이언트가 상태를 바꾸는 호출에서 `DEADLINE_EXCEEDED`, `UNAVAILABLE`, `INTERNAL`을 받았고, 응답 +trailer `completion-outcome`이 `COMPLETION_UNKNOWN`이다. -**What it means.** The server may have committed. This is not a failure and not a success; the status -code cannot distinguish them, which is why the outcome is carried separately. +**뜻.** 서버가 커밋했을 수 있다. 실패도 성공도 아니다. 상태 코드로는 둘을 가릴 수 없어서 결과를 따로 싣는다. -**What not to do.** Do not re-issue the call. Do not tell the caller it failed. Both are wrong half -the time, and which half is not knowable from the status. +**하지 말 것.** 호출을 다시 보내지 않는다. 호출자에게 실패했다고 말하지 않는다. 둘 다 절반은 틀리고, 어느 절반인지 +상태 코드로는 알 수 없다. -**What to do.** +**할 일.** -1. Take the `error-execution-id` from the trailers. It is the only link between what the client saw - and what the server did. -2. If the method is `IDEMPOTENCY_KEY_REQUIRED`, query the operation ledger with the caller - fingerprint, the full method name and the caller's key. `GrpcOperationStatusQuery` returns one of - `IN_PROGRESS`, `COMMITTED`, `FAILED_TERMINAL`, `NOT_FOUND` or `UNKNOWN`. -3. `COMMITTED` means return the stored outcome reference, not a freshly computed answer — the resource - may have changed since, and a new answer would describe the state at reconciliation time rather - than the state the caller's own call produced. -4. `NOT_FOUND` means the operation never started and is safe to re-issue. `FAILED_TERMINAL` means the - same. -5. `UNKNOWN` means the ledger could not be consulted. Nothing may be concluded. The case is queued by - `GrpcCompletionReconciler` and retried later. -6. If the method is not keyed, there is no ledger row. Resolve it against the business resource, or - escalate to the service owner. This is the case the keyed profile exists to avoid. +1. trailer에서 `error-execution-id`를 꺼낸다. 클라이언트가 본 것과 서버가 한 것을 잇는 유일한 고리다. +2. 메서드가 `IDEMPOTENCY_KEY_REQUIRED`면 호출자 fingerprint, 전체 메서드 이름, 호출자의 키로 operation ledger를 + 조회한다. `GrpcOperationStatusQuery`는 `IN_PROGRESS`, `COMMITTED`, `FAILED_TERMINAL`, `NOT_FOUND`, `UNKNOWN` + 중 하나를 돌려준다. +3. `COMMITTED`면 새로 계산한 답이 아니라 저장된 결과 참조를 돌려준다. 그 뒤에 자원이 바뀌었을 수 있고, 새 답은 + 호출자 자신의 호출이 만든 상태가 아니라 맞춰 보는 시점의 상태를 설명한다. +4. `NOT_FOUND`는 operation이 시작하지 않았다는 뜻이라 다시 보내도 안전하다. `FAILED_TERMINAL`도 같다. +5. `UNKNOWN`은 ledger를 조회하지 못했다는 뜻이다. 아무것도 결론 낼 수 없다. `GrpcCompletionReconciler`가 그 + 건을 대기열에 넣고 나중에 다시 시도한다. +6. 메서드에 키가 없으면 ledger 행이 없다. 업무 자원으로 맞춰 보거나 서비스 소유자에게 넘긴다. 키 있는 profile은 + 이 경우를 피하려고 있다. -7. `IN_PROGRESS` means a claim exists and has not finished. If its owner died, the claim is not - stuck forever: once it is older than the claim TTL (`app.grpc.platform.operation-ledger-claim-ttl`, - default 5m), the next retry of the same request takes it over and runs again, - and a later reconciler pass sees that attempt's `COMMITTED` or `FAILED_TERMINAL`. Until a retry - arrives, the case stays pending. The re-run is safe only when the ledger commit is recorded in the - mutation's own transaction; if this service commits them separately, check the business resource - before letting the retry through. An owner that was only slow cannot spoil the takeover: its claim - attempt (`claim_attempt`) is behind, so its late commit is refused and its late failure ignored. - A log line saying an operation "is no longer held by attempt N" is that refusal, not an outage. +7. `IN_PROGRESS`는 claim이 있고 끝나지 않았다는 뜻이다. 그 소유자가 죽었어도 claim이 영원히 묶이지는 않는다. + claim TTL(`app.grpc.platform.operation-ledger-claim-ttl`, 기본 5m)보다 오래되면, 같은 요청의 다음 재시도가 + 그것을 넘겨받아 다시 돌리고, 뒤의 reconciler 단계가 그 시도의 `COMMITTED`나 `FAILED_TERMINAL`을 본다. + 재시도가 오기 전까지 그 건은 대기로 남는다. 다시 돌리는 것은 ledger 커밋이 변경 자신의 트랜잭션 안에서 기록될 + 때만 안전하다. 이 서비스가 둘을 따로 커밋하면 재시도를 들이기 전에 업무 자원을 확인한다. 느리기만 했던 + 소유자는 넘겨받기를 망치지 못한다. 그 claim 시도(`claim_attempt`)가 뒤처졌으므로 늦은 커밋은 거부되고 늦은 + 실패는 무시된다. operation이 "is no longer held by attempt N"이라는 로그 줄이 그 거부다. 장애가 아니다. -**Escalate when** the reconciler's pending list grows across passes. That means the ledger is -unreachable rather than slow. A case pending as `IN_PROGRESS` for longer than the claim TTL with no -retry arriving is a caller that gave up; it needs the business resource checked, not a ledger fix. +**넘길 때는** reconciler의 대기 목록이 단계를 거듭하며 커질 때다. ledger가 느린 게 아니라 닿지 않는다는 뜻이다. +claim TTL보다 오래 `IN_PROGRESS`로 대기 중인데 재시도가 오지 않는 건은 호출자가 포기한 것이다. ledger를 고칠 일이 +아니라 업무 자원을 확인할 일이다. --- -## The operation ledger table keeps growing +## operation ledger 테이블이 계속 커진다 -**What you are seeing.** `grpc_operation_ledger` grows without bound, or a retry of an old key runs -the mutation again instead of replaying. +**보이는 것.** `grpc_operation_ledger`가 끝없이 커지거나, 오래된 키의 재시도가 replay 대신 변경을 다시 돌린다. -**What it means.** Finished rows (`COMMITTED`, `FAILED_TERMINAL`) are deleted only when something -calls `GrpcOperationLedgerRetention.purgeExpired(now)`; the starter assembles that bean -(`app.grpc.platform.operation-ledger-enabled=true`) but does not schedule it. A growing table means -the service's scheduler is not calling it. A retry that re-ran after the retention -(`app.grpc.platform.operation-ledger-retention`, default 24h) is the trade the retention makes: its -record was purged, so it was a new operation. +**뜻.** 끝난 행(`COMMITTED`, `FAILED_TERMINAL`)은 누군가 `GrpcOperationLedgerRetention.purgeExpired(now)`를 불러야만 +지워진다. starter는 그 bean을 조립하지만(`app.grpc.platform.operation-ledger-enabled=true`) 일정을 걸지는 않는다. +테이블이 커지면 서비스의 scheduler가 그것을 부르지 않는 것이다. 보존 기간 +(`app.grpc.platform.operation-ledger-retention`, 기본 24h)이 지난 뒤 다시 돈 재시도는 보존 기간이 감수하는 +교환이다. 기록이 지워졌으므로 새 operation이었다. -**What to do.** +**할 일.** -1. Check that the service schedules `purgeExpired`. Each call deletes in batches of 500 until a batch - comes back short, never touching `IN_PROGRESS` rows. -2. For a large backlog, call it repeatedly; each batch is a short transaction that skips rows another - transaction holds. -3. If retried keys re-run after the retention, raise the retention above the callers' retry window - rather than skipping the purge. +1. 서비스가 `purgeExpired`에 일정을 걸었는지 확인한다. 한 번 부르면 500행씩 지우다가 덜 찬 묶음이 나오면 멈추고, + `IN_PROGRESS` 행은 건드리지 않는다. +2. 밀린 양이 많으면 여러 번 부른다. 묶음마다 짧은 트랜잭션이고, 다른 트랜잭션이 쥔 행은 건너뛴다. +3. 다시 보낸 키가 보존 기간 뒤에 다시 돌면, purge를 건너뛰지 말고 보존 기간을 호출자의 재시도 창보다 길게 한다. -**Escalate when** old `IN_PROGRESS` rows accumulate. Those are not purged by design; each is an -abandoned claim no retry has taken over (see `IN_PROGRESS` above). +**넘길 때는** 오래된 `IN_PROGRESS` 행이 쌓일 때다. 그 행은 설계상 지워지지 않는다. 하나하나가 어느 재시도도 +넘겨받지 않은 버려진 claim이다(위의 `IN_PROGRESS`). --- -## A stream ended with FULL_RESYNC_REQUIRED +## stream이 FULL_RESYNC_REQUIRED로 끝났다 -**What you are seeing.** A client's resume was refused and it was told to resynchronise. +**보이는 것.** 클라이언트의 resume이 거부되고 다시 동기화하라는 답을 받았다. -**What it means.** The server can no longer replay from the client's cursor. Either the snapshot -version moved, or the cursor predates retained history. +**뜻.** 서버가 클라이언트의 cursor부터 더는 replay할 수 없다. snapshot 버전이 움직였거나, cursor가 보존된 이력보다 +앞선다. -**What to do.** Nothing on the server. The client is expected to discard its position and start a new -stream from a fresh snapshot. A client that instead retries the same token will keep receiving the -same answer. +**할 일.** 서버에서는 없다. 클라이언트가 자기 위치를 버리고 새 snapshot에서 새 stream을 시작해야 한다. 대신 같은 +token으로 다시 시도하는 클라이언트는 같은 답을 계속 받는다. -**Escalate when** it is happening to many clients at once. That usually means history retention was -reduced, or snapshots are rotating faster than clients reconnect. +**넘길 때는** 많은 클라이언트에 한꺼번에 일어날 때다. 보통 이력 보존이 줄었거나, 클라이언트가 다시 붙는 것보다 +snapshot이 빨리 돈다는 뜻이다. --- -## A stream ended with SLOW_CONSUMER +## stream이 SLOW_CONSUMER로 끝났다 -**What you are seeing.** Streams terminating with `SLOW_CONSUMER`, and -`grpc.stream.flow_control_stalls` rising. +**보이는 것.** stream이 `SLOW_CONSUMER`로 끝나고 `grpc.stream.flow_control_stalls`가 오른다. -**What it means.** The consumer could not keep up with the bounded queue. The stream was terminated -rather than silently dropping messages, because a client cannot detect drops — the sequence numbers -it sees are the ones it was sent. +**뜻.** 소비자가 상한 있는 큐를 따라가지 못했다. 메시지를 조용히 버리는 대신 stream을 끝냈다. 클라이언트는 버려진 +것을 알아챌 수 없다. 클라이언트가 보는 순번은 보내진 것뿐이다. -**What to do.** +**할 일.** -1. Check whether the consumer is slow or the producer is fast. `grpc.stream.messages` against - `grpc.stream.lifetime` tells you the rate. -2. If the consumer is slow, the fix is on the consumer. Raising the queue bound moves the failure - later and makes it larger. -3. A resume is not available after this ending: the messages that overflowed the queue are gone, so - continuing from the last delivered sequence would silently skip them. The client resynchronises. +1. 소비자가 느린지 생산자가 빠른지 확인한다. `grpc.stream.messages`를 `grpc.stream.lifetime`과 견주면 속도가 + 나온다. +2. 소비자가 느리면 고칠 곳은 소비자다. 큐 상한을 올리면 실패가 뒤로 밀리고 커질 뿐이다. +3. 이렇게 끝난 뒤에는 resume을 쓸 수 없다. 큐를 넘친 메시지는 사라졌으므로, 마지막으로 전달한 순번부터 이어 가면 + 그것을 조용히 건너뛴다. 클라이언트는 다시 동기화한다. --- -## RESOURCE_EXHAUSTED under load +## 부하에서 RESOURCE_EXHAUSTED -**What you are seeing.** Calls refused with `RESOURCE_EXHAUSTED` and `GrpcAdmissionController` -reporting rejections. +**보이는 것.** 호출이 `RESOURCE_EXHAUSTED`로 거부되고 `GrpcAdmissionController`가 거부를 보고한다. -**What it means.** The server is at its concurrency and queue bounds and is shedding rather than -queueing. This is the designed behaviour: accepting work whose callers have already given up spends -capacity on nothing. +**뜻.** 서버가 동시성과 큐 상한에 닿아서 줄을 세우지 않고 덜어 낸다. 설계한 동작이다. 호출자가 이미 포기한 일을 +받으면 아무것도 아닌 데 용량을 쓴다. -**What to do.** +**할 일.** -1. Read `grpc.rpc.duration` and `grpc.rpc.queue_wait` separately. Queue time rising with duration flat - means the bottleneck is admission, not the work. -2. Check which saturation counter is moving — executor, channel or flow control. They look identical - in a latency graph and have different fixes. -3. Raising `app.grpc.platform.executor-queue-capacity` defers the problem; it does not remove - it. `GrpcExecutorProfile` refuses a queue above ten thousand for that reason. +1. `grpc.rpc.duration`과 `grpc.rpc.queue_wait`를 따로 읽는다. duration은 그대로인데 큐 시간이 오르면 병목은 일이 + 아니라 admission이다. +2. 어느 포화 counter가 움직이는지 확인한다. executor, channel, flow control이다. 지연 그래프에서는 똑같이 보이지만 + 고치는 법이 다르다. +3. `app.grpc.platform.executor-queue-capacity`를 올리면 문제를 미룰 뿐 없애지 않는다. 그래서 `GrpcExecutorProfile`이 + 1만이 넘는 큐를 거부한다. --- -## A rollout is producing errors at every deploy +## 배포할 때마다 rollout이 오류를 낸다 -**What you are seeing.** A burst of `UNAVAILABLE` or `CANCELLED` each time an instance goes away. +**보이는 것.** 인스턴스가 빠질 때마다 `UNAVAILABLE`이나 `CANCELLED`가 몰린다. -**What it means.** The drain sequence is not completing, or is running out of order. +**뜻.** drain 순서가 끝나지 않거나, 순서가 어긋나서 돈다. -**What to do.** +**할 일.** -1. `GrpcDrainResult` records what each drain achieved: completed and cancelled unary calls, signalled - and cancelled streams, and which phases ran. A drain that routinely force-cancels is the cause. -2. The order matters. Readiness flips first and nothing is refused during that window, because there - is a gap between an instance reporting unready and routing acting on it. Refusing during that gap - turns a clean rollout into a burst of errors at every deploy. -3. For long streams, check the Kubernetes profile's `streamReconnectBudget` and - `readinessDrainGrace`. A stream is pinned to one pod for its whole life, so every rollout ends it; - a profile with long streams and no reconnect budget has not decided what clients do next. +1. `GrpcDrainResult`가 각 drain이 해낸 것을 기록한다. 끝난 unary 호출과 취소된 unary 호출, 신호를 받은 stream과 + 취소된 stream, 돈 단계다. 늘 강제 취소하는 drain이 원인이다. +2. 순서가 중요하다. readiness가 먼저 뒤집히고, 그 사이에는 아무것도 거부하지 않는다. 인스턴스가 unready를 보고한 + 뒤 라우팅이 그것을 따르기까지 틈이 있기 때문이다. 그 틈에 거부하면 깨끗한 rollout이 배포마다 오류 묶음이 된다. +3. 긴 stream이면 Kubernetes profile의 `streamReconnectBudget`과 `readinessDrainGrace`를 확인한다. stream은 일생 + 내내 한 pod에 묶이므로 rollout마다 끝난다. 긴 stream이 있는데 다시 붙는 예산이 없는 profile은 클라이언트가 다음에 + 할 일을 정하지 않은 것이다. --- -## Verifying a deployment's configuration +## 배포의 설정 확인 -`GrpcPlatformSnapshotService` produces a secret-free snapshot for a caller on the admin network -holding an admin role. Both gates are required. +`GrpcPlatformSnapshotService`는 관리 네트워크에 있고 관리 역할을 가진 호출자에게 secret 없는 snapshot을 만든다. +두 관문이 모두 필요하다. -`GrpcPlatformSnapshotService.driftAgainstRelease` compares a running snapshot with the release -manifest and reports schema version, method policy hash and per-channel profile differences. An -instance running a configuration the release did not ship is behind a whole class of incidents that -are otherwise diagnosed by reading logs. +`GrpcPlatformSnapshotService.driftAgainstRelease`는 실행 중인 snapshot을 릴리스 manifest와 비교해 스키마 버전, +메서드 정책 해시, channel별 profile 차이를 보고한다. 릴리스가 내보내지 않은 설정으로 도는 인스턴스는, 그렇지 않으면 +로그를 읽어야만 진단되는 장애 한 부류의 원인이다. -The snapshot carries hashes and names only. A field whose name looks like a credential is refused at -construction rather than redacted. +snapshot에는 해시와 이름만 실린다. 자격 증명처럼 보이는 이름의 칸은 가리지 않고 만들 때 거부한다. --- -## Things that are deliberately off +## 일부러 꺼 둔 것 -- **Reflection in production.** `GrpcReflectionMode.defaultFor` returns `DISABLED` for `STAGE` and - `PROD`. Reflection publishes the whole schema to anyone who can open a connection. -- **Every advanced capability.** See `docs/runbooks/grpc-advanced-capabilities.md`. -- **The platform itself.** `app.grpc.platform.enabled` defaults to false, and every `:grpc:*` - leaf is build-only in the registry. +- **운영의 reflection.** `GrpcReflectionMode.defaultFor`는 `STAGE`와 `PROD`에 `DISABLED`를 돌려준다. reflection은 + 연결을 열 수 있는 누구에게나 스키마 전체를 공개한다. +- **모든 advanced capability.** `docs/runbooks/grpc-advanced-capabilities.md`를 본다. +- **플랫폼 자체.** `app.grpc.platform.enabled`의 기본값은 false이고, registry에서 모든 `:grpc:*` leaf는 + `"build": "optional-grpc"`라 기본 조립에 들어가지 않는다.