Files
grpc-library/docs/runbooks/grpc-advanced-capabilities.md
T
DongHyeonka b071ff74c5 docs(runbooks): runbook을 한국어로 옮기고 상태를 초안·운영으로 바꾼다
문제: `docs/runbooks`의 runbook 38개가 영어였다(`check-docs.py` language
예외). 머리말 `status`는 `stub`·`active`였는데 문서 체계 규칙(design-docs
`conventions/docs-system.md` 1절)은 runbook 상태를 「초안 · 운영」으로 정한다.
번역하며 대조하니 지금 코드와 다른 주장도 있었다.

고친 것:
- 38개를 번역했다. 코드·명령·경로·설정 키·로그 문자열·표 구조는 그대로다.
  lane이 읽는 SQL·Redis 블록과 표지(`<!-- runbook-sql: … -->`)는 바이트 그대로다.
- `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.
2026-11-07 17:56:34 +09:00

4.9 KiB

Runbook: gRPC advanced capabilities

범위: :grpc-advanced:* family. 여기 있는 것은 모두 기본으로 꺼져 있고, 배포가 이름을 대기 전까지 꺼진 채로 있다. 지금 이 family의 어떤 것도 런타임 조립에 들어가지 않는다.

스위치는 app.grpc.advanced.<capability>.enabled다. capability 이름 목록과 기본 등급은 GrpcAdvancedCapability(defaultGrade())가 가진다. 근거가 있는 배포는 GrpcAdvancedFeatureFlags.withGrade로 등급을 바꾼다.


capability가 뜨기를 거부한다

GrpcAdvancedModuleGuard는 세 가지로 거부하고, 고치는 법이 다르다.

메시지에 있는 말 뜻 고치는 법
"its feature flag is not set" 아무도 켜지 않았다 메시지가 이름 댄 속성을 설정한다
"tracked rather than implemented" 등급이 WATCH다 여기서 할 일은 없다. 그 capability는 구현되지 않았다
"uncharacterised failure modes" 등급이 EXPERIMENTAL이고 여기는 운영이다 운영 승인을 기록하거나, 운영 밖에서 돌린다

거부 메시지는 늘 속성 키를 이름 댄다. 그래서 첫 경우는 지원 문의가 아니라 설정 한 줄이다.


xDS: control plane이 사라졌다

보이는 것. control plane에 닿지 않는데 클라이언트는 아직 라우팅한다.

뜻. GrpcXdsFailurePolicy가 마지막으로 정상이던 snapshot을 오래됨 상한까지 내준다.

할 일.

  1. snapshot의 나이를 본다. SERVE_LAST_KNOWN_GOOD는 정상적인 degraded 상태다.
  2. STALE_BEYOND_BOUND는 snapshot이 정책이 허용하는 것보다 오래돼서 더는 믿지 않는다는 뜻이다. 그 상한이 없으면 내린 backend가 트래픽을 끝없이 받는다.
  3. 뜨는 인스턴스의 NO_SNAPSHOT_YET은 control plane에 한 번도 닿지 못했다는 뜻이다. 라우팅 없이 뜨지 않고, 첫 fetch 시간 상한이 지나면 실패한다.

xDS가 켜진 동안 애플리케이션 수준의 재시도 정책을 더하지 않는다. GrpcXdsProfile이 APPLICATION 재시도 소유자를 거부한다. 두 곳에 정의한 재시도는 결정이 아니라 해석 순서가 이기는 쪽을 정하기 때문이다.


gRPC-Web: 브라우저 호출이 멈췄다가 상태 없이 실패한다

거의 언제나 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에 그것이 들어 있다.

메서드가 client streaming이나 bidirectional streaming이면 gRPC-Web으로는 아예 되지 않는다. 브라우저는 메시지 stream을 보낼 방법이 없다. GrpcWebRpcSupport.require가 그런 메서드를 거부한다.


Servlet: 전송 설정이 무시되는 것 같다

무시된다. 소켓은 컨테이너가 가지므로 keepalive 조정, 최대 연결 수명, flow-control window 조정은 컨테이너의 몫이다. 이 저장소에는 그것을 거부할 Servlet 전송 코드가 없으니 컨테이너에서 설정한다.

Servlet 실행은 Netty 인증을 대신하지 않는다.


Hedging: backend 부하가 두 배가 됐다

상한 안이면 예상한 일이다. hedging은 중복 부하를 내고 꼬리 지연을 줄인다. GrpcHedgingResult는 duplicateBackendCalls와 cancelledLoserAttempts를 둘 다 기록한다. 지연 개선만 보여 주는 대시보드는 그 교환을 공짜처럼 보이게 한다.

확인할 것. GrpcHedgingBudget은 hedge를 끝난 호출의 비율로 제한한다. 중복 부하가 그 비율을 넘으면 예산이 쓰이지 않고 있다는 뜻이다. coordinator 밖에서 무언가가 hedge를 보내고 있다.

읽기 전용 unary 메서드가 아니면 hedging을 거부한다. hedge된 변경은 설계상 두 번 돈다. 멱등 키도 소용없다. 두 번째 시도는 실패를 다시 시도하는 것이 아니라 진행 중인 성공을 중복한다.


capability 승격

ADVANCED_STABLE로 올리려면 호환성 증거, 보안 리뷰, 장애 증거, 성능 증거, ADR, runbook, 실제 환경 시험, 7일 soak이 필요하다. Stable 기본값은 30일이 필요하다. 승격은 서로 독립이다. 한 capability를 올려도 다른 것의 등급은 바뀌지 않는다. 이것은 리뷰 점검 목록이다. 이것을 코드로 다시 적은 GrpcAdvancedPromotionGate는 자기 테스트 말고는 부르는 곳이 없어 지웠다(리뷰 2026-09-24 S5-lead-4).

어떤 suite를 증거로 들기 전에, 그 suite가 필요한 실제 인프라(proxy, 컨테이너, control plane, toolchain)에 대고 돌았는지 확인한다. 인프라 없이 돈 suite는 통과했지만 아무것도 증명하지 않았다.