Files
clean-architecture-backend-…/docs/runbooks/lock-acquisition-timeout.md
T
DongHyeonka 354b7fc959
pr / done (pull_request) Canceled after 0s
fix(observability)!: 지표·MDC·헤더 registry를 코드가 실제로 내는 것과 맞춘다
관측 registry가 코드와 양쪽으로 어긋난다. metrics.yaml에는 아무 코드도
등록하지 않는 행 열하나와 코드에 없는 tag 값이 있고, 코드가 등록하는
graphql·notification·http.client·fileserver·mongodb·jpa.query 지표 다수가
없다. mdc-keys.yaml은 18키 중 코드가 넣는 5키만 맞고 required_in이 틀렸다.
headers.yaml은 X-Request-Id·X-Correlation-Id를 ulid로 적고 아무도 쓰지
않는 Deprecation·Sunset·tracestate를 적는다. 전송마다 correlation 규칙이
다른데 registry는 하나로 적는다. 단일 인스턴스 in-process lock은
lock.acquisition을 세지 않아 그 지표가 0이다. 밑줄 든 meter 이름 둘이
이름 규칙을 어긴다.

- 행마다 등록하는 main 파일(source)·상수(constant)·등록 주체
  (registered_by)를 적고, MetricsRegistryCodeAlignmentTest가 행 → 코드(이름이
  상수면 그 상수를 쓰는 곳까지)와 코드(글자·상수 이름의 builder·registry·
  Metrics 호출) → 행 두 방향을 본다. 템플릿이 부르지 않는 공개 메서드로만
  생기는 job.* 행은 emitted_when을 적는다. 버린 안: 행만 지우기(새 지표가
  다시 빠진다).
- mdc-keys는 5키와 전송별 표, headers는 source가 든 33행(서비스 controller용
  상수는 service: 출처), StructuredLog·HeaderRegistry 시험이 코드 상수와
  집합을 대조한다. 두 registry 시험은 시험 도우미 MainSources를 같이 쓴다.
- slo_driven 행은 MetricsDistributionMeterFilter 대상과 같은 집합이다(두
  방향 시험). histogram을 켜지 않는 hikaricp timer 행은 평균으로 경보한다.
  graphql.datafetcher·dataloader 행에 Spring 기본 tag를 적는다.
- in-process lock을 MeteredDistributedLock으로 감싼다.
- http.client.ratelimit.rejected, fileserver.upload.offset.mismatch로
  이름을 바꾸고 http.client.circuit.state.rejected를 상수로 둔다.
- CardinalityBounds(status 40·outcome 6·uri), MetricNaming 단위 규칙,
  SLO filter 대상(http.server.requests·jvm.gc.pause)을 문서와 맞춘다.

위험: 지표 이름 둘이 바뀌고 단일 인스턴스 lock 지표가 생긴다. 그 이름으로
만든 대시보드·경보를 옮겨야 한다(docs/upgrade/2026-11-round9-observability.md
8~13행). ApachePoolMetricsBinder·MongoTransactionRetry 지연은 다른 묶음이
맡는다.

검증: 위와 같은 desktop 실행(묶음 셋을 합친 트리) rc=0.

Refs: RR9-02-05, RR9-02-07, RR9-02-08, RR9-02-27, RR9-03-05
BREAKING CHANGE: http.client.rate_limit.rejected → http.client.ratelimit.rejected,
  fileserver.upload.offset_mismatch → fileserver.upload.offset.mismatch,
  CardinalityBounds 상수. docs/upgrade/2026-11-round9-observability.md 8~13행.
2026-11-13 13:12:27 +09:00

72 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=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다. 그 키를 다음에 잡는 쪽이 넘겨받는다. 가장 오래된
살아 있는 행이 오래 쥔 쪽이다.
<!-- 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).
- 락 경합이 구조적이면 임계 구역을 쥐는 시간을 줄인다.
## 에스컬레이션
- 락 보유자가 멈춘 것으로 보이면 넘긴다(분산 락의 교착 가능성).
---
> **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다.