문제: `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.
73 lines
3.4 KiB
Markdown
73 lines
3.4 KiB
Markdown
---
|
|
title: Runbook — LOCK_ACQUISITION_TIMEOUT (분산 락 획득 타임아웃)
|
|
category: CONFLICT
|
|
error_codes: [LOCK_ACQUISITION_TIMEOUT]
|
|
severity: P2
|
|
owner: oncall
|
|
last_updated: 2026-11-07
|
|
status: 초안
|
|
---
|
|
|
|
# Runbook: LOCK_ACQUISITION_TIMEOUT (`runbook://lock/acquisition-timeout`)
|
|
|
|
## 증상
|
|
|
|
- HTTP 409, `error.code=LOCK_ACQUISITION_TIMEOUT`, `Retry-After: 1`. GraphQL은 extension
|
|
`code=LOCK_ACQUISITION_TIMEOUT`, gRPC는 trailer `error-code: LOCK_ACQUISITION_TIMEOUT`(`ABORTED`)이고, 모두
|
|
`retryable=true`다.
|
|
- 서버 로그 줄이 없다. 4xx 응답은 장애가 아니라서 어느 전송 계층도 로그를 남기지 않고, 락 어댑터도 시간 초과를
|
|
로그에 쓰지 않는다. 예외 메시지(락 키, 대기 시간)는 어느 로그에도 클라이언트에도 닿지 않으므로 어느 락이
|
|
시간을 넘겼는지는 어디에도 기록되지 않는다. 아래의 메트릭과 락 테이블을 읽는다.
|
|
- 분산 락 대기가 설정된 시간 상한을 넘었다. 한 자원에 경합이 심하다.
|
|
|
|
> 이력: 2026-11-07 전의 템플릿은 이 경우를 500 `INTERNAL_ERROR`와 "unhandled exception" ERROR 줄로
|
|
> 응답했다(예외가 `ApiErrorCarrier`가 아니었다). 옛 템플릿을 쓰는 서비스에서는 그것이 보인다.
|
|
|
|
## 진단
|
|
|
|
1. 경합 비율. `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
|
|
락에만 해당한다.
|
|
2. 지금 누가 락을 쥐고 있나. `INT_LOCK`에는 쥔 락마다 한 행이 있다. `CLIENT_ID`는 쥔 인스턴스의 락 저장소 id이고,
|
|
시각은 UTC다. `EXPIRED_AFTER`가 지난 행은 죽은 lease다. 그 키를 다음에 잡는 쪽이 넘겨받는다. 가장 오래된
|
|
살아 있는 행이 오래 쥔 쪽이다.
|
|
|
|
<!-- runbook-sql: lock-holders -->
|
|
```sql
|
|
SELECT lock_key, region, client_id, created_date, expired_after
|
|
FROM int_lock
|
|
ORDER BY created_date;
|
|
```
|
|
|
|
3. 코드에서 키를 아는 락 하나(예: `orders/42`)를 누가 쥐고 있나. `LOCK_KEY`는 키 자체가 아니다. Spring
|
|
Integration은 키의 이름 기반 UUID(키의 UTF-8 바이트에 `UUID.nameUUIDFromBytes`)를 저장하므로 테이블에서 키를
|
|
거꾸로 읽을 수 없다. 아래 쿼리는 키에서 UUID를 계산해 그 행을 찾는다.
|
|
|
|
<!-- runbook-sql: lock-holder-of-key -->
|
|
```sql
|
|
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).
|
|
- 락 경합이 구조적이면 임계 구역을 쥐는 시간을 줄인다.
|
|
|
|
## 에스컬레이션
|
|
|
|
- 락 보유자가 멈춘 것으로 보이면 넘긴다(분산 락의 교착 가능성).
|
|
|
|
---
|
|
|
|
> **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다.
|