Files
clean-architecture-backend-…/docs/runbooks/idempotency-unavailable.md
T
DongHyeonka 0fded57cb3
pr / done (pull_request) Canceled after 0s
docs(runbooks): runbook 신호를 지금 코드가 내는 응답·로그·지표로 고친다
runbook이 코드가 내지 않는 신호로 장애를 찾게 한다. actuator·cross-tenant
runbook은 아무 코드도 내지 않는 ACTUATOR_FORBIDDEN·AUTHZ_TENANT_MISMATCH를
증상으로 적고, 없는 경보·지표·로그 칸을 적는다. auth runbook은 로그에서
token payload·Authorization 원문을 보라고 하고(남지도 않고 남겨서도 안
된다), 없는 JWKS 캐시 손잡이와 decoder가 읽지 않는 Spring issuer 키를
적는다. rate-limit·dependency runbook은 없는 gateway 지표·헤더·
CACHE_UNAVAILABLE·dependency_name 칸을, web runbook은 연산마다의 TTL,
시험 도구 GracefulShutdownProbe, 없는 tag routeTemplate, 기동이 거부하는
CORS 설정을 「기동은 된다」고 적는다. job runbook은 내는 코드가 없는
JOB_DEAD_LETTER·JOB_TIMEOUT과 job.* 지표에 경보를 걸게 한다.

각 runbook을 지금 코드가 내는 신호로 다시 쓴다: 응답 코드·헤더, 보안
로그 줄 `security failure: code=… path=…`, 요청 로그 줄, ServerFailureLog
의 고정 문구(`dependency failure classified as … dependency=<이름>`,
`persistence failure classified as …`), 실제 설정 키
APP_SECURITY_JWT_ISSUER, registry에 있는 지표. 이 템플릿에 경보 규칙이
없다는 것, 내는 코드가 없는 코드·지표는 서비스가 낼 때만 있다는 것을
적는다. 진단 순서도 고친다: actuator 노출은 관리 포트 9001로 가르고,
INTERNAL_AUTH_MISCONFIGURATION은 issuer discovery(4xx·issuer 불일치·
jwks_uri 없음은 500, 연결 실패·5xx·JSON 아님은 503)부터, 종료 예산은
웹 drain 30s + async 19s + preStop의 합으로 본다. 같은 원인의 다른
자리(경보 이름을 지어 적은 job·outbox·internal-error-spike, traceId로
적은 칸, 지적 밖 auth·dependency·db·outbox runbook, error-codes.yaml 주석,
같은 틀린 신호를 적은 shared-contract README·web README·
DependencyFailureException Javadoc)도 고치고, 본문의 리뷰 ID는 지운다.

버린 안: 선언만 있는 두 코드를 내는 WARN·counter를 새로 만들기. actuator
노출 밖 경로는 메인 chain이 401 AUTH_TOKEN_MISSING(익명)·404(인증됨)로
답해 403 상황이 없고, cross-tenant는 정한 규칙(남의 것은 404)이라 판정
자리가 서비스 코드에 있다. 새 신호는 서비스가 더할 일로 runbook에 적는다.

위험: 문서만 바뀐다. runbook은 모두 status 초안으로 둔다.
dependency-unavailable이 적은 hikaricp.connections.pending·timeout 행과
job.* 행의 emitted_when은 관측 registry 변경(같은 묶음의 다른 PR)이
더하고, auth-jwks-unavailable의 「캐시가 지난 뒤 503」은 인증 PR의 JWKS
재조회 분류 수정이 만든다. 세 PR을 함께 병합한다.

검증: python3 scripts/check-docs.py·check-work-docs.py OK, desktop
:app-bootstrap:documentContractTest :app-bootstrap:repositoryContractTest,
scripts/verify.sh pr rc=0.

Refs: RR9-02-04, RR9-02-24, RR9-04-34, RR9-04-37
2026-11-13 09:35:50 +09:00

