문제(round8 확인 리뷰 RR8-01-02):
- 락 timeout이 4xx carrier가 된 뒤로 어느 락이 막혔는지 서버 어디에도
남지 않는다. 그런데 runbook은 lock.acquisition metric에서 락 이름과
시간을 보라고 하고(metric은 outcome tag 하나뿐인 counter), 없는
integration_lock 테이블에서 보유자를 찾으라고 한다(테이블은 INT_LOCK,
LOCK_KEY는 key가 아니라 key의 UUID). 예외 Javadoc과 application-core
README는 메시지가 "서버 로그 전용"이라 적지만 그 메시지를 남기는
로그가 없다.
고른 방법(리뷰 권장안):
- runbook Symptoms·Diagnosis를 있는 정보로 다시 쓴다: 로그가 없다는 것,
경합 비율은 lock.acquisition{outcome} 비교(JDBC 락에만, 이름·시간
없음), INT_LOCK의 보유자 목록, 코드에서 아는 key의 보유자(key를
Spring Integration과 같은 name-based UUID로 계산하는 SQL).
- 두 SQL에 runbook-sql 표시를 달고 postgresqlDistributedLockIntegrationTest
가 runbook 파일에서 읽어 실 PostgreSQL에서 락을 잡은 채 돌린다(lane
입력에 runbook을 넣어 문서를 고치면 lane이 다시 돈다).
- 예외 Javadoc·README의 "서버 로그 전용"을 "클라이언트에 보내지 않고,
어느 로그에도 남지 않는다. 필요하면 호출자가 key()를 남긴다"로 고친다.
- 버린 안: 락 timeout에 WARN 한 줄(key digest, 대기 시간)을 남기기 —
로그 정책을 바꾸는 소유자 결정이고, 템플릿은 tryAcquire를 부르지 않는다.
위험·한계:
- runbook은 status: stub 그대로다. Action·Escalation 본문은 도메인을
고른 서비스가 쓴다.
- key가 UUID 문자열이면 Spring Integration은 그대로 쓰므로 계산 SQL이
맞지 않는다. runbook은 "코드에서 아는 key"만 말한다.
- OutboxRunbookSql을 그대로 쓴다. 그 이름을 바꾸는 수정(RR8-03-03)과
합칠 때 이 테스트의 참조도 함께 바뀌어야 한다.
검증(desktop, flock, --no-build-cache, 로그 ~/r9-g1-inbound-logs/):
- RED(문서의 주장을 단언한 임시 탐침, 기준 3eb3b067 + 탐침, 커밋 안 함,
트리 a675c244):
- "integration_lock 테이블에서 보유자를 찾는다": 락을 잡은 채
SELECT count(*) FROM integration_lock → postgresqlDistributedLock
IntegrationTest 7건 중 1건 실패, BadSqlGrammarException(relation
"integration_lock" does not exist). red/R6-jpa-table-claim.log
- "lock.acquisition metric에서 락 이름과 시간을 본다": timeout 뒤
outcome 밖의 tag가 있어야 한다 → MeteredDistributedLockTest 11건 중
1건 실패(tag 없음). red/R5-jpa-metric-claim.log
- GREEN(이 커밋 트리 fc5eae5a):
- :application-core:check :adapter:outbound:persistence-jpa:check rc=0,
test 1,089건 실패 0(skip 19는 application-core의 이전부터 것). 같은
worktree의 앞 실행(green/C1-check.log, 이 두 leaf의 입력이 같은 트리
acf42e98)으로 UP-TO-DATE. green2/C1-check.log
- :adapter:outbound:persistence-jpa:postgresqlDistributedLockIntegrationTest
rc=0, 8건(runbook의 두 SQL 블록을 파일에서 읽어 실행하는 새 테스트 2건
포함) 실패 0. green2/C2-lock-lane.log
- :app-bootstrap:documentContractTest rc=0, 67건(RunbookCoverageContract
Test 포함). green2/C3-doc-contract.log
Refs: docs/reviews/2026-11-03-rereview/README.md 19절 RR8-01-02, round8/01-transport-errors.md
3.1 KiB
3.1 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 | stub |
Runbook: LOCK_ACQUISITION_TIMEOUT (runbook://lock/acquisition-timeout)
Symptoms
- HTTP 409 with
error.code=LOCK_ACQUISITION_TIMEOUTandRetry-After: 1; GraphQL extensioncode=LOCK_ACQUISITION_TIMEOUT, gRPC trailererror-code: LOCK_ACQUISITION_TIMEOUT(ABORTED), allretryable=true. - No server log line. A 4xx answer is not an incident, so no transport logs it, and the lock adapters do not log a timeout either. The exception's message (lock key, wait time) reaches no log and no client, so which lock timed out is recorded nowhere. Read the metric and the lock table below.
- Before 2026-11-07 the template answered this as 500
INTERNAL_ERRORwith an "unhandled exception" ERROR line (the exception was not anApiErrorCarrier). A service on an older template sees that instead. - Distributed lock wait exceeded configured timeout; high contention on a resource
Diagnosis
- Contention rate. With
APP_MULTI_INSTANCE_ENABLED=truethe JDBC lock is metered: comparelock.acquisition{outcome="timeout"}withlock.acquisition{outcome="acquired"}. The counter has no lock name and no wait time — a key is never a metric tag (docs/registries/metrics.yaml). The in-process lock (APP_MULTI_INSTANCE_ENABLED=false, the default) has no metric and keeps nothing in the database; the steps below apply only to the JDBC lock. - Who holds locks now.
INT_LOCKhas one row per held lock.CLIENT_IDis the holding instance's lock repository id, and the times are UTC. A row whoseEXPIRED_AFTERhas passed is a dead lease: the next acquisition of that key takes it over. The oldest live rows are the long holders.
SELECT lock_key, region, client_id, created_date, expired_after
FROM int_lock
ORDER BY created_date;
- The holder of one lock whose key you know from the code (for example
orders/42).LOCK_KEYis not the key: Spring Integration stores the key's name-based UUID (UUID.nameUUIDFromBytesof the key's UTF-8 bytes), so a key cannot be read back from the table. This computes the UUID from the key and finds its row:
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 runs both blocks, read
from this file, against real PostgreSQL while locks are held.
Action
- Client should retry with backoff (retryable=true)
- Optimize critical section holding time if lock contention is systemic
Escalation
- Escalate if lock holder appears stuck (potential deadlock in distributed lock)
Stub: Phase D2 — author body after domain adoption. (feature-operational-runbook-contract D9)