--- 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=false`, 기본값)과 JDBC 락 모두 메트릭이 붙는다. `lock.acquisition{outcome="timeout"}`을 `lock.acquisition{outcome="acquired"}`와 비교한다. 이 counter에는 락 이름도 대기 시간도 없다. 키는 메트릭 태그가 되지 않는다(`docs/registries/metrics.yaml`). 프로세스 안 락은 DB에 아무것도 남기지 않는다. 아래 단계는 JDBC 락에만 해당한다. 2. 지금 누가 락을 쥐고 있나. `INT_LOCK`에는 쥔 락마다 한 행이 있다. `CLIENT_ID`는 쥔 인스턴스의 락 저장소 id이고, 시각은 UTC다. `EXPIRED_AFTER`가 지난 행은 죽은 lease다. 그 키를 다음에 잡는 쪽이 넘겨받는다. 가장 오래된 살아 있는 행이 오래 쥔 쪽이다. ```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를 계산해 그 행을 찾는다. ```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('') AS h); ``` `:adapter:outbound:persistence-jpa:postgresqlDistributedLockIntegrationTest`가 두 블록을 이 파일에서 읽어, 락을 쥔 상태의 실제 PostgreSQL에 돌린다. ## 조치 - 클라이언트는 백오프하며 다시 시도한다(retryable=true). - 락 경합이 구조적이면 임계 구역을 쥐는 시간을 줄인다. ## 에스컬레이션 - 락 보유자가 멈춘 것으로 보이면 넘긴다(분산 락의 교착 가능성). --- > **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다.