문제: `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.
10 KiB
Runbook: gRPC platform operations
범위: :grpc:* family. 지금은 모두 빌드만 된다. registry에서 이 family의 leaf는 모두 "build": "optional-grpc"
(주 빌드 밖, -p platforms/optional-build로 돈다)이고 어느 조립에도 들어가지 않으므로, 여기 있는 것은 아직 운영에서
일어나지 않는다. 그래도 지금 쓰는 이유가 있다. 여기서 다루는 상태는 당번이 새벽 세 시에 처음부터 따져서는 알아낼
수 없는 것들이고, runbook보다 동작을 먼저 내보내면 그것을 처음 만난 사람이 그 따지기를 하게 된다.
설정은 app.grpc.platform.* 아래에 있고 GrpcPlatformProperties가 묶는다. 플랫폼은
app.grpc.platform.enabled=true가 아니면 뜨지 않는다.
상태를 바꾸는 호출의 COMPLETION_UNKNOWN
보이는 것. 클라이언트가 상태를 바꾸는 호출에서 DEADLINE_EXCEEDED, UNAVAILABLE, INTERNAL을 받았고, 응답
trailer completion-outcome이 COMPLETION_UNKNOWN이다.
뜻. 서버가 커밋했을 수 있다. 실패도 성공도 아니다. 상태 코드로는 둘을 가릴 수 없어서 결과를 따로 싣는다.
하지 말 것. 호출을 다시 보내지 않는다. 호출자에게 실패했다고 말하지 않는다. 둘 다 절반은 틀리고, 어느 절반인지 상태 코드로는 알 수 없다.
할 일.
-
trailer에서
error-execution-id를 꺼낸다. 클라이언트가 본 것과 서버가 한 것을 잇는 유일한 고리다. -
메서드가
IDEMPOTENCY_KEY_REQUIRED면 호출자 fingerprint, 전체 메서드 이름, 호출자의 키로 operation ledger를 조회한다.GrpcOperationStatusQuery는IN_PROGRESS,COMMITTED,FAILED_TERMINAL,NOT_FOUND,UNKNOWN중 하나를 돌려준다. -
COMMITTED면 새로 계산한 답이 아니라 저장된 결과 참조를 돌려준다. 그 뒤에 자원이 바뀌었을 수 있고, 새 답은 호출자 자신의 호출이 만든 상태가 아니라 맞춰 보는 시점의 상태를 설명한다. -
NOT_FOUND는 operation이 시작하지 않았다는 뜻이라 다시 보내도 안전하다.FAILED_TERMINAL도 같다. -
UNKNOWN은 ledger를 조회하지 못했다는 뜻이다. 아무것도 결론 낼 수 없다.GrpcCompletionReconciler가 그 건을 대기열에 넣고 나중에 다시 시도한다. -
메서드에 키가 없으면 ledger 행이 없다. 업무 자원으로 맞춰 보거나 서비스 소유자에게 넘긴다. 키 있는 profile은 이 경우를 피하려고 있다.
-
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"이라는 로그 줄이 그 거부다. 장애가 아니다.
넘길 때는 reconciler의 대기 목록이 단계를 거듭하며 커질 때다. ledger가 느린 게 아니라 닿지 않는다는 뜻이다.
claim TTL보다 오래 IN_PROGRESS로 대기 중인데 재시도가 오지 않는 건은 호출자가 포기한 것이다. ledger를 고칠 일이
아니라 업무 자원을 확인할 일이다.
operation ledger 테이블이 계속 커진다
보이는 것. grpc_operation_ledger가 끝없이 커지거나, 오래된 키의 재시도가 replay 대신 변경을 다시 돌린다.
뜻. 끝난 행(COMMITTED, FAILED_TERMINAL)은 누군가 GrpcOperationLedgerRetention.purgeExpired(now)를 불러야만
지워진다. starter는 그 bean을 조립하지만(app.grpc.platform.operation-ledger-enabled=true) 일정을 걸지는 않는다.
테이블이 커지면 서비스의 scheduler가 그것을 부르지 않는 것이다. 보존 기간
(app.grpc.platform.operation-ledger-retention, 기본 24h)이 지난 뒤 다시 돈 재시도는 보존 기간이 감수하는
교환이다. 기록이 지워졌으므로 새 operation이었다.
할 일.
- 서비스가
purgeExpired에 일정을 걸었는지 확인한다. 한 번 부르면 500행씩 지우다가 덜 찬 묶음이 나오면 멈추고,IN_PROGRESS행은 건드리지 않는다. - 밀린 양이 많으면 여러 번 부른다. 묶음마다 짧은 트랜잭션이고, 다른 트랜잭션이 쥔 행은 건너뛴다.
- 다시 보낸 키가 보존 기간 뒤에 다시 돌면, purge를 건너뛰지 말고 보존 기간을 호출자의 재시도 창보다 길게 한다.
넘길 때는 오래된 IN_PROGRESS 행이 쌓일 때다. 그 행은 설계상 지워지지 않는다. 하나하나가 어느 재시도도
넘겨받지 않은 버려진 claim이다(위의 IN_PROGRESS).
stream이 FULL_RESYNC_REQUIRED로 끝났다
보이는 것. 클라이언트의 resume이 거부되고 다시 동기화하라는 답을 받았다.
뜻. 서버가 클라이언트의 cursor부터 더는 replay할 수 없다. snapshot 버전이 움직였거나, cursor가 보존된 이력보다 앞선다.
할 일. 서버에서는 없다. 클라이언트가 자기 위치를 버리고 새 snapshot에서 새 stream을 시작해야 한다. 대신 같은 token으로 다시 시도하는 클라이언트는 같은 답을 계속 받는다.
넘길 때는 많은 클라이언트에 한꺼번에 일어날 때다. 보통 이력 보존이 줄었거나, 클라이언트가 다시 붙는 것보다 snapshot이 빨리 돈다는 뜻이다.
stream이 SLOW_CONSUMER로 끝났다
보이는 것. stream이 SLOW_CONSUMER로 끝나고 grpc.stream.flow_control_stalls가 오른다.
뜻. 소비자가 상한 있는 큐를 따라가지 못했다. 메시지를 조용히 버리는 대신 stream을 끝냈다. 클라이언트는 버려진 것을 알아챌 수 없다. 클라이언트가 보는 순번은 보내진 것뿐이다.
할 일.
- 소비자가 느린지 생산자가 빠른지 확인한다.
grpc.stream.messages를grpc.stream.lifetime과 견주면 속도가 나온다. - 소비자가 느리면 고칠 곳은 소비자다. 큐 상한을 올리면 실패가 뒤로 밀리고 커질 뿐이다.
- 이렇게 끝난 뒤에는 resume을 쓸 수 없다. 큐를 넘친 메시지는 사라졌으므로, 마지막으로 전달한 순번부터 이어 가면 그것을 조용히 건너뛴다. 클라이언트는 다시 동기화한다.
부하에서 RESOURCE_EXHAUSTED
보이는 것. 호출이 RESOURCE_EXHAUSTED로 거부되고 GrpcAdmissionController가 거부를 보고한다.
뜻. 서버가 동시성과 큐 상한에 닿아서 줄을 세우지 않고 덜어 낸다. 설계한 동작이다. 호출자가 이미 포기한 일을 받으면 아무것도 아닌 데 용량을 쓴다.
할 일.
grpc.rpc.duration과grpc.rpc.queue_wait를 따로 읽는다. duration은 그대로인데 큐 시간이 오르면 병목은 일이 아니라 admission이다.- 어느 포화 counter가 움직이는지 확인한다. executor, channel, flow control이다. 지연 그래프에서는 똑같이 보이지만 고치는 법이 다르다.
app.grpc.platform.executor-queue-capacity를 올리면 문제를 미룰 뿐 없애지 않는다. 그래서GrpcExecutorProfile이 1만이 넘는 큐를 거부한다.
배포할 때마다 rollout이 오류를 낸다
보이는 것. 인스턴스가 빠질 때마다 UNAVAILABLE이나 CANCELLED가 몰린다.
뜻. drain 순서가 끝나지 않거나, 순서가 어긋나서 돈다.
할 일.
GrpcDrainResult가 각 drain이 해낸 것을 기록한다. 끝난 unary 호출과 취소된 unary 호출, 신호를 받은 stream과 취소된 stream, 돈 단계다. 늘 강제 취소하는 drain이 원인이다.- 순서가 중요하다. readiness가 먼저 뒤집히고, 그 사이에는 아무것도 거부하지 않는다. 인스턴스가 unready를 보고한 뒤 라우팅이 그것을 따르기까지 틈이 있기 때문이다. 그 틈에 거부하면 깨끗한 rollout이 배포마다 오류 묶음이 된다.
- 긴 stream이면 Kubernetes profile의
streamReconnectBudget과readinessDrainGrace를 확인한다. stream은 일생 내내 한 pod에 묶이므로 rollout마다 끝난다. 긴 stream이 있는데 다시 붙는 예산이 없는 profile은 클라이언트가 다음에 할 일을 정하지 않은 것이다.
배포의 설정 확인
GrpcPlatformSnapshotService는 관리 네트워크에 있고 관리 역할을 가진 호출자에게 secret 없는 snapshot을 만든다.
두 관문이 모두 필요하다.
GrpcPlatformSnapshotService.driftAgainstRelease는 실행 중인 snapshot을 릴리스 manifest와 비교해 스키마 버전,
메서드 정책 해시, channel별 profile 차이를 보고한다. 릴리스가 내보내지 않은 설정으로 도는 인스턴스는, 그렇지 않으면
로그를 읽어야만 진단되는 장애 한 부류의 원인이다.
snapshot에는 해시와 이름만 실린다. 자격 증명처럼 보이는 이름의 칸은 가리지 않고 만들 때 거부한다.
일부러 꺼 둔 것
- 운영의 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"라 기본 조립에 들어가지 않는다.