fix: 하네스 제거 및 keycloak 문서 보강

2026-07-25 12:53:13 +09:00
parent 6c53ded9cb
commit d71669eb59
2329 changed files with 138239 additions and 172816 deletions
@@ -1 +0,0 @@
-../../vault/40-publish/blog-topics/webhook-full-jitter-dlq-observability-2026-07-02.md
@@ -0,0 +1,82 @@
+---
+title: blog-topic / webhook-full-jitter-dlq-observability
+source_type: blog-topic
+status: raw
+related_branches: [feature-webhook-outbound-contract]
+related_projects: [ca-tmpl]
+tags: [blog-topic, ca-tmpl, integration, observability, retry-policy, exponential-backoff, dead-letter-queue]
+created: 2026-07-02
+status_label: ready-for-canonical
+target_audience: backend-engineer
+inspiration_url:
+archive_url:
+---
+
+# blog-topic: webhook-full-jitter-dlq-observability
+
+> Layer: `raw/blog-topics/` — 작업 중 나온 블로그 글감 원석. 최종 블로그는 canonical 정제 후 `wiki/blog/`에서 작성한다.
+
+## Parent / 부모
+
+- [[raw/branch-notes/feature-webhook-outbound-contract]] — webhook retry, DLQ, metric registry seed에서 나온 글감.
+
+## 트리거 / Trigger
+
+- 트리거 유형: `branch-work`
+- 트리거 날짜: 2026-07-02
+- 트리거 연결 노트: [[raw/branch-notes/feature-webhook-outbound-contract]]
+
+## 글감 / Topic seed
+
+- 한 문장 요지: webhook retry를 Full Jitter, DLQ, metric contract로 묶을 때 retry storm과 관측 가능성을 어떻게 다룰지 정리한다.
+- 예상 제목 후보:
+  - Webhook retry에 Full Jitter가 필요한 이유
+  - DLQ와 metric 없이 webhook retry를 켜면 생기는 문제
+
+## 핵심 주장 후보 / Claim candidates
+
+- 사실 후보:
+  - branch D3가 Full Jitter retry를 다루고 metric registry seed가 있다 — 근거 후보: [[raw/branch-notes/feature-webhook-outbound-contract]] line `:109`, `:158-170`, `:344-381`.
+- 경험 후보:
+  - 검증 claim이 planned 중심이라 raw topic으로 캡처하되 canonical화 전 구현/테스트 상태를 분리해야 한다.
+- 의견/해석 후보:
+  - retry policy는 backoff 계산식만이 아니라 DLQ, dedupe, metric cardinality와 함께 설계해야 한다.
+
+## Outline seed
+
+1. retry는 장애를 줄일 수도 키울 수도 있다 — synchronized retry와 retry storm을 피해야 한다.
+2. Full Jitter의 역할 — delay 계산식과 upper bound를 project policy로 둔다.
+3. DLQ와 metric contract — 실패를 재시도한 뒤 어디에 남기고 어떻게 관측할지 정한다.
+
+## Canonical 전환 후보 / Canonical extraction candidates
+
+- `wiki/projects/ca-tmpl/data-layer-persistence-cache-outbound.md` 후보:
+  - ca-tmpl webhook retry/DLQ/observability project decision.
+- `wiki/concepts/retry-policy.md` 후보:
+  - exponential backoff, jitter, DLQ 일반 개념.
+- 필요한 추가 검증:
+  - Full Jitter formula source claim, DLQ implementation, metric names/cardinality.
+
+## Sources / 근거 후보
+
+- [[raw/branch-notes/feature-webhook-outbound-contract]] — D3 retry and metric seed 근거.
+- [[raw/official-docs/aws-builders-retry-jitter]] — retry jitter 근거 후보.
+
+## 미해결 / Unknown
+
+- 아직 확인해야 할 사실: webhook retry implementation과 DLQ persistence 상태.
+- 과장하면 안 되는 부분: planned metric/retry items를 구현 완료로 쓰지 않는다.
+- 블로그로 쓰기 전에 필요한 canonical 정제: AWS jitter claim과 ca-tmpl project-local retry policy 분리.
+
+## Decision / 처리 결정
+
+- 액션: `promote-to-canonical`
+- 이유: `wiki/projects/ca-tmpl/data-layer-persistence-cache-outbound.md` 에 webhook retry/DLQ/observability 글감으로 반영했다.
+- 다음 단계: target canonical이 아직 `draft` 이므로 `blogify` 전 review/verify가 필요하다. planned metric/retry items를 구현 완료로 쓰지 않는다.
+
+## Related / 관련
+
+- 관련 branch: [[raw/branch-notes/feature-webhook-outbound-contract]]
+- 관련 error:
+- 관련 interview prep:
+- derived blog: 생성 전. 생성 시 `wiki/blog/webhook-full-jitter-dlq-observability-YYYY-MM-DD.md` 후보
				`@@ -1 +0,0 @@`
				`../../vault/40-publish/blog-topics/webhook-full-jitter-dlq-observability-2026-07-02.md`