Files
clean-architecture-backend-…/docs/runbooks/outbox-publish-failed.md
T
DongHyeonka 59dff0041c ci(docs): 문서 검사에 문체를 더하고 번역한 결정 기록의 머리 문구를 맞춘다
문체 규칙(「~한다」, 「~합니다」와 섞지 않음)은 docs/README.md에 있지만
지키는 검사가 없어서, 번역 뒤에도 runbook 열 개에 높임 문장이 남았다.
그리고 결정 기록 머리 블록의 둘째 줄은 「본문은 결정한 때의 원문이다」인데,
2026-11-07에 본문을 한국어로 옮긴 ADR에는 맞지 않는다.

- check-docs.py `style`: 살아 있는 문서의 문장 끝이 높임(습니다·합니다·
  입니다·됩니다·십시오·하세요·주세요)이면 실패. 코드 블록, 인라인 코드,
  따옴표·낫표 안 인용, 「이력」 인용 블록은 보지 않는다.
- runbook 열 개의 「이 runbook은 다음 alert에서 발동됩니다.」를 「다음 alert가
  울리면 쓴다.」로 고쳤다. 지금 걸리는 곳은 이것뿐이었다.
- 결정 기록 표시 줄을 「본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지
  않았다)」로 바꿨다: check-docs.py의 DECISION_LABEL, docs/README.md 설명,
  docs/adr의 머리 블록 33개(기록은 머리 블록만 고친다는 규칙 안).
- docs/README.md 「문서 검사」에 앞 커밋이 더한 `link`와 이번 `style`을 적고,
  링크 검사 설명을 바로잡았다. 「모듈 README」 절(design-docs
  docs-system.md 6.2절 다섯 칸)을 더했다.

버린 대안: 문체를 리뷰로만 보기(번역 묶음 네 개를 거쳐도 남았다).

위험: design-docs docs-system.md 4.1절과 프론트의 같은 문구는 이 repo
밖이라 고치지 않았다(총괄에게 알린다).

검증: python3 -m unittest discover -s scripts/tests(문체 시험 5 포함),
check-docs.py, check-work-docs.py 모두 rc=0. 이 커밋의 트리만 얹은 임시
worktree에서 돌렸다. 검사 조건을 끈 사본 둘에서 문체 시험이 각각 2건,
1건 실패했다.
2026-11-07 22:20:18 +09:00