150 lines
11 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
---
title: Runbook — IDEMPOTENCY_UNAVAILABLE (멱등성 조정 저장소 사용 불가)
category: TRANSIENT_DEPENDENCY
error_codes: [IDEMPOTENCY_UNAVAILABLE, IDEMPOTENCY_COMPLETION_UNKNOWN, IDEMPOTENCY_RECOVERY_REQUIRED]
severity: P2
owner: oncall
last_updated: 2026-11-13
status: 운영
---
# Runbook: IDEMPOTENCY_UNAVAILABLE (`runbook://idempotency/unavailable`)
## 증상
- `Idempotency-Key`를 받는 엔드포인트에서 HTTP 503(`error.code=IDEMPOTENCY_UNAVAILABLE`, `retryable=true`).
gRPC는 `error-code` trailer에 같은 코드가 온다(`UNAVAILABLE`).
- replay 저장소(`app.idempotency`가 고른 JPA나 Redis)가 답하지 않아서 `IdempotencyExecutor`가 action 실행을
거절했다. 아무것도 실행되지 않았다. 거절은 action 전에 일어나므로 클라이언트가 다시 시도해도 안전하다.
- 처리 lease가 이미 끝난 claim을 저장소가 시작하지 않을 때도 같은 503이다. 요청이 claim과 action 시작 사이에
lease보다 오래 걸렸다(멈춘 프로세스, 느린 저장소 호출). ERROR 줄 `failure classified as
IDEMPOTENCY_UNAVAILABLE (…)`에 예외가 붙고, 예외 메시지는 `the claim's processing lease ran out before the
action started; nothing ran: <scope>`다. prod JSON 로그에서는 `message`가 아니라 `stack_trace`에 있다.
저장소는 멀쩡할 수 있다. 이때도 아무것도 실행되지 않았고, 그 키로 오는 다음 요청이 claim을 넘겨받아 실행한다.
- HTTP 503 `IDEMPOTENCY_COMPLETION_UNKNOWN`(`retryable=true`)은 같은 장애가 action이 실행된 뒤에 닥친 것이다.
결과를 기록하는 동안 저장소가 답하지 않았다. use case가 자기 쓰기 트랜잭션 안에서 executor를 불렀으면, 그
트랜잭션의 DB 쓰기는 예외와 함께 롤백됐다. 자기 트랜잭션을 따로 커밋한 action은 쓰기가 남았고, 트랜잭션 밖의
일(외부 호출, 메시지)은 일어났을 수 있다. 「아무것도 실행되지 않았다」가 아니다. 클라이언트는 같은 키로 다시
보낸다.
- HTTP 500 `IDEMPOTENCY_RECOVERY_REQUIRED`(`retryable=false`)는 반대 경우다. 앞선 시도의 효과가 이미 일어났는지
저장소가 가릴 수 없다. 두 기록이 이 코드를 낸다.
- `ABANDONED`: action이 예외를 던졌거나 효과를 모른다고 보고했다. 기록이 만료될 때까지 바뀌지 않는다.
- 처리 lease(`APP_IDEMPOTENCY_PROCESSING_LEASE`, 30s)가 지난 `EXECUTING`: 시도가 죽었거나, lease보다 오래 아직
돌고 있다. executor는 lease를 늘리지 않으므로 느리지만 멀쩡한 요청도 여기에 온다. 서버는 그 요청을 다시
실행하지 않고 기록도 건드리지 않는다. 시도가 아직 돌다가 끝나면 그 결과가 기록되고, 첫 요청은 보통의 응답을
받고, 그 키로 오는 뒤의 요청은 그 결과를 replay로 받는다. 시도가 보고한 실패도 같은 식으로 기록된다. 그래서
이 500은 저절로 멈출 수 있다(소유자 결정 2026-11-04).
이것은 Redis 저장소의 경우다. PostgreSQL 저장소는 템플릿이 부르는 대로 use case의 쓰기 트랜잭션 안에서
불리면, 끝나지 않은 기록을 다른 요청에 보이지 않는다. 그 요청은 첫 트랜잭션이 끝나기를 기다렸다가, 커밋됐으면
replay를, 롤백됐으면 새 실행을 받는다(`docs/web/http-contract.md` §2).
## 진단
- 서비스가 쓰는 멱등성 저장소의 상태를 본다(고른 provider에 따라 JPA datasource나 Redis의 `/actuator/health`
구성 요소).
- 같은 시간대에 그 저장소의 커넥션 풀 포화나 시간 초과를 찾는다. executor는 포화를 추측하지 않고 사용 불가로
보고한다.
- `IDEMPOTENCY_RECOVERY_REQUIRED`는 실패한 요청의 서버 ERROR 로그에서 scope를 찾는다. 모든 전송 계층이 같은 줄
`failure classified as IDEMPOTENCY_RECOVERY_REQUIRED (category=DATA_INTEGRITY, retryable=false)`에 예외를
붙여 쓰고(shared-contract `ServerFailureLog`), 자기 상관 정보를 덧붙인다.
- web: 덧붙이는 것이 없다. 줄에 요청의 `X-Request-Id`(MDC `request_id`)가 실린다.
- gRPC: ` (method=<service>/<method>)`. 서비스가 callback 스레드에서 호출을 닫았으면 MDC `request_id`도 있다.
- GraphQL: ` (executionId=<id>)`. 클라이언트가 오류의 `extensions`에서 받은 `executionId`다.
- STOMP(`@MessageMapping`): 덧붙이는 것이 없다. MDC `request_id`는 그 frame의 것이다.
예외 메시지는 `<operation code>::v<digest version>::<scope digest>`로 끝난다. 예:
`claim requires reconciliation: CHARGE_CARD::v1::3f9a…`(16진수 64자). 그다음 서비스가 쓰는 저장소
(`APP_IDEMPOTENCY_PROVIDER`)에서 기록을 본다. 이것을 해 주는 도구는 없다. 아래가 그 명령이다.
- Redis. 키는 예를 들어 `prod:order:shared:idem:v1:d1:CHARGE_CARD:3f9a…`이고, 모양은 다음과 같다.
<!-- runbook-redis: idempotency-record-key -->
```
<APP_REDIS_NAMESPACE_ENVIRONMENT>:<APP_REDIS_NAMESPACE_SERVICE>:<APP_REDIS_NAMESPACE_DOMAIN>:idem:v1:d<digest version>:<operation code>:<scope digest>
```
```
HMGET <key> state attempt leaseUntil
PTTL <key>
```
`state` `ABANDONED`는 바뀌지 않는다. `state` `EXECUTING`이면서 `leaseUntil`(lease 끝, epoch 밀리초, 서버
시계)이 서버의 `TIME`(첫 값 × 1000)보다 이르면, lease가 지났지만 아직 돌고 있을 수 있는 시도다. `PTTL`은
기록이 앞으로 살아 있을 시간(밀리초)이다.
- PostgreSQL. 애플리케이션의 스키마에서:
```sql
SELECT status, attempt, failure_disposition, last_transition_kind,
processing_lease_until, expires_at, updated_at
FROM idempotency_record
WHERE record_version = 2
AND scope_hash = '<scope digest>';
```
`status` `ABANDONED`에 `last_transition_kind` `FAIL_ABANDONED`면 action이 예외를 던졌거나 효과를 모른다고
보고했다. `status` `EXECUTING`에 `processing_lease_until`이 `clock_timestamp()`보다 이르면, lease가 지났지만
아직 돌고 있을 수 있는 시도다. `expires_at`은 reaper가 행을 지우는 시각이다.
> 이력: `ABANDONED`에 `EXPIRED_EXECUTION`은 2026-11-04 전 버전에서 lease가 끝난 행이다. 그 버전은 그런 행을
> 버렸다. 행이 만료되면 사라진다.
## 조치
- `IDEMPOTENCY_UNAVAILABLE`: 저장소를 되살린다. 클라이언트는 같은 키로 백오프하며 다시 시도한다. 예외 메시지가
action 시작 전에 claim의 처리 lease가 끝났다고 하면 저장소가 원인이 아니다. claim과 시작 사이에 그 요청들을
붙잡은 것을 찾는다(스레드 덤프, GC 멈춤, 그 시간대의 저장소 지연). 고칠 것은 없다. 같은 키의 다음 요청이
실행된다.
- `IDEMPOTENCY_COMPLETION_UNKNOWN`: 저장소를 되살린 뒤, 실패한 요청들의 트랜잭션 밖 효과를 확인한다(ERROR 로그
줄이 코드를 알려 준다). 같은 키로 다시 보내면, 실제로 기록된 결과는 replay로 받고, 시도의 lease가 남은 동안은
`IDEMPOTENT_IN_FLIGHT`를, 그 뒤에는 `IDEMPOTENCY_RECOVERY_REQUIRED`를 받는다. 마지막 것은 아래처럼 다룬다.
- `IDEMPOTENCY_RECOVERY_REQUIRED`: 클라이언트에게 그냥 다시 시도하라고 하지 않는다. 기록이 lease가 지난
`EXECUTING`이면 먼저 시도를 기다린다. action이 걸릴 수 있는 가장 긴 시간이 지난 뒤 기록을 다시 본다. 시도가
끝나면 기록은 저절로 바뀐다. `COMPLETED`(다시 보내면 replay된다, 할 일 없음), `ABANDONED`, `FAILED_RETRYABLE`
(시도가 효과가 없었음을 증명했고, 그 키의 다음 요청이 실행한다) 중 하나다. 죽은 시도, 또는 요청이 이미
`IDEMPOTENCY_COMPLETION_UNKNOWN`으로 끝난 시도는 기록을 바꾸지 않는다. 그 기록은 만료될 때까지 `EXECUTING`으로
남는다. 시도가 아직 도는 동안 확인한 업무 데이터는 효과가 들어가기 직전에 「효과 없음」으로 보일 수 있다.
그다음 업무 데이터(주문, 결제, 하위 시스템)로 효과가 있는지 확인한다. 기록을 손으로 완료할 방법은 없다. 저장된
응답은 action 자신의 결과다.
- 효과가 있다: 클라이언트에게 적용됐다고 알린다. 기록은 그대로 둔다. 그 키로 다시 보내면 기록이 만료될 때까지
(Redis `PTTL`, PostgreSQL `expires_at`) 이 500을 계속 받는다.
- 효과가 없다: 클라이언트가 새 키로 요청을 다시 보낸다. 같은 키로 다시 돌리게 하려면 기록을 지운다. 단
`ABANDONED`일 때만 지운다. 다른 상태는 아직 돌고 있을 수 있는 요청이나 저장된 결과의 것이다. `EXECUTING`
기록은 lease가 지났어도 지우지 않는다. 그 시도가 아직 살아 있으면 늦게 온 결과가 기록을 찾지 못하고
(`ABSENT`) 결과가 사라진다. 첫 요청은 일이 적용된 뒤에 이 500을 받고, 그 키의 다음 요청이 일을 한 번 더
한다. 만료되게 둔다.
- Redis: 확인과 삭제를 한 단계로, 서비스에 등록된 스크립트가 도는 계정으로 한다
(`APP_REDIS_AUTHENTICATION_ADVANCED_CREDENTIAL_REFERENCE`, 비어 있으면 애플리케이션 계정). `HMGET`으로
확인하고 `DEL`을 보내면 명령이 둘이다. 그 사이에 만료되어 새 요청이 다시 claim한 기록은 그 요청이 도는
동안 지워지고, 그 키의 다음 요청이 일을 한 번 더 한다. 아래 프로그램은
`state`가 `ABANDONED`일 때만 키를 지운다. 애플리케이션 계정은 `EVAL`이 막혀 있으므로
(`compose/redis/acl/README.md`), 서비스가 자기 스크립트를 돌리는 것처럼 불러 올리고 `SCRIPT LOAD`가 찍은
digest로 돌린다.
<!-- runbook-redis: idempotency-delete-abandoned -->
```
SCRIPT LOAD "if redis.call('HGET', KEYS[1], 'state') == 'ABANDONED' then return redis.call('DEL', KEYS[1]) end return 0"
EVALSHA <digest SCRIPT LOAD printed> 1 <key>
```
`1`이면 기록을 지웠고 키는 새것이다. `0`이면 아무것도 지우지 않았다. 기록이 더는 `ABANDONED`가 아니다
(또는 없다). 다른 일을 하기 전에 다시 본다. `NOSCRIPT`는 키를 가진 노드(클러스터)가 프로그램을 불러 올리지
않았다는 뜻이다. 그 노드에서 `SCRIPT LOAD`를 돌리고 `EVALSHA`를 다시 한다. 아무것도 지워지지 않았다. 곧
만료될 기록은 할 일이 없다. 사라지면 키는 새것이다.
- PostgreSQL:
```sql
DELETE FROM idempotency_record
WHERE record_version = 2
AND scope_hash = '<scope digest>'
AND status = 'ABANDONED';
```
어느 단계도 하지 않으면 기록이 만료될 때 키가 풀린다. 시도가 끝나지 않은 기록은 claim부터 처리 lease에
`APP_IDEMPOTENCY_TTL`을 더한 만큼 산다. action이 실패로 표시한 기록은 실패부터
`APP_IDEMPOTENCY_FAILURE_RETENTION`(`APP_IDEMPOTENCY_TTL`보다 짧지 않다)만큼 산다
(`docs/web/http-contract.md` 「서버가 기억하는 기간」).
## 에스컬레이션
- 쓰기 경로에서 저장소가 10분 넘게 사용 불가로 남으면 P2 → P1.
- 멱등성 저장소 소유자(DB나 Redis 당번)를 부른다.