pr / done (pull_request) Canceled after 0s
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
150 lines
11 KiB
Markdown
150 lines
11 KiB
Markdown
---
|
||
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 당번)를 부른다.
|