문제: `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.
3.4 KiB
3.4 KiB
title, category, error_codes, severity, owner, last_updated, status
| title | category | error_codes | severity | owner | last_updated | status | |
|---|---|---|---|---|---|---|---|
| Runbook — LOCK_ACQUISITION_TIMEOUT (분산 락 획득 타임아웃) | CONFLICT |
|
P2 | oncall | 2026-11-07 | 초안 |
Runbook: LOCK_ACQUISITION_TIMEOUT (runbook://lock/acquisition-timeout)
증상
- HTTP 409,
error.code=LOCK_ACQUISITION_TIMEOUT,Retry-After: 1. GraphQL은 extensioncode=LOCK_ACQUISITION_TIMEOUT, gRPC는 trailererror-code: LOCK_ACQUISITION_TIMEOUT(ABORTED)이고, 모두retryable=true다. - 서버 로그 줄이 없다. 4xx 응답은 장애가 아니라서 어느 전송 계층도 로그를 남기지 않고, 락 어댑터도 시간 초과를 로그에 쓰지 않는다. 예외 메시지(락 키, 대기 시간)는 어느 로그에도 클라이언트에도 닿지 않으므로 어느 락이 시간을 넘겼는지는 어디에도 기록되지 않는다. 아래의 메트릭과 락 테이블을 읽는다.
- 분산 락 대기가 설정된 시간 상한을 넘었다. 한 자원에 경합이 심하다.
이력: 2026-11-07 전의 템플릿은 이 경우를 500
INTERNAL_ERROR와 "unhandled exception" ERROR 줄로 응답했다(예외가ApiErrorCarrier가 아니었다). 옛 템플릿을 쓰는 서비스에서는 그것이 보인다.
진단
- 경합 비율.
APP_MULTI_INSTANCE_ENABLED=true이면 JDBC 락에 메트릭이 붙는다.lock.acquisition{outcome="timeout"}을lock.acquisition{outcome="acquired"}와 비교한다. 이 counter에는 락 이름도 대기 시간도 없다. 키는 메트릭 태그가 되지 않는다(docs/registries/metrics.yaml). 프로세스 안 락 (APP_MULTI_INSTANCE_ENABLED=false, 기본값)은 메트릭이 없고 DB에 아무것도 남기지 않는다. 아래 단계는 JDBC 락에만 해당한다. - 지금 누가 락을 쥐고 있나.
INT_LOCK에는 쥔 락마다 한 행이 있다.CLIENT_ID는 쥔 인스턴스의 락 저장소 id이고, 시각은 UTC다.EXPIRED_AFTER가 지난 행은 죽은 lease다. 그 키를 다음에 잡는 쪽이 넘겨받는다. 가장 오래된 살아 있는 행이 오래 쥔 쪽이다.
SELECT lock_key, region, client_id, created_date, expired_after
FROM int_lock
ORDER BY created_date;
- 코드에서 키를 아는 락 하나(예:
orders/42)를 누가 쥐고 있나.LOCK_KEY는 키 자체가 아니다. Spring Integration은 키의 이름 기반 UUID(키의 UTF-8 바이트에UUID.nameUUIDFromBytes)를 저장하므로 테이블에서 키를 거꾸로 읽을 수 없다. 아래 쿼리는 키에서 UUID를 계산해 그 행을 찾는다.
SELECT region, client_id, created_date, expired_after
FROM int_lock
WHERE lock_key = (
SELECT overlay(overlay(h placing '3' from 13)
placing to_hex(8 | (('x' || substr(h, 17, 1))::bit(4)::int & 3)) from 17)::uuid::text
FROM md5('<lock_key>') AS h);
:adapter:outbound:persistence-jpa:postgresqlDistributedLockIntegrationTest가 두 블록을 이 파일에서 읽어,
락을 쥔 상태의 실제 PostgreSQL에 돌린다.
조치
- 클라이언트는 백오프하며 다시 시도한다(retryable=true).
- 락 경합이 구조적이면 임계 구역을 쥐는 시간을 줄인다.
에스컬레이션
- 락 보유자가 멈춘 것으로 보이면 넘긴다(분산 락의 교착 가능성).
초안: 서비스가 도메인을 채운 뒤 본문을 쓴다.