165 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 — outbox publish 일시 실패
category: TRANSIENT_DEPENDENCY
error_codes: [OUTBOX_PUBLISH_FAILED]
severity: P2
owner: oncall
last_updated: 2026-11-04
status: 초안
---
# Runbook: outbox publish 일시 실패 (`runbook://outbox/publish-failed`)
## 1. Trigger
이 runbook은 다음 alert가 울리면 쓴다.
- alert name: `outbox_publish_failed_rate`, `outbox_publisher_lag` 또는 `outbox_retry_long`
- alert payload 필수 field: `error.code=OUTBOX_PUBLISH_FAILED`, `error.reason`, `event_type`, `correlation_id`, `runbook_link`
- 임계 (metrics.yaml verbatim):
- P2: `outbox.publisher.published.total{outcome=FAILED}` rate > 1% for 10m
- P2: `outbox.publisher.lag` > 60s for 10m / P1: > 300s for 5m
- P2: `outbox.pending.size{status=PENDING}` growing for 10m
- P2: `outbox.retry.long.size` > 0 for 10m — §4.1 "끝나지 않는 재시도"로 간다
## 2. First Response (5분 이내)
### Step 1 — 확인
1. ERROR log에서 `OUTBOX_PUBLISH_FAILED` 라인 확인: `event_type`, `event_id`, `correlation_id`, `attempt_count`,
`error.reason` 추출. `error.reason`이 원인 코드다 — publisher가 붙인 코드(예: `KAFKA_AUTHENTICATIONEXCEPTION`,
`KAFKA_TRANSPORT_CLOSED`, `PUBLISH_RUNTIME_UNAVAILABLE`, `PUBLISH_DEADLINE_EXCEEDED`), 코드가 없으면 결과
이름(`AMBIGUOUS`, `REJECTED_RETRYABLE`), 분류되지 않고 던져진 실패면 예외 타입 이름이다. 같은 값이 행의
`last_failure_code`에도 남는다. `error.cause_type`은 어느 결과였는지만 말한다(`OutboxPublishRefusedException`이면
거부, `OutboxPublishAmbiguousException`이면 응답 없음)
2. broker 상태 확인: `APP_MESSAGING_BROKER` 값과 broker endpoint 가용성. 이 키는 활성화 스위치가
아니라 **선택자**다 — messaging을 끄는 것은 `APP_MESSAGING_ENABLED=false`이고, 이 값을 비운다고
messaging이 꺼지지는 않는다.
- relay 스케줄러는 발행 포트(`OutboxMessagePublishPort`, messaging bridge가 제공)가 있을 때만
생긴다. messaging을 고르지 않은 배포에서는 relay가 없고 PENDING row가 그대로 남는다(MSG-024의
"DEAD까지 소진"은 대역 publisher가 있던 때의 이야기다). messaging 모듈이 켜져 있는데
`APP_MESSAGING_PRODUCER_ID`가 공백이면(messaging `MessagingConfig`) 또는 `APP_MESSAGING_BROKER`가
공백이면(messaging platform `MessagingProviderSelection`) 기동이 거부된다 — 값을 설정하거나
messaging을 끈다.
- 발행이 `REJECTED_*`로 바로 DEAD가 된다면 event의 logical destination(`app.messaging.destinations`)이
선언돼 있는지부터 본다.
- 기동은 했는데 실패가 쌓인다면 broker는 설정돼 있고 도달이 안 되는 것이다 — endpoint부터 본다.
3. `outbox.pending.size` status 분포 확인 (FAILED 누적 vs PENDING 누적)
### Step 2 — 임시 격리
- 일시 실패는 자동 backoff 재시도(30s × 2^(attempt-1) + jitter, 상한 5분)가 동작 — broker 장애처럼 원인이 저절로
풀리는 경우는 수동 개입이 필요 없다
- broker 정지·종료 중 거부·Kafka 인증/인가 실패(`AMBIGUOUS`, `REJECTED_RETRYABLE`)는 시도 예산을 쓰지 않는다 — 장애가 길어도 DEAD가 되지 않고, broker가 돌아오면 늦어도 약 5분 30초 안에 자동 재발행된다
- **그 대신 끝이 없다.** 원인이 저절로 풀리지 않으면(진짜로 틀린 credential·ACL, Kafka adapter가 이름을 모르는
broker 거부 — topic timestamp 정책, 없는 topic의 metadata 대기 초과는 기본값으로 `AMBIGUOUS`가 된다) 그 행은 5분
간격으로 영원히 FAILED가 되고 그 aggregate의 뒤 이벤트를 막는다. `outbox.retry.long.size` > 0이면 §4.1로 간다
- max attempts 3은 adapter가 분류하지 못하고 던진 발행 예외에만 적용된다 (소진 시 `runbook://outbox/dead-letter`로 이관)
- relay 자체를 멈춰야 하면 `app.outbox.relay-enabled=false`로 스케줄러 비활성 (이벤트는 outbox 테이블에 안전하게 보존됨 — 유실 없음)
## 3. Diagnosis
- log query: `{service="app"} | error.code="OUTBOX_PUBLISH_FAILED" | stats count by event_type`
- metric panel:
- `outbox.publisher.published.total{outcome}` — FAILED 비율
- `outbox.publisher.lag{event_type}` — 최고령 미발행 이벤트 age
- `outbox.pending.size{status}` — 상태별 분포
- DB 확인: `SELECT status, count(*) FROM outbox_event GROUP BY status;`
- 가능한 원인:
- broker outage/네트워크 → broker 측 회복 대기
- Kafka adapter 미구성(enabled인데 brokers 누락은 기동 시 차단됨) / disabled 상태에서 producer 활성화
- poison event (직렬화 불가/payload 계약 위반) → 확정 거부(`REJECTED_*`)면 바로, 분류되지 않은 예외면 attempts 소진 후 DEAD로 흘러감 (의도된 동작)
- 같은 행의 `OUTBOX_PUBLISH_FAILED`가 5분 간격으로 끝없이 반복되면 §4.1의 조회로 그 행의 `last_failure_code`를
본다. `KAFKA_AUTHENTICATIONEXCEPTION`·`KAFKA_*AUTHORIZATIONEXCEPTION`이면 credential·ACL이 실제로 틀린
것이다 — 고치면 다음 재시도에서 저절로 빠진다. 그 밖의 코드가 같은 행에서만 반복되면 broker가 그 레코드를
받지 않는 것이다 — §4.1로 보류한다
- 동일 aggregate head 실패로 후행 이벤트가 FIFO 게이트에 차단되어 lag 증가 (strict per-aggregate FIFO — 설계 의도)
## 4. Mitigation
- 단기: broker 회복 후 backoff 만료 시 자동 재발행 — `outcome=PUBLISHED` 회복 확인
- IN_FLIGHT orphan(claim 후 crash)은 in-flight-timeout(기본 PT5M) 경과 후 자동 재claim — at-least-once이므로 중복 발행 가능, consumer dedupe(idempotencyKey)가 흡수
- 장기: `app.outbox.poll-interval`/`batch-size` 조정, broker 가용성 SLA 점검, 빈발 event_type의 payload 계약 검토
### 4.1 끝나지 않는 재시도 — 찾기, 보류(park), 재개(resume), 버리기(skip)
시도 예산을 쓰지 않는 실패(§2 Step 2)는 끝 상태가 없다. 리뷰 2026-11-01 README 15절 결정(재시도 유지)은 그대로 두고,
운영자가 그런 행을 보고 멈출 수 있게 한다(재리뷰 2026-11-03 RR-05-03 결정).
**Step 1 — 찾기 (읽기 전용).** 미룬 claim(`deferred_attempt_count`)이 10번 이상인 FAILED 행이다. backoff 상한이
5분이라 10번은 적어도 약 35분 동안 계속 실패했다는 뜻이다. `outbox.retry.long.size`·`outbox.retry.long.age`가
같은 기준(`OutboxMetrics.LONG_RETRY_DEFERRED_CLAIMS`)으로 센다. 아래 SQL의 숫자를 바꾸면 그 상수도 같이 바꾼다 —
`OutboxLongRetryRunbookContractTest`(lane `:composition:outbox-relay:outboxRelayDocumentContractTest`)가 둘을 비교한다.
<!-- runbook-sql: long-retries -->
```sql
SELECT event_id, event_type, aggregate_type, aggregate_id, attempt_count, deferred_attempt_count,
last_failure_code, occurred_at, next_attempt_at
FROM outbox_event
WHERE status = 'FAILED'
AND deferred_attempt_count >= 10
ORDER BY occurred_at, event_id;
```
`last_failure_code`로 원인을 가른다(§3). 원인이 고쳐지는 것(credential·ACL·topic 설정)이면 고치고 기다린다 —
다음 재시도에서 저절로 빠진다. 고칠 때까지 재시도 소음과 실패 로그를 멈추고 싶거나, 그 레코드만 broker가
받지 않는 것이면 Step 2로 보류한다.
**Step 2 — 보류(park).** FAILED 행 하나를 `PARKED`로 둔다. relay는 PARKED 행을 claim하지 않는다. 그 행은
여전히 미발행이라 같은 aggregate의 뒤 이벤트를 계속 막는다 — 순서는 지킨다. `outbox.publisher.lag`도 계속
오른다. 보류는 원인을 찾는 동안 재시도만 멈추는 것이지 incident를 닫는 것이 아니다.
<!-- runbook-sql: park-one -->
```sql
UPDATE outbox_event SET status = 'PARKED' WHERE event_id = '<id>' AND status = 'FAILED';
```
`UPDATE 0`이면 그 사이 relay가 행을 claim해 IN_FLIGHT다. `next_attempt_at`이 지난 뒤 다시 실행한다.
보류된 행 수는 `outbox.pending.size{status=PARKED}`로 보인다.
**롤백 전에 보류를 푼다.** `PARKED`는 이 버전(`bbe944bd` 이후)에 생긴 상태다. 그보다 옛 버전은 이 이름을 몰라
상태별 집계 전체가 실패하고, `outbox.pending.size` 게이지가 PENDING까지 통째로 꺼진다 — `PENDING size growing`
경보의 입력이 사라진다(재리뷰 2026-11-03 2차 RR-02-11). 옛 버전으로 롤백해야 하면 그 전에 보류한 행을 모두
Step 3으로 재개하거나 버린다. 이 버전부터는 모르는 상태가 있어도 그 상태만 빼고 세고 WARN 한 번으로 이름을
말한다(`outbox_event holds rows in a status this version does not know`).
**Step 3 — 재개(resume) 또는 버리기(skip).** 원인을 고쳤으면 재개한다. 행은 FAILED로 돌아가 바로 claim
대상이 된다. 시도 횟수는 그대로 둔다(미룬 claim은 예산을 쓰지 않으므로 DEAD로 바로 가지 않는다).
<!-- runbook-sql: resume-one -->
```sql
UPDATE outbox_event SET status = 'FAILED', next_attempt_at = now() WHERE event_id = '<id>' AND status = 'PARKED';
```
그 이벤트를 영원히 보내지 않기로 했으면 버린다. DEAD skip과 같은 승인 조건이다 — 다운스트림에 영구 이벤트
갭이 생기므로 비즈니스 오너 승인 후에만 하고 incident 기록에 남긴다.
<!-- runbook-sql: parked-skip-one -->
```sql
UPDATE outbox_event SET status = 'PUBLISHED' WHERE event_id = '<id>' AND status = 'PARKED';
```
이 절의 SQL 블록은 문서에서 그대로 읽어 실제 PostgreSQL에서 실행하는 테스트가 있다
(`PostgreSqlOutboxDispositionRunbookIntegrationTest`, lane `postgresqlOutboxDispositionRunbookIntegrationTest`).
블록을 고치면 그 lane을 다시 돌린다.
## 5. Escalation
- P1 lag(>300s 5m) 지속 + broker 회복 불가면 broker/infra 팀에 page
- DEAD 전이가 발생하기 시작하면 `runbook://outbox/dead-letter` 절차로 이관
## 6. Recovery / Verification
- 회복 확인 metric: `outcome=FAILED` rate < 1% 10분 지속, `outbox.publisher.lag` < 60s, `outbox.pending.size{status=FAILED}` 감소 추세
- post-incident: 실패 구간의 DEAD row 유무 확인, consumer 측 중복 처리량 확인(dedupe 동작 검증), backoff/attempts 상수 재평가
## 7. Related
- error-codes.yaml rows: `OUTBOX_PUBLISH_FAILED` (TRANSIENT_DEPENDENCY, retryable=true, retry_after 30s)
- metrics.yaml: `outbox.publisher.published.total`, `outbox.publisher.lag`, `outbox.pending.size`, `outbox.retry.long.size`, `outbox.retry.long.age`
- 코드: `application-core` `PublishPendingOutboxEventsUseCase`(상태머신), `adapter:outbound:persistence-jpa` `outbox/postgresql/PostgreSqlOutboxClaimRepository`(SKIP LOCKED claim + FIFO 게이트), `adapter:outbound:messaging` `outbox/OutboxMessagePublishAdapter`·`platformbridge/PlatformIntegrationEventPublishAdapter`(fail-closed, 원인 코드 번역)
- 관련 runbook: [[outbox-dead-letter]]
- 관련 branch: [[feature-domain-event-outbox-contract]], [[feature-background-job-async-contract]] (retry/DLQ vocabulary SSOT)
---
> **Stub 상태 안내**: 이 runbook은 skeleton 단계의 stub. 실제 broker 채택·alert 라우팅·대시보드 링크 확정 시 보강 필요.