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
17 KiB
title, category, error_codes, severity, owner, last_updated, status
| title | category | error_codes | severity | owner | last_updated | status | |
|---|---|---|---|---|---|---|---|
| Runbook — outbox dead letter | INTERNAL |
|
P1 | oncall | 2026-11-13 | 초안 |
Runbook: outbox dead letter (runbook://outbox/dead-letter)
1. Trigger
이 runbook은 아래 신호로 서비스가 만든 경보가 울리면 쓴다. 이 템플릿은 경보 규칙을 두지 않는다. 경보 이름과 싣는 값은 서비스가 정한다.
- 경보에 실을 만한 값:
error.code=OUTBOX_DEAD_LETTER,event_type,event_id,correlation_id - 임계:
outbox.publisher.published.total{outcome=DEAD}> 0 또는outbox.pending.size{status=DEAD}> 0 (DEAD 전이는 자동 회복이 없으므로 단건도 점검 대상). 두 번째 조건이 필요한 이유: claim이 행을 DEAD로 옮기는 경우 (ATTEMPT_COUNTERS_INCONSISTENT,UNREADABLE_ROW)는 relay 결과를 거치지 않아 첫 번째 카운터가 오르지 않는다.
2. First Response (5분 이내)
Step 1 — 확인
- ERROR log에서
OUTBOX_DEAD_LETTER라인 확인:event_id,event_type,correlation_id,error.reason(원인 코드 — publisher가 붙인 코드, 없으면 거부 결과 이름, 분류되지 않은 예외면 그 타입 이름) 추출. 같은 값이 행의last_failure_code에 남는다. ERROR가 없고 WARNoutbox claim moved a row ... to DEAD만 있으면 relay가 아니라 claim이 행을 DEAD로 옮긴 것이다 —error.reason이ATTEMPT_COUNTERS_INCONSISTENT면deferred_attempt_count를 되돌리지 않은 수동 재발행이 원인이니 §4의 SQL로 다시 재발행한다.UNREADABLE_ROW면 행 자체가 event로 읽히지 않는다(canonical 봉투 없음, 저장된 해시와 바이트 불일치). 이 경우에도 같은 코드가 행의last_failure_code에 남는다 — 그 전 발행 실패의 코드는 덮어쓴다 - DB에서 DEAD row 확인:
SELECT * FROM outbox_event WHERE status = 'DEAD' ORDER BY occurred_at; - 차단 영향 파악 (중요): strict per-aggregate FIFO 정책상 DEAD row는 같은 aggregate(
tenant_scope,aggregate_type,aggregate_id)의 후행 이벤트를 계속 차단함. 순서는(aggregate_sequence, event_index)로 비교한다(claim SQLPostgreSqlOutboxClaimRepository와 같은 키) —SELECT count(*) FROM outbox_event b WHERE b.status <> 'PUBLISHED' AND EXISTS (SELECT 1 FROM outbox_event d WHERE d.status='DEAD' AND d.tenant_scope=b.tenant_scope AND d.aggregate_type=b.aggregate_type AND d.aggregate_id=b.aggregate_id AND (d.aggregate_sequence < b.aggregate_sequence OR (d.aggregate_sequence = b.aggregate_sequence AND d.event_index < b.event_index)));
Step 2 — 임시 격리
- DEAD는 확정 거부(
REJECTED_BEFORE_SEND·REJECTED_AFTER_BROKER) 또는 분류되지 않은 발행 예외의 max attempts(3) 소진의 최종 상태 — 자동 재시도 없음, 수동 개입 필수 - broker 정지·종료 중 거부·Kafka 인증/인가 실패는 DEAD가 되지 않는다(FAILED로 계속 재시도). 이것들로 DEAD가 보이면 이 변경 이전에 생긴 행이다
- 차단된 aggregate가 비즈니스 크리티컬하면 아래 §4의 수동 처분(재발행 또는 skip)을 우선 수행
3. Diagnosis
- log query:
{service="app"} | error.code="OUTBOX_DEAD_LETTER" | stats count by event_type - 마지막 실패 원인 분류:
- poison event (payload 직렬화/계약 위반) → payload 자체 결함, 재발행해도 실패 — 수정 후 재발행 또는 skip
- broker 장기 outage 중 attempts 소진 → 현재 relay에서는 일어나지 않는다(일시적 실패는 예산을 쓰지 않음). 이전 버전에서 생긴 행은 broker 회복 후 재발행으로 해결 가능
- 구성 오류 (Kafka disabled 상태에서 producer 활성) → 구성 수정 후 재발행
- 가능한 원인 우선순위: 구성 오류 > broker outage > poison payload
4. Mitigation (수동 처분 — 둘 중 하나)
재발행 (기본): 원인 해소 후 해당 row를 다시 claim 가능 상태로 되돌린다. 시도 횟수 두 개
(attempt_count, deferred_attempt_count)를 함께 0으로 되돌린다. attempt_count만 되돌리면 다음 claim에서
미룬 claim 수가 전체 claim 수보다 많아지고, claim은 그 행을 읽지 않고 다시 DEAD로 옮긴다.
UPDATE outbox_event SET status = 'PENDING', attempt_count = 0, deferred_attempt_count = 0, next_attempt_at = now() WHERE event_id = '<id>' AND status = 'DEAD';
장애 구간 전체를 한 번에 되돌리려면(원인이 해소된 것을 확인한 뒤). outbox_event에는 DEAD가 된 시각 컬럼이 없어 이벤트 발생 시각으로 고른다 — 먼저 같은 조건의 SELECT로 대상을 확인한다.
UPDATE outbox_event SET status = 'PENDING', attempt_count = 0, deferred_attempt_count = 0, next_attempt_at = now() WHERE status = 'DEAD' AND occurred_at BETWEEN '<장애 시작>' AND '<장애 끝>';
consumer는 at-least-once + idempotencyKey dedupe 의무가 있으므로 중복 발행은 안전하다.
skip (영구 폐기): 이벤트가 더 이상 유효하지 않으면 PUBLISHED로 마킹해 FIFO 차단을 해제한다. ⚠️ skip은 다운스트림에 영구 이벤트 갭을 만든다 — 비즈니스 오너 승인 후에만 수행하고 incident 기록에 남긴다.
UPDATE outbox_event SET status = 'PUBLISHED' WHERE event_id = '<id>' AND status = 'DEAD';
- 장기: poison event 재발 방지(payload 계약 테스트 보강), DEAD 빈발 event_type의 producer 검증 강화
5. Escalation
- 처분 판단(재발행 vs skip)이 불가하면 해당 이벤트의 비즈니스 오너에게 escalate
- DEAD 누적이 특정 event_type에 집중되면 producer 코드 오너에게 page
6. Recovery / Verification
- 회복 확인:
SELECT count(*) FROM outbox_event WHERE status='DEAD';= 0, 차단됐던 aggregate의 후행 이벤트가 PUBLISHED로 전이 outbox.publisher.lag정상화(< 60s), 재발행분의 consumer dedupe 동작 확인- post-incident: DEAD 원인 분류 기록, 같은 원인의 재발 방지 테스트 추가
7. Related
- error-codes.yaml rows:
OUTBOX_DEAD_LETTER(INTERNAL, retryable=false) - metrics.yaml:
outbox.publisher.published.total{outcome=DEAD},outbox.pending.size{status=DEAD},outbox.publisher.lag - 코드:
application-corePublishPendingOutboxEventsUseCase(FAILED→DEAD 전이),adapter:outbound:persistence-jpaoutbox/postgresql/PostgreSqlOutboxClaimRepository(FIFO 게이트 — DEAD가 후행 차단),outbox/jpa/JpaOutboxStore#claimBatch(읽을 수 없는 행을 claim 때 DEAD로) - §4의 SQL 블록은 문서에서 그대로 읽어 실제 PostgreSQL에서 실행하는 테스트가 있다
(
PostgreSqlOutboxDispositionRunbookIntegrationTest, lanepostgresqlOutboxDispositionRunbookIntegrationTest). 블록을 고치면 그 lane을 다시 돌린다 - 관련 runbook: outbox-publish-failed
- 관련 branch: feature-domain-event-outbox-contract, feature-background-job-async-contract (max attempts/DLQ vocabulary SSOT)
8. 배포 전 확인 — V21 순서 키 중복
V21(V21__outbox_aggregate_sequence.sql)은 outbox_event의 순서 키
(tenant_scope, aggregate_type, aggregate_id, aggregate_sequence, event_index)에 유일 인덱스
ux_outbox_event_aggregate_order를 만든다. 같은 키를 가진 행이 이미 둘 이상 있으면 인덱스 생성이
실패하고 기동이 멈춘다(MIGRATION_FAILED, exit 70). 이 실패는 의도한 동작이다(소유자
결정). 같은 키의 행들은 claim gate가 순서를 정하지 못한 행이다. 그냥 넘기면 순서 위반이
숨는다. V21은 transaction 하나로 적용되므로, 실패하면 V21 전체가 롤백되고 V20 상태로 남는다.
V21이 하는 일은 세 가지 더 있다.
- floor 기록.
outbox_aggregate_sequence_floor에 V21 적용 시각(epoch 마이크로초)을 한 번 쓴다. 새로 생기는 aggregate counter는 이 값과 남은 행의 최대 번호 중 큰 값 다음에서 시작한다. 그래서 reaper가 행을 지운 aggregate, tenant scope가 바뀐 aggregate도 소비자가 이미 받은 벽시계 번호(약 1.7×10¹⁵)보다 작은 번호를 받지 않는다. 벽시계 번호를 쓴 적 없는 서비스도 첫 번호가 floor + 1이다. - counter 미리 만들기. 남은 행이 있는 aggregate의 counter를 그 최대 번호로 만든다.
- 잠금 대기 5초. 유일 인덱스는 만드는 동안
outbox_event에 SHARE 잠금을 건다. 그동안 outbox를 쓰는 업무 쓰기가 모두 멈춘다. V21은lock_timeout = 5s로 잠금을 기다린다. 열린 outbox 쓰기 트랜잭션 때문에 5초 안에 못 잡으면 V21이 실패하고 V20에 남는다(MIGRATION_FAILED). 덜 바쁜 시각에 다시 배포하거나 Step 0으로 인덱스를 먼저 만든다.
V20(deferred_attempt_count)과 V22(last_failure_code)도 같은 상한을 둔다.
둘 다 ALTER TABLE outbox_event라 가장 강한 잠금(ACCESS EXCLUSIVE)을 건다. 이 잠금은 읽기와도 충돌하므로,
outbox_event를 읽기만 한 트랜잭션 하나(운영자가 BEGIN 안에서 조회하고 둔 psql 세션 포함)가 열려 있어도
기다린다. 5초 안에 못 잡으면 그 마이그레이션이 실패·롤백되고 DB는 한 버전 아래(V19 또는 V21)에 남으며 새 버전은
기동하지 않는다(MIGRATION_FAILED, exit 70). outbox_event에 잠금을 쥔 열린 트랜잭션을 찾아 끝낸 뒤 다시 배포한다.
SELECT DISTINCT a.pid, a.state, a.xact_start, a.query
FROM pg_locks l JOIN pg_stat_activity a USING (pid)
WHERE l.relation = 'outbox_event'::regclass AND l.granted AND a.pid <> pg_backend_pid()
ORDER BY a.xact_start;
query는 그 세션의 마지막 문장일 뿐이다. outbox_event를 읽은 뒤 다른 문장을 실행한 세션이면 표 이름이 보이지
않으니 query로 원인을 고르지 않는다. 오래 열린 트랜잭션을 모두 보는 조회는 보고·배치 같은 무관한 트랜잭션까지 낸다.
rolling 배포 중 아직 옛 버전인 인스턴스가 벽시계 번호로 쓴 행은 floor보다 크다. 새 버전의 counter는 그 aggregate의 가장 큰 행 번호보다 작아지지 않으므로 그 행 뒤에 번호를 준다. 서로 커밋되지 않은 채 겹친 옛·새 쓰기 사이의 순서는 보장하지 않는다 — 옛 벽시계 방식도 보장하지 않던 것이다.
이 "그 행 뒤에"는 같은 aggregate identity의 행에만 성립한다. tenant scope를 바꾸는 배포에서는 옛 버전이 옛 scope로, 새 버전이 새 scope로 쓴다. 새 버전의 counter는 옛 scope 행을 보지 못하므로 floor + 1부터 시작하고, rolling 중 옛 버전이 방금 쓴 번호(floor보다 초당 10⁶씩 큰 벽시계 번호)보다 작은 번호를 준다(실 PostgreSQL에서 확인). scope를 무시하고 aggregate id로 "마지막 번호보다 작으면 버린다"를 구현한 소비자는 그 사이 새 이벤트를 버린다. 그래서 tenant scope를 바꾸는 배포는 rolling으로 하지 않는다: 옛 버전 인스턴스를 모두 멈춘 뒤(옛·새 버전이 함께 쓰는 구간 없이) 새 버전을 띄운다.
tenant scope를 바꾼 서비스(예: 기능별 scope → 단일 scope)는 배포 전에 옛 scope의 미발행 행이 없는지 확인한다. 옛 scope 행과 새 scope 행은 서로 다른 aggregate로 보여 claim gate가 서로를 막지 않고, partition key도 달라 다른 partition으로 간다.
SELECT tenant_scope, count(*) AS unpublished
FROM outbox_event
WHERE status <> 'PUBLISHED'
GROUP BY tenant_scope;
V20 이하 DB를 V21 이상으로 올리는 배포 전에 아래 순서로 확인한다.
Step 0 — (outbox가 큰 경우만) 순서 키 인덱스를 먼저 만든다
V21이 인덱스를 만드는 동안 outbox 쓰기가 멈춘다. reaper가 outbox_event를 보존 기간 안으로 줄이므로
보통은 짧다. 그 시간도 멈출 수 없을 만큼 크면, Step 1~3으로 중복을 없앤 뒤 같은 이름·같은 열의 인덱스를
CONCURRENTLY로 먼저 만든다. 쓰기를 막지 않는다. transaction 밖(autocommit)에서 실행한다. V21의
IF NOT EXISTS가 이 인덱스를 그대로 쓴다.
CREATE UNIQUE INDEX CONCURRENTLY IF NOT EXISTS ux_outbox_event_aggregate_order
ON outbox_event (tenant_scope, aggregate_type, aggregate_id, aggregate_sequence, event_index);
CONCURRENTLY 빌드가 중복이나 중단으로 실패하면 INVALID 인덱스가 남는다. 이 인덱스는 유일성을 지키지
않는다. V21은 이 이름의 인덱스가 유효한 유일 인덱스가 아니면 건너뛰지 않고 실패한다. 그때는
DROP INDEX CONCURRENTLY ux_outbox_event_aggregate_order; 뒤 Step 1부터 다시 한다. 빌드가 아직 도는
중에도 INVALID로 보이므로, 지우기 전에 pg_stat_progress_create_index에 진행 중인 빌드가 없는지 본다.
V21 안에서 CONCURRENTLY를 쓰지 않은 이유: CONCURRENTLY는 transaction 안에서 돌 수 없다. V21을
transaction 밖으로 빼면 중복을 만났을 때 "V21 전체 롤백, V20 그대로"가 깨지고, 반쯤 적용된 counter·floor와
INVALID 인덱스가 남는다. 인덱스만 V22로 떼어 내도 실패 시 INVALID 인덱스와 Flyway 실패 이력이 남아 수동
복구가 필요하다. 그래서 기본은 transaction 안 빌드 + 잠금 대기 5초, 큰 outbox는 이 Step 0이다.
Step 1 — 중복 확인 (읽기 전용)
SELECT tenant_scope, aggregate_type, aggregate_id, aggregate_sequence, event_index,
count(*) AS row_count,
count(*) FILTER (WHERE status <> 'PUBLISHED') AS unpublished_count,
string_agg(event_id || ':' || status, ', ' ORDER BY occurred_at, event_id) AS events
FROM outbox_event
WHERE tenant_scope IS NOT NULL
AND aggregate_type IS NOT NULL
AND aggregate_sequence IS NOT NULL
AND event_index IS NOT NULL
GROUP BY tenant_scope, aggregate_type, aggregate_id, aggregate_sequence, event_index
HAVING count(*) > 1
ORDER BY tenant_scope, aggregate_type, aggregate_id, aggregate_sequence, event_index;
- 결과가 0행이면 그대로 배포한다.
- 1행 이상이면 Step 2로 간다. 결과 한 행이 순서 키 하나이고,
events가 그 키를 쓰는 행들이다. IS NOT NULL조건이 있는 이유: 유일 인덱스는 다섯 열 중 하나라도 NULL인 행을 비교하지 않는다 (PostgreSQL 기본 동작). 순서 열이 비어 있는 옛 행은 V21을 막지 않는다.
Step 2 — 미발행 행이 빠질 때까지 기다린다
unpublished_count가 0이 아닌 키는 아직 지우지 않는다. 같은 키의 행끼리는 서로를 막지 않으므로
지금 배포된 relay가 계속 발행한다. DEAD 행은 §4의 처분(재발행 또는 skip)을 먼저 한다. Step 1을
다시 돌려 모든 키의 unpublished_count가 0이 되면 Step 3으로 간다.
Step 3 — 이미 발행된 중복을 정리한다
모든 행이 PUBLISHED인 키에서 가장 먼저 생긴 행(occurred_at, event_id 순) 하나만 남기고 나머지를
지운다. 이 행들은 이미 broker로 나갔고 다시 나가지 않는다. 보존 기간이 지나면 reaper가 어차피 지운다.
지우기 전에 outbox_event_v21_duplicates 테이블로 복사해 증거를 남긴다. 미발행 행이 하나라도 있는
키는 이 SQL이 건드리지 않는다.
BEGIN;
CREATE TABLE outbox_event_v21_duplicates AS
SELECT o.*
FROM outbox_event o
JOIN (SELECT event_id,
row_number() OVER same_key AS copy_no,
bool_and(status = 'PUBLISHED') OVER same_key AS all_published
FROM outbox_event
WHERE tenant_scope IS NOT NULL
AND aggregate_type IS NOT NULL
AND aggregate_sequence IS NOT NULL
AND event_index IS NOT NULL
WINDOW same_key AS (
PARTITION BY tenant_scope, aggregate_type, aggregate_id, aggregate_sequence, event_index
ORDER BY occurred_at, event_id
ROWS BETWEEN UNBOUNDED PRECEDING AND UNBOUNDED FOLLOWING)) d
ON d.event_id = o.event_id
WHERE d.copy_no > 1
AND d.all_published;
DELETE FROM outbox_event o
USING outbox_event_v21_duplicates d
WHERE o.event_id = d.event_id;
COMMIT;
Step 1을 다시 돌려 0행이면 배포한다. 정리와 배포 사이에 옛 버전이 새 중복을 만들 수 있다(벽시계로
순서 번호를 만든 옛 코드가 그 원인이었다). 그래도 V21은 실패하고 롤백될 뿐이니 Step 1부터 다시 한다.
outbox_event_v21_duplicates는 확인이 끝나면 지운다.
확인 쿼리, 정리 SQL, Step 0의 인덱스 SQL은 이 문서에서 그대로 읽어 실제 PostgreSQL에서 실행하는
테스트가 있다(PostgreSqlOutboxOrderKeyRunbookIntegrationTest, lane
postgresqlOutboxOrderKeyRunbookIntegrationTest). 같은 lane이 V21의 counter·floor, 잠금 대기 실패,
INVALID 인덱스 거부도 본다. 이 절의 runbook-sql 블록을 고치면 그 lane을 다시 돌린다. V20·V22의 잠금 대기
실패는 PostgreSqlMigrationLockWaitIntegrationTest(lane postgresqlMigrationLockWaitIntegrationTest)가 본다.
Stub 상태 안내: 이 runbook은 skeleton 단계의 stub. 실제 broker·DLQ 토픽·승인 체계 확정 시 보강 필요.