문제: 3차 수정의 확인 리뷰가 새 Important 없이 Minor 19건을 남겼다. 동작에 닿는 것이 셋이다. JDK read-idle watchdog이 공용 ForkJoinPool에서 돌아 그 풀이 바쁘면 300ms timeout이 6초 가까이 늦었다. 붙여 쓴 -x<task>를 verifyStrictLaneStages가 읽지 않아 lane을 뺀 workflow가 통과했다. 사용자 전송이 중간 클래스를 거쳐 @SystemCaller bean을 부르면 ArchUnit 규칙을 지났다. 잠금 대기 검사기는 FK·trigger·REINDEX와 lock_timeout = 0을 못 봤고, 쿼터 보정 SQL은 코드와 다른 모양의 행을 넣었다. 방법: 영역별 4묶음이 맡은 Minor만 test-driven-development 절차로 고쳤다(재리뷰 README 12절). - watchdog은 전용 데몬 스레드 하나에서 돌고 스트림을 닫으면 작업을 취소한다. read당 비용은 그대로다(21–24ns). - 사용자 전송 → @SystemCaller는 직접·간접 의존 모두 거부한다. 리뷰가 권한 직접 의존 검사는 중간 클래스 하나로 다시 열려서 버렸다. - 검사기를 보강하면서 새로 걸린 이미 배포된 마이그레이션 5개는 내용을 바꾸지 않고 동결 목록에 더했다(main과 blob이 같다). - 비밀 목록 bean은 규칙보다 먼저 만들어 실제 클래스로 검사한다. 위험·한계: 회복 필요 예외 메시지 끝에 scope digest가 붙고 기동 실패 문구가 바뀌어, 문구 전체에 맞추던 로그 매처는 고쳐야 한다. 코드가 든 Redis 계정 참조의 fixture- 검사는 문서로만 막았다(코드로 막으려면 새 의존 edge가 필요하다). failure-retention ≥ replay-ttl 기동 검사는 넣지 않았다. -mx 같은 짧은 플래그 묶음과 graphql 전송 fixture는 남았다. spotbugsTestFixtures(게이트 밖)의 정규식 경고가 15건으로 늘었다. 검증: ci, 두 빌드의 verifyStrictLaneStages --dry-run, mainCheck, :integrationCheck, -p optional-platforms ci integrationCheck performanceCheck, :performanceCheck, :releaseCheck(-PgitRevision), verify-compose-profile-contracts(18 lane) 첫 실행 통과. watchdog은 공용 풀을 채운 상태에서 300ms 설정이 300ms에 끝나는 것을 쟀다. Refs: docs/reviews/2026-11-03-rereview/README.md 11·12절, round3/
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-04 | stub |
Runbook: outbox dead letter (runbook://outbox/dead-letter)
1. Trigger
이 runbook은 다음 alert에서 발동됩니다.
- alert name:
outbox_dead_letter - alert payload 필수 field:
error.code=OUTBOX_DEAD_LETTER,event_type,event_id,correlation_id,runbook_link - 임계:
outbox.publisher.published.total{outcome=DEAD}> 0 또는outbox.pending.size{status=DEAD}> 0 (DEAD 전이는 자동 회복이 없으므로 단건도 점검 대상). 두 번째 조건이 필요한 이유: claim이 행을 DEAD로 옮기는 경우 (ATTEMPT_COUNTERS_INCONSISTENT,UNREADABLE_ROW)는 relay 결과를 거치지 않아 첫 번째 카운터가 오르지 않는다 (재리뷰 2026-11-03 2차 RR-02-12)
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로 옮긴다(재리뷰 2026-11-03
RR-05-01).
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). 이 실패는 의도한 동작이다(리뷰 2026-11-01
README 15절 결정). 같은 키의 행들은 claim gate가 순서를 정하지 못한 행이다. 그냥 넘기면 순서 위반이
숨는다. V21은 transaction 하나로 적용되므로, 실패하면 V21 전체가 롤백되고 V20 상태로 남는다.
V21이 하는 일은 세 가지 더 있다.
- floor 기록.
outbox_aggregate_sequence_floor에 V21 적용 시각(epoch 마이크로초)을 한 번 쓴다. 새로 생기는 aggregate counter는 이 값과 남은 행의 최대 번호 중 큰 값 다음에서 시작한다. 그래서 reaper가 행을 지운 aggregate, tenant scope가 바뀐 aggregate도 소비자가 이미 받은 벽시계 번호(약 1.7×10¹⁵)보다 작은 번호를 받지 않는다(리뷰 RR-03-02). 벽시계 번호를 쓴 적 없는 서비스도 첫 번호가 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)도 같은 상한을 둔다(재리뷰 2026-11-03 2차 RR-02-09).
둘 다 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⁶씩 큰 벽시계 번호)보다 작은 번호를 준다(재리뷰 2026-11-03 2차 RR-02-10, 실 PG 확인). scope를 무시하고 aggregate id로 "마지막 번호보다 작으면 버린다"를 구현한 소비자는 그 사이 새 이벤트를 버린다. 그래서 tenant scope를 바꾸는 배포는 rolling으로 하지 않는다: 옛 버전 인스턴스를 모두 멈춘 뒤(옛·새 버전이 함께 쓰는 구간 없이) 새 버전을 띄운다.
tenant scope를 바꾼 서비스(샘플은 portfolio → 단일 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 토픽·승인 체계 확정 시 보강 필요.