김신건의 로그 - 위키 / distributed-systems

[Distributed] Kafka Consumer Group: rebalancing, offset, lag

koa (김신건) — Thu, 25 Jun 2026 00:00:00 GMT

정의

Consumer Group = 같은 group.id 를 가진 consumer 들이 함께 한 topic 을 분담 소비. partition 단위로 분배.

Partition 할당

flowchart LR
    subgraph T[Topic: orders, 6 partitions]
        P0[p0] & P1[p1] & P2[p2] & P3[p3] & P4[p4] & P5[p5]
    end
    subgraph CG[Consumer Group]
        C1[Consumer 1] --> P0 & P1
        C2[Consumer 2] --> P2 & P3
        C3[Consumer 3] --> P4 & P5
    end

규칙:

partition 수 ≥ consumer 수 면 모두 분배.
partition 수 < consumer 수 면 일부 consumer idle.
한 partition → 한 consumer (group 안).

Rebalancing

consumer 추가 / 제거 / 죽음 → partition 재할당:

sequenceDiagram
    autonumber
    participant C1 as Consumer 1
    participant C2 as Consumer 2 (new)
    participant Coord as Group Coordinator

    C1->>Coord: heartbeat
    C2->>Coord: join group
    Note over Coord: rebalance 시작
    Coord->>C1: stop fetching (revoke)
    C1->>Coord: ack + commit offset
    Coord->>C1: new assignment (p0, p1, p2)
    Coord->>C2: new assignment (p3, p4, p5)
    C1->>C1: resume fetching
    C2->>C2: start fetching

Eager vs Cooperative

	Eager (옛 기본)	Cooperative (Kafka 2.4+)
Rebalance 시	모든 consumer 정지	영향받는 partition 만
처리 중단	길음 (수십 초 가능)	짧음
Throughput	하락 큼	적음

[!IMPORTANT] Cooperative rebalancing 이 2026 권장 기본. partition.assignment.strategy=org.apache.kafka.clients.consumer.CooperativeStickyAssignor.

Static Membership (KIP-345)

group.instance.id=consumer-1

consumer 가 동일 ID 로 재접속 하면 partition 유지.
배포 / 재시작 시 rebalance 회피.
보통 수십 초 ~ 수 분 안 의 짧은 재시작 가정.

Offset 관리

flowchart LR
    C[Consumer] -->|fetch| K[(Kafka)]
    C -->|commit| Offset["__consumer_offsets<br/>(internal topic)"]
    Note1[정기 commit 또는 명시적]

모드	안전성
`enable.auto.commit=true` (기본)	중복 또는 손실 가능
명시적 sync commit	안전
명시적 async commit + 마지막 sync	balanced

Auto commit 함정

1. fetch [100, 101, 102]
2. 처리 중 ...
3. 5초 후 auto commit (103 까지 commit)
4. consumer crash (102 처리 미완)
5. 재시작 → 103 부터 fetch → 102 손실!

[!CAUTION] Auto commit 은 손실 또는 중복 의 함정. exactly-once 가 필요하면 명시적 commit + idempotent 처리.

Consumer Lag

flowchart LR
    Last["partition 의 last offset (LEO): 1000"] --> Lag
    Curr["consumer current offset: 800"] --> Lag
    Lag[Lag = 200<br/>processing 못 따라옴]

도구	의미
`kafka-consumer-groups.sh --describe`	즉시 확인
Kafka Lag Exporter	Prometheus 메트릭
Burrow (LinkedIn)	더 세련된 lag 분석

Lag 기반 Auto-Scaling

flowchart LR
    Lag[Consumer Lag] -->|KEDA| HPA[Kubernetes HPA]
    HPA --> Scale[Consumer pod 수 증가]

KEDA 가 Kafka lag 을 Kubernetes HPA 지표 로 사용. spike 자동 흡수.

Heartbeat / Session

설정	의미	기본
`session.timeout.ms`	이 시간 heartbeat 없으면 죽었다고 판단	45s
`heartbeat.interval.ms`	heartbeat 보내는 주기	3s
`max.poll.interval.ms`	poll 사이 최대 시간	5min

[!WARNING] max.poll.interval.ms 초과 = consumer 추방. 처리 시간이 길면 명시적 늘림 또는 워커 별도 스레드.

흔한 함정

[!WARNING]

Rebalancing 폭주 = consumer 자주 추가/제거 → 처리 정지 반복. cooperative + static membership.

auto.offset.reset=latest + 다운 = 다운 사이 메시지 손실. 보통 earliest.

너무 큰 batch = max.poll.records 너무 큼 → 처리 시간 길어 추방.

상태 있는 consumer + rebalance = partition 이 다른 consumer 로 가면서 처리 진행 정보 손실. 상태는 외부 store 에.

[Distributed] Kafka: 분산 로그, partition, consumer group

koa (김신건) — Thu, 25 Jun 2026 00:00:00 GMT

정의

Apache Kafka = 분산 commit log. 고처리량 (수백만 msg/s), 영속, 수평 확장. event-driven 아키텍처 의 de facto.

핵심 개념: topic = partition 들 = 노드에 분산된 append-only log.

토폴로지

flowchart TB
    P1[Producer 1] --> T1[Topic: events]
    P2[Producer 2] --> T1
    subgraph T1[Topic: events]
      Part0["partition 0<br/>(broker A)"]
      Part1["partition 1<br/>(broker B)"]
      Part2["partition 2<br/>(broker C)"]
    end
    T1 --> CG1[Consumer Group: analytics]
    T1 --> CG2[Consumer Group: search]
    CG1 --> C11[Consumer 1]
    CG1 --> C12[Consumer 2]
    CG1 --> C13[Consumer 3]
    CG2 --> C21[Consumer 1]

Partition: 핵심 단위

{}

속성	의미
Append-only	끝에만 추가
Immutable	변경 불가
Ordered	partition 안에서 순서 보장
Distributed	노드 간 분산
Replicated	RF (Replication Factor) 만큼 복제
Offset	각 메시지의 partition 내 ID

Partition 수 선택

flowchart TD
    Q{Partition 수}
    Q -->|"적음 (1-3)"| Low[병렬성 낮음<br/>순서 보장 쉬움]
    Q -->|"중간 (10-50)"| Med[일반적]
    Q -->|"많음 (100+)"| High[오버헤드 증가<br/>리밸런싱 비용]

[!IMPORTANT] Partition 수 = 한 consumer group 의 최대 병렬성. 늘리는 건 가능하지만 줄이는 건 불가. 보수적으로 시작.

Consumer Group

flowchart LR
    subgraph CG1[Consumer Group A]
        C1[Consumer 1] --> P0[part 0]
        C2[Consumer 2] --> P1[part 1]
        C3[Consumer 3] --> P2[part 2]
    end
    subgraph CG2[Consumer Group B]
        D1[Consumer 1] --> P0
        D1 --> P1
        D1 --> P2
    end

규칙	의미
한 partition → 한 consumer (group 안)	순서 보장
한 consumer → N partitions	OK
Consumer 수 > Partition 수	남는 consumer는 idle
다른 group → 독립 offset	fan-out

Offset 관리

sequenceDiagram
    C->>K: poll() (offset 100 ~)
    K-->>C: msgs [100, 101, 102]
    C->>C: 처리
    C->>K: commit offset 103
    Note over C,K: 다음 poll 부터 103 부터

모드	의미
Auto commit	주기적 자동. 최대 한 번 손실 또는 중복
Manual sync commit	처리 후 동기 commit. 정확
Manual async commit	비동기 commit. 최후 commit 실패 가능

Replication + ISR

flowchart LR
    Leader["Leader replica"] --> F1["Follower 1"]
    Leader --> F2["Follower 2"]
    Leader --> ISR{"ISR<br/>In-Sync Replica set"}
    F1 --> ISR
    F2 -.지연.-> ISR

Leader 가 모든 write 수신.
Follower 가 동기 (또는 비동기) 복제.
ISR = 충분히 따라온 replica 집합.
Leader 다운 → ISR 중 새 leader.

설정	의미
`acks=0`	응답 안 기다림 (손실 가능)
`acks=1`	leader 만 (기본)
`acks=all`	ISR 전체 (가장 안전)
`min.insync.replicas`	최소 ISR 수. 미달 시 write 거절

[!CAUTION] acks=all + min.insync.replicas=2 가 프로덕션 표준. 낮은 settings 는 운영 사고 단골.

Exactly-once Semantics (EOS)

flowchart LR
    P[Producer<br/>idempotent + transactional] --> K[Kafka]
    K --> C[Consumer<br/>read_committed]
    P -->|transactional.id| TC[Transaction Coordinator]
    C -->|isolation.level=read_committed| K

Producer idempotence: 재전송 시 중복 제거.
Transactional producer: 여러 topic write 를 원자적.
Consumer isolation.level=read_committed: aborted 트랜잭션 무시.

[!NOTE] 완벽한 EOS 는 Kafka 안에서만. Kafka → DB → Kafka 등 외부 시스템 포함 은 outbox + idempotency 패턴이 추가로 필요. 자세한 건 [[outbox-pattern]].

KRaft (Kafka Raft, ZooKeeper 제거)

flowchart LR
    subgraph Old[옛 구조]
        K1[Kafka 브로커] --> Zk[(ZooKeeper)]
    end
    subgraph New[KRaft 구조]
        K2[Kafka 브로커] -.-> Quorum[메타데이터 controller<br/>Raft 합의]
    end

2.8+ preview, 3.5+ production, 4.0+ ZK 완전 제거.
운영 단순화 + 확장성 (수백만 partition).

Kafka 의 적합 / 부적합

적합	부적합
Event sourcing	작은 데이터 (RabbitMQ 가 단순)
로그 수집	request-reply (가능하지만 어색)
Stream processing	1-N 즉시 fan-out (Pub/Sub 가 간단)
CDC (Change Data Capture)	짧은 retention task queue (Sidekiq 가 적합)

흔한 함정

[!WARNING]

Partition 수 부족 = 병렬성 제한. 늘리는 건 가능하지만 기존 키 분포 깨짐.

Rebalancing 폭주 = consumer 가 자주 join/leave → 모든 consumer 정지 후 재할당. cooperative rebalancing (Kafka 2.4+) 으로 완화.

Hot partition = key 선택 잘못 → 한 partition 만 트래픽. key 디자인 재검토.

auto.offset.reset=latest = consumer 가 죽었다 살아나면 그동안 메시지 손실. 보통 earliest.

[Distributed] Message Broker 비교: Kafka / RabbitMQ / NATS / SQS / Redis Streams

koa (김신건) — Thu, 25 Jun 2026 00:00:00 GMT

결정 트리

flowchart TD
    Q1{사용 패턴}
    Q1 -->|event log + replay| Kafka[Kafka]
    Q1 -->|복잡 라우팅 + task queue| Rabbit[RabbitMQ]
    Q1 -->|마이크로서비스 가벼움| NATS[NATS]
    Q1 -->|AWS managed + 단순 큐| SQS[SQS]
    Q1 -->|Redis 위 fan-out / 짧은 큐| RedisS[Redis Streams]
    Q1 -->|클라우드 native pub-sub| GCP[Google Pub/Sub]

6가지 broker 매트릭스

항목	Kafka	RabbitMQ	NATS	SQS	Redis Streams	Google Pub/Sub
모델	log	exchange-queue	subject pub-sub	queue	log	topic pub-sub
영속	항상	옵션	옵션 (JS)	항상	옵션	항상
Throughput	수백만/s	수만/s	수백만/s	거의 무한 (auto-scale)	수십만/s	수백만/s
Latency	중간 (ms)	낮음	마이크로초	수십 ms	낮음	중간
운영 복잡도	높음	중간	낮음	없음 (managed)	낮음 (Redis 운영자라면)	없음
라우팅	partition by key	exchange 패턴	subject 계층	FIFO/standard	consumer group	filtering
Re-play (재처리)	자유 (offset)	한 번만	JS 가능	DLQ 만	가능 (XREAD)	가능
학습 곡선	높음	중간	낮음	낮음	낮음	낮음
비용 (자체호스팅)	비쌈	중간	저렴	-	저렴	-
비용 (managed)	Confluent	CloudAMQP	Synadia	AWS	ElastiCache	GCP

처리량 / 지연 / 운영비용 (직관)

시나리오별 추천

시나리오	추천
Event sourcing (큰 로그)	Kafka
마이크로서비스 commands	NATS 또는 RabbitMQ
AWS Lambda + 큐	SQS
Sidekiq 같은 Ruby job queue	Redis (list 기반)
실시간 채팅 fan-out	NATS 또는 Redis Pub/Sub
CDC (DB → search)	Kafka + Debezium
트래픽 spike 자동 흡수	SQS (managed)
빠른 mvp / startup	Redis Streams

메시지 보장 비교

Broker	At-most-once	At-least-once	Exactly-once
Kafka	옵션	기본	EOS 가능
RabbitMQ	옵션	persistent + ack	외부 idempotency 필요
NATS Core	기본	-	-
NATS JS	-	기본	옵션
SQS	-	기본	FIFO + 5분 dedup
Redis Streams	-	XACK 로	외부 idempotency

[!IMPORTANT] Exactly-once 는 broker 내부 에서만 의미 있음. 외부 시스템 (DB, API) 까지 완벽한 exactly-once 는 불가능. idempotency + outbox 가 현실적 정답. 자세한 건 [[outbox-pattern]], [[idempotency-keys]].

영속 / 재처리 비교

flowchart TD
    Kafka[Kafka<br/>days~weeks retention<br/>임의 offset replay]
    Rabbit[RabbitMQ<br/>queue 안의 메시지<br/>소비 = 사라짐]
    Nats[NATS JS<br/>retention 정책<br/>임의 시점 replay]
    Sqs[SQS<br/>최대 14일<br/>한 번 소비 = 사라짐]
    Stream[Redis Streams<br/>MAXLEN 만큼<br/>임의 offset]

마이그레이션 비용

출발	도착	비용
Sidekiq (Redis)	Kafka	큼 (consumer group, exactly-once 재설계)
RabbitMQ	Kafka	중간 (라우팅 → topic 재설계)
Kafka	NATS	작음 (둘 다 log)
자체 호스팅	Managed	작음 (운영 측면 큰 이득)

운영자 시점 체크리스트

✓ 메시지 손실 허용?              (acks, persistent, ack 정책)
✓ 순서 보장 필요?                 (partition key, FIFO)
✓ 재처리 가능?                    (offset / position)
✓ DLQ + parking lot              (실패 메시지 격리)
✓ Backpressure                   (prefetch, max-in-flight)
✓ Monitoring                     (lag, dead messages, throughput)
✓ Consumer auto-scaling          (lag 기반)

[Distributed] NATS: 가벼움, JetStream, subject 라우팅

koa (김신건) — Thu, 25 Jun 2026 00:00:00 GMT

정의

NATS = 극도로 가벼운 메시징 시스템. core NATS = at-most-once Pub/Sub + request-reply. JetStream = 영속 / at-least-once / exactly-once 까지.

특징:

1 바이너리 (Go), 메모리 ~10MB.
마이크로초 latency.
수백만 msg/s/노드.
edge / IoT / 마이크로서비스 친화.

두 모드: Core vs JetStream

	Core NATS	JetStream
영속	없음 (in-memory)	있음
신뢰성	at-most-once	at-least-once / exactly-once
Latency	매우 낮음	낮음
사용	telemetry, signal	event log, queue

Subject 계층

orders.created
orders.paid
orders.shipped.us
orders.shipped.eu
inventory.low.warehouse-a

와일드카드	의미
`*`	단어 1개
`>`	나머지 모두

subscribe orders.*    → orders.created, orders.paid (1단 차이만)
subscribe orders.>    → orders.created, orders.paid, orders.shipped.us, ...

Request-Reply (Core NATS 의 강점)

sequenceDiagram
    autonumber
    participant R as Requester
    participant N as NATS
    participant S as Service

    S->>N: SUB shop.getItem
    R->>N: PUB shop.getItem (reply=INBOX.abc)
    N->>S: deliver
    S->>S: 처리
    S->>N: PUB INBOX.abc {결과}
    N->>R: deliver

RPC 가 Pub/Sub 위에 자연스럽게.
load balancing = 같은 subject 의 queue group 으로.

// Queue group: 여러 service 가 같은 subject 구독, 한 명에게 전달
nats.subscribe('shop.getItem', { queue: 'shop' }, (msg) => { ... });

JetStream 메시지 흐름

flowchart LR
    P[Producer] -->|PUB orders.>| JS[(JetStream Stream)]
    JS --> Consumer1[Push consumer]
    JS --> Consumer2[Pull consumer]
    JS --> Consumer3[Durable consumer]

Consumer 타입	의미
Push	broker 가 능동 push
Pull	consumer 가 poll
Ephemeral	임시 (재접속 시 처음부터)
Durable	진행 상태 영속

NATS KV / Object Store

JetStream 위 추가 추상:

// KV
const kv = await jsm.views.kv('config');
await kv.put('feature.x', 'enabled');
const val = await kv.get('feature.x');

// Object Store
const os = await jsm.views.os('images');
await os.put('logo.png', readableStream);

Redis 같은 KV, S3 같은 object store 가 NATS 안에 통합. 작은 인프라 친화.

NATS vs Kafka vs RabbitMQ

항목	NATS	Kafka	RabbitMQ
바이너리 크기	10 MB	수백 MB	수십 MB
운영 복잡도	낮음	높음	중간
처리량	매우 높음	매우 높음	중간
Latency	최저	중간	낮음
영속	옵션 (JS)	항상	옵션
Replication	빌트인 (JS)	빌트인	mirror queue
학습 곡선	낮음	높음	중간

Edge / IoT 패턴

flowchart TB
    subgraph Edge["Edge devices (수천 ~ 수백만)"]
        E1[Sensor 1]
        E2[Sensor 2]
        EN[Sensor N]
    end
    Edge --> NEdge[NATS edge cluster]
    NEdge --> Leaf[Leaf node]
    Leaf --> NCloud[NATS central cluster]
    NCloud --> Apps[Apps / Analytics]

Leaf node = edge → central 의 경량 게이트웨이.
bandwidth 최적: 같은 메시지 한 번만 전송.
오프라인 buffer + 재연결 시 sync.

적합 / 부적합

flowchart TD
    Good[적합]
    Good --> G1[마이크로서비스 사이 메시징]
    Good --> G2[Edge / IoT]
    Good --> G3[Real-time telemetry]
    Good --> G4["작은 영속 큐 (JS)"]
    Bad[부적합]
    Bad --> B1["복잡한 라우팅 (Topic exchange 같은)"]
    Bad --> B2[수개월 retention 의 거대 로그]

흔한 함정

[!WARNING]

Core NATS 의 손실 가능성 무시 = subscriber 없으면 조용히 사라짐. JS 로 가야.

JS replica 1 = 노드 다운 시 손실. RF 3 권장.

Wildcard 과도 사용 = > 가 모든 메시지 받음 → 클라이언트 부하.

Subject 표준화 없음 = 작은 팀에서는 OK, 큰 팀에서는 충돌 / 중복. 네임스페이스 가이드 필요.

[Distributed] RabbitMQ: exchange, queue, routing key

koa (김신건) — Thu, 25 Jun 2026 00:00:00 GMT

정의

RabbitMQ = AMQP 0.9.1 기반 traditional message broker. exchange → queue 라우팅, workload distribution, publish-subscribe. Kafka 보다 작은 단위 메시지 라우팅에 강함.

구조

flowchart LR
    P[Producer] --> Exch[Exchange]
    Exch -->|routing key 매칭| Q1[Queue 1]
    Exch -->|routing key 매칭| Q2[Queue 2]
    Exch -->|routing key 매칭| Q3[Queue 3]
    Q1 --> C1[Consumer 1]
    Q2 --> C2[Consumer 2]
    Q3 --> C3[Consumer 3]

컴포넌트	의미
Producer	메시지 발행자
Exchange	routing 규칙. 4 종류
Queue	메시지 저장소
Binding	exchange ↔ queue 연결 + key
Consumer	소비자

Exchange 4 종류

flowchart TB
    Direct[Direct<br/>routing_key 정확 일치]
    Topic[Topic<br/>*.error.* 와일드카드]
    Fanout[Fanout<br/>모든 queue 로 broadcast]
    Headers[Headers<br/>header attribute 매칭]

1. Direct

publish key=ORDER.PAID → queue:paid (binding key=ORDER.PAID)
publish key=ORDER.SHIPPED → queue:shipped (binding key=ORDER.SHIPPED)

2. Topic

publish key=order.paid.us → matches "order.*.us", "order.paid.*", "#"

와일드카드	의미
`*`	단어 1개
`#`	0+ 단어

3. Fanout

모든 binding 된 queue 로 무조건 복사

Pub/Sub fan-out 의 정통.

4. Headers

header { type: "order", region: "us" } 매칭

메시지 보장

sequenceDiagram
    P->>Broker: publish
    Broker->>Disk: persistent? → disk write
    Broker->>P: confirm
    P->>P: confirm 받음 → 안전
    Broker->>C: deliver
    C->>C: 처리
    C->>Broker: ack
    Broker->>Broker: ack 받음 → 제거

설정	의미
`persistent` 메시지	broker 재시작 후에도 보존
`durable` queue	broker 재시작 후 queue 유지
`publisher confirms`	broker 의 받음 확인
`consumer ack`	처리 완료 확인
`mandatory` flag	routing 안 되면 unroutable 반환

[!IMPORTANT] 모든 4가지 켜야 실제 at-least-once 보장. 하나라도 빠지면 손실 가능.

DLQ (Dead Letter Queue)

flowchart LR
    Q1[primary queue] -->|reject 또는 ttl 만료| DLX[Dead Letter Exchange]
    DLX --> DLQ[DLQ]
    DLQ --> Inspect[운영자 검사]

trigger	동작
reject (requeue=false)	DLQ 로
TTL 만료	DLQ 로
queue 길이 한도 초과	DLQ 로

자동 retry 패턴:

flowchart LR
    Q1[primary] -->|fail| DLQ
    DLQ -->|ttl 5s| Retry1[retry-1]
    Retry1 -->|fail| DLQ2
    DLQ2 -->|ttl 30s| Retry2[retry-2]
    Retry2 -->|fail| Final[parking lot]

RabbitMQ vs Kafka

항목	RabbitMQ	Kafka
모델	큐 + exchange 라우팅	append-only log
처리량	수만 ~ 수십만/s	수백만/s
Latency	낮음 (ms)	좀 더 큼
영속	옵션	항상
재처리	한 번 소비 후 사라짐	offset 으로 임의 재생
라우팅	유연 (exchange 패턴)	단순 (topic + partition)
사용	task queue, request-reply	event log, stream

RabbitMQ Streams (Kafka 흉내)

3.9+ 의 Stream 큐 타입. append-only log + replica + 재생 가능.

# 또는 declare 시
queue.declare("my-stream", arguments={ "x-queue-type": "stream" })

Kafka 와 비슷한 흐름. RabbitMQ 안에서 durable log + fan-out 임의 시점.

흔한 함정

[!WARNING]

persistent 없이 신뢰 = broker 재시작 시 모든 메시지 손실.

prefetch 너무 큼 = 한 consumer 가 수천 메시지 lock → 다른 consumer 가 굶음. prefetch=10~100 권장.

DLQ 없이 reject = 메시지 영구 손실 또는 무한 재시도.

auto_ack=true = consumer 다운 시 처리 안 한 메시지가 ack 됨 (손실).

[Pattern] API Gateway: BFF, 라우팅, auth, rate limit

koa (김신건) — Thu, 25 Jun 2026 00:00:00 GMT

정의

API Gateway = 클라이언트와 마이크로서비스 사이의 단일 진입점. 라우팅, auth, rate limit, transformation, monitoring 의 cross-cutting 책임 을 모음.

역할

flowchart LR
    Client[Mobile / Web / IoT] --> GW[API Gateway]
    GW -->|/users/*| US[User Service]
    GW -->|/orders/*| OS[Order Service]
    GW -->|/payments/*| PS[Payment Service]
    GW -.cross-cutting.-> Auth[Auth]
    GW -.cross-cutting.-> RL[Rate Limit]
    GW -.cross-cutting.-> Log[Logging]
    GW -.cross-cutting.-> Cache[Cache]
    GW -.cross-cutting.-> Transform[Request/Response transform]

책임 카탈로그

책임	예시
라우팅	path / header / host 기준
인증 / 인가	JWT 검증, OAuth, API key
Rate limiting	per-API key, per-IP
Transformation	request/response 변환 (gRPC↔REST)
캐싱	응답 캐시
Load balancing	백엔드 분산
Circuit breaker	백엔드 다운 시 차단
Logging / metrics	중앙 집계
WAF	SQLi, XSS 차단
TLS termination	인증서 관리
Versioning	URL / 헤더 기반 분기

BFF (Backend For Frontend)

flowchart LR
    iOS[iOS App] --> iOSGW[iOS BFF]
    Web[Web App] --> WebGW[Web BFF]
    Android[Android App] --> AnGW[Android BFF]
    iOSGW & WebGW & AnGW --> Services[(공통 services)]

각 클라이언트 종류마다 별도 gateway. 클라이언트 별 응답 형식 / 페이지네이션 / 압축 차이 흡수. 모바일 = 작은 응답, 웹 = 큰 응답.

API Gateway vs Service Mesh

항목	API Gateway	Service Mesh
위치	외부 ↔ 내부 경계 (north-south)	내부 ↔ 내부 (east-west)
책임	인증, transformation, public API	mTLS, retry, circuit, observability
클라이언트 인지	직접 호출	sidecar 자동
예	Kong, AWS API Gateway, Envoy	Istio, Linkerd

[!NOTE] 둘 다 운영하는 경우 가 흔하다. gateway 가 north-south, mesh 가 east-west.

도구 비교

도구	종류	강점
Kong	OSS gateway	plugin 생태계
Tyk	OSS gateway	옵션
Envoy	Proxy	gRPC, L7, mesh 토대
AWS API Gateway	Managed	Lambda 통합
Cloudflare Workers	Edge	글로벌
Apigee	Enterprise (Google)	엔터프라이즈
Apollo Router	GraphQL	federation

패턴: GraphQL Federation Gateway

flowchart TB
    Client --> Router[Apollo Router]
    Router --> A[User subgraph]
    Router --> B[Order subgraph]
    Router --> C[Payment subgraph]

자세한 건 [[graphql]] 참고.

흔한 함정

[!WARNING]

Gateway 가 모든 비즈니스 로직 흡수 = monolith 의 재림. cross-cutting 만.

단일 gateway 의 bottleneck = HA + auto-scaling 필수.

Auth 검증 백엔드 마다 다시 = gateway 가 검증 → 백엔드는 trust. 단 zero-trust 환경에서는 백엔드도 검증.

Rate limit 의 분산 상태 = 단일 노드 카운터 = race. 중앙 store (Redis) + sliding window.

[Pattern] CQRS: Command / Query 분리, read model

koa (김신건) — Thu, 25 Jun 2026 00:00:00 GMT

정의

CQRS (Command Query Responsibility Segregation) = 쓰기 모델 과 읽기 모델 을 분리. 같은 데이터를 다른 형태 로 저장 / 조회.

[!IMPORTANT] CQRS 는 쓰기 / 읽기 모델 분리 라는 추상 패턴. 반드시 다른 DB 일 필요는 없다. 대부분 시작 단계는 같은 DB + 다른 모델.

동기

flowchart LR
    Trad[전통 CRUD]
    Trad --> ProbW[복잡한 비즈니스 로직 + 정규화 DB]
    Trad --> ProbR[복잡한 join 으로 화면 그리기]
    CQRS[CQRS]
    CQRS --> Write[Write: 정규화, 트랜잭션, 비즈니스 규칙]
    CQRS --> Read[Read: 화면 친화, denormalized, 빠른 조회]

CRUD 의 읽기 / 쓰기 사용 패턴이 매우 다른 워크로드 (대시보드, 추천, 검색) 에서 효과적.

기본 구조

flowchart TB
    Cmd[Command<br/>CreateOrder, ConfirmOrder] --> CH[Command Handler]
    CH --> WM[(Write Model<br/>정규화, 트랜잭션)]
    WM -->|event| EH[Event Handler / Projection]
    EH --> RM[(Read Model<br/>denormalized, optimized)]
    Query[Query<br/>GetOrderSummary] --> QH[Query Handler]
    QH --> RM

항목	Command Side	Query Side
입력	비즈니스 의도 (Command)	정보 요청 (Query)
검증	비즈니스 규칙	권한만
결과	변경 사실 (성공/실패)	데이터
모델	정규화 (3NF)	denormalized
DB	RDB 가 일반	다양 (RDB, ES, Redis)
일관성	강	보통 eventual

예시: 전자상거래

-- Write Model (정규화)
TABLE orders (id, user_id, status, ...);
TABLE order_items (id, order_id, product_id, qty, price);
TABLE products (id, name, ...);

-- Read Model (denormalized, 화면 친화)
TABLE order_summary_view (
  order_id, user_name, total, item_count,
  status_label, created_at, items_json
);

읽기 1 쿼리:

SELECT * FROM order_summary_view WHERE order_id = ?;

쓰기 - 정상 트랜잭션 + event 발행:

BEGIN;
INSERT INTO orders ...;
INSERT INTO order_items ...;
INSERT INTO outbox (event) VALUES ('OrderCreated', ...);
COMMIT;

이후 event handler 가 order_summary_view 갱신.

Event Sourcing 과 자주 같이

flowchart LR
    Cmd[Command] --> Agg[Aggregate]
    Agg -->|emit event| ES[(Event Store)]
    ES -->|project| V1[(Read View 1)]
    ES -->|project| V2[(Read View 2)]
    ES -->|project| V3[(Read View 3)]
    Query --> V1 & V2 & V3

자세한 건 [[event-sourcing]].

Read Model 종류

Read Model	적합
Materialized view (DB)	같은 RDB 안
ElasticSearch / OpenSearch	검색 + aggregation
Redis	작은 hot data
Cassandra	시계열 / 대용량
GraphQL cache	API 응답 캐시
클라이언트 IndexedDB	offline-first

Eventual Consistency

sequenceDiagram
    User->>API: POST /orders (command)
    API->>WriteDB: INSERT
    WriteDB-->>API: OK
    API-->>User: 200 OK (order_id)
    Note over API,ReadDB: 비동기 projection 진행
    User->>API: GET /orders/123 (query)
    API->>ReadDB: SELECT
    ReadDB-->>API: NOT FOUND? (projection lag)

[!CAUTION] 방금 만든 주문이 안 보이는 UX 함정. 해결책:

짧은 lag (수 ms) 보장 + UI 가 낙관적 표시

write 후 즉시 같은 transaction 으로 read 시 write DB 우회

작성자 본인은 강 일관성, 다른 사람은 eventual (read-your-writes)

언제 CQRS? (안 쓸 때가 더 많다)

flowchart TD
    Q1{비즈니스 도메인 복잡?}
    Q1 -->|아니오| Simple[CRUD 충분]
    Q1 -->|예| Q2{읽기 / 쓰기 패턴 매우 다름?}
    Q2 -->|아니오| Simple
    Q2 -->|예| Q3{팀이 ES + 분산 시스템 이해?}
    Q3 -->|아니오| Risk[학습 비용 큼 → 천천히]
    Q3 -->|예| CQRS[CQRS 시작]

[!IMPORTANT] 대부분의 앱은 CQRS 가 과한 솔루션. 진짜 도움 되는 곳 (큰 e-commerce, 트레이딩 시스템, 큰 SaaS 대시보드) 가 아니면 모듈 모놀리스 + 일부 read model 정도면 충분.

단순 CQRS (가벼운 형태)

flowchart LR
    Cmd[Command Handler<br/>POST /orders] --> Write[(DB)]
    Write -->|trigger / event| Mat[Materialized View<br/>갱신]
    Query[Query Handler<br/>GET /orders/dashboard] --> Mat

같은 DB.
materialized view 또는 summary table.
별도 인프라 없이 80% 의 효과.

흔한 함정

[!WARNING]

모든 곳에 CQRS = 단순 CRUD 도 분리. 복잡도 폭증.

Projection 동기 실행 = read model 갱신이 write 막음. async + idempotent.

Read-your-writes 무시 = 사용자가 방금 한 일을 못 봄 UX.

Read model 재구성 어려움 = event log 없으면 replay 불가. ES + CQRS 가 자주 묶이는 이유.

[Pattern] Event Sourcing: 상태 대신 이벤트 누적

koa (김신건) — Thu, 25 Jun 2026 00:00:00 GMT

정의

Event Sourcing = 현재 상태 대신 과거 이벤트 시퀀스 를 저장. 현재 상태 = event 모두 replay 한 결과.

전통: state = { balance: 100 }
ES:   events = [Deposited(50), Deposited(60), Withdrawn(10)]
      state = events.reduce(apply) = { balance: 100 }

핵심 약속

과거 모든 변화 기록. 감사 / 디버깅 / 시간 여행 자유.
읽기 모델 자유 (어떻게든 projection).
replay 로 새 view 생성 (옛 데이터에서 새 통찰).
비파괴. 옛 이벤트는 불변.

구조

flowchart LR
    Cmd[Command<br/>Deposit 50] --> Agg[Aggregate]
    Agg -->|emit| Event["Deposited(50)"]
    Event --> Store[(Event Store<br/>append-only)]
    Store -->|project| V1[(Balance View)]
    Store -->|project| V2[(Audit View)]
    Store -->|project| V3[(Search View)]

Event Store

이벤트 = 불변 사실. 형식:

{
  "event_id": "evt_abc",
  "aggregate_id": "account_42",
  "aggregate_type": "Account",
  "event_type": "Deposited",
  "version": 5,
  "payload": { "amount": 50, "currency": "USD" },
  "metadata": { "user_id": "...", "correlation_id": "..." },
  "occurred_at": "2026-06-25T12:00:00Z"
}

Store	특징
Kafka	log + retention
EventStoreDB	ES 전용
PostgreSQL	append-only 테이블 + outbox
DynamoDB	partition key = aggregate_id
Axon	Java 프레임워크

Replay (재계산)

sequenceDiagram
    autonumber
    participant App
    participant Store as Event Store
    App->>Store: load events for aggregate_id=42
    Store-->>App: [e1, e2, e3, e4, e5]
    App->>App: state = e1.apply(empty)<br/>state = e2.apply(state)<br/>...
    Note over App: state 복원 완료

Snapshot

이벤트 수 만이면 replay 가 느림. 주기적 snapshot 저장:

flowchart LR
    Store[(Event Store)] --> Snap[(Snapshot Store)]
    Note1["Snapshot at version 1000:<br/>{ balance: 5000 }"]
    Load[Load aggregate] --> Snap
    Snap -->|version 1000 부터| Replay[event 1001 ~ 현재 replay]

def load_aggregate(id):
    snapshot = snapshot_store.latest(id)
    events = event_store.from_version(id, snapshot.version)
    state = snapshot.state
    for e in events:
        state = e.apply(state)
    return state

CQRS 와의 자연 결합

flowchart TB
    Cmd --> Write[Write side]
    Write --> Store[(Event Store)]
    Store -->|stream| P1[Projection 1] --> View1[(Read View 1)]
    Store -->|stream| P2[Projection 2] --> View2[(Read View 2)]
    Store -->|stream| P3[Projection 3] --> View3[(Read View 3)]
    Query --> View1 & View2 & View3

자세한 건 [[cqrs]].

새 View 추가

기존 데이터에서 새 인사이트 가 필요할 때:

sequenceDiagram
    Dev->>Code: 새 projection 함수 추가
    Code->>Store: from version 0 부터 replay
    Store-->>Code: 모든 이벤트
    Code->>NewView: 새 view 채우기 (수 시간 ~ 일)
    Note over Code,NewView: 이후 실시간 stream 으로 유지

[!IMPORTANT] 이게 ES 의 가장 큰 매력. 과거에 안 묻던 질문 을 나중에 데이터로 만들 수 있다.

적합 / 부적합

flowchart TD
    Good[적합]
    Good --> G1["감사 추적 필수 (금융, 의료)"]
    Good --> G2[과거 시점 상태 조회]
    Good --> G3["복잡 비즈니스 (주문 흐름)"]
    Good --> G4[CQRS 가 자연스러운 도메인]
    Bad[부적합]
    Bad --> B1[단순 CRUD]
    Bad --> B2["GDPR 의 *잊혀질 권리* (이벤트 불변과 충돌)"]
    Bad --> B3[빠른 prototype]

함정: 이벤트 진화

v1: Deposited(amount: int)
v2: Deposited(amount: int, currency: string)   ← currency 추가

옛 이벤트는 currency 가 없다. 처리 시:

전략	의미
Default value	옛 이벤트에 currency=“USD” 가정
Up-cast	load 시 옛 → 새 형태로 변환
Lazy migration	처리 시점에 보강
Re-write event (안 권장)	불변 원칙 위반

flowchart TD
    Q[GDPR: 사용자 데이터 삭제 요구]
    Q --> Issue[ES: 이벤트는 불변 → 어떻게 지움?]
    Issue --> S1["1. Crypto-shredding: 개인정보 *암호화*, key 만 삭제"]
    Issue --> S2["2. Event redaction: 특정 필드 null 처리"]
    Issue --> S3["3. 별도 저장: 개인정보는 가변 DB, 이벤트는 reference"]

흔한 함정

[!WARNING]

모든 도메인에 ES = 단순 CRUD 까지 복잡 모델. 진짜 도메인 가치 있는 곳에만.

이벤트 schema 영구 보존 안 함 = 1년 뒤 옛 이벤트 해석 불가. 스키마 진화 정책.

이벤트 크기 폭증 = 작은 이벤트 + 정기 snapshot. 큰 binary 는 reference.

Aggregate 경계 잘못 = aggregate 가 너무 크면 concurrent write 충돌, 너무 작으면 일관성 사라짐.

[Pattern] Idempotency Keys: 중복 요청 안전 처리

koa (김신건) — Thu, 25 Jun 2026 00:00:00 GMT

정의

Idempotency = 같은 요청을 N번 보내도 결과가 1번과 동일. 분산 시스템 / 결제 / API 의 안전망.

[!IMPORTANT] 네트워크는 항상 timeout / retry. 진짜 exactly-once 는 불가능 → at-least-once + idempotent 가 현실적 정답.

HTTP 의 idempotent method

Method	Idempotent
GET	O
HEAD	O
OPTIONS	O
PUT	O
DELETE	O
POST	X (기본)
PATCH	X (대개)

POST 의 비-멱등성 이 결제 중복 같은 사고의 근원.

Idempotency-Key Header

Stripe / Square / PayPal 등이 표준화:

POST /v1/charges HTTP/1.1
Authorization: Bearer sk_...
Idempotency-Key: 7f4d8e2a-c-3a-4e-9f-1234567890ab
Content-Type: application/json

{"amount": 5000, "currency": "usd", "customer": "cus_..."}

서버 응답:

1번째 호출: 200 OK (실제 처리)
2번째 호출 (같은 key): 200 OK (옛 응답 그대로)

서버 구현

sequenceDiagram
    autonumber
    participant Client
    participant API
    participant Store as Idempotency Store
    participant DB

    Client->>API: POST + Idempotency-Key: abc
    API->>Store: GET key abc
    alt 처음
        Store-->>API: not found
        API->>Store: SET key abc IN_PROGRESS
        API->>DB: 실제 처리
        DB-->>API: 결과
        API->>Store: SET key abc COMPLETED + 응답
        API-->>Client: 응답
    else 옛 응답 있음
        Store-->>API: COMPLETED + 옛 응답
        API-->>Client: 같은 옛 응답 (실제 처리 없음)
    else 진행 중
        Store-->>API: IN_PROGRESS
        API-->>Client: 409 Conflict (같은 key 중복)
    end

def idempotent_post(key, request, handler):
    cached = store.get(key)
    if cached and cached.status == "completed":
        return cached.response

    if cached and cached.status == "in_progress":
        raise Conflict("Same key in progress")

    store.set(key, "in_progress", ttl=24*3600)
    try:
        response = handler(request)
        store.set(key, "completed", response=response, ttl=24*3600)
        return response
    except Exception:
        store.delete(key)   # 또는 "failed" 로 표시
        raise

Store 선택

Store	적합
Redis	빠름, TTL 자동
PostgreSQL	트랜잭션 친화
DynamoDB	분산 + TTL

[!TIP] PostgreSQL 의 UNIQUE constraint + ON CONFLICT 가 가장 단순. 결제 같이 강한 일관성 필요할 때.

CREATE TABLE idempotency_keys (
  key TEXT PRIMARY KEY,
  request_hash BYTEA NOT NULL,
  response JSONB,
  status TEXT,
  expires_at TIMESTAMPTZ
);

INSERT INTO idempotency_keys (key, request_hash, status)
VALUES (?, ?, 'in_progress')
ON CONFLICT (key) DO NOTHING
RETURNING ...;

Request Hashing (재시도 안전)

def request_hash(req):
    return sha256(req.method + req.url + req.body).hexdigest()

같은 key + 다른 body = 수상. 거절 (400) 또는 옛 응답.
같은 key + 같은 body = 재시도. 옛 응답.

TTL 정책

기간	적합
24시간	Stripe 표준
7일	더 안전
영구	결제처럼 극한 안전

짧으면 재시도 보호 부족. 길면 store 부담.

분산 / 큐의 idempotency

flowchart LR
    P[Producer] -->|publish + msg_id| Broker
    Broker --> C[Consumer]
    C -->|이미 처리?| Inbox[(Inbox table)]
    Inbox -->|YES| Skip
    Inbox -->|NO| Process[처리 + 기록]

자세한 건 [[outbox-pattern]] 의 Inbox.

멱등한 작업 만드는 패턴

작업	멱등으로 만드는 방법
이메일 발송	deduplication store + 발송 전 체크
DB INSERT	UNIQUE constraint + ON CONFLICT
계좌 송금	transaction_id 컬럼 + UNIQUE
Webhook 수신	event_id + 처리 표시
API 호출	Idempotency-Key 헤더

흔한 함정

[!WARNING]

클라이언트가 매번 새 key 생성 = idempotency 의미 없음. retry 시 같은 key 재사용.

key 충돌 = UUID v4 사용. 클라이언트 라이브러리가 자동 생성.

TTL 너무 짧음 = 24시간 뒤 재시도 시 중복 처리.

in-progress 처리 = 그동안 동일 key 가 또 오면 대기 vs 거절 정책. 보통 409.

[Pattern] Microservices vs Monolith: 언제 분리, 언제 통합

koa (김신건) — Thu, 25 Jun 2026 00:00:00 GMT

정의

	Monolith	Modular Monolith	Microservices
배포 단위	1개	1개 (모듈 명확)	N개
데이터	단일 DB	단일 DB (스키마 분리)	DB per service
통신	함수 호출	함수 호출	네트워크 (HTTP/gRPC)
운영 복잡도	낮음	낮음	높음
스케일링	전체 함께	전체 함께	service 별 독립
장애 격리	약함	약함	강함 (이상적)
적합 팀	< 30	< 100	100+

결정 트리

flowchart TD
    Q1{팀 크기}
    Q1 -->|< 10| Mono[Monolith]
    Q1 -->|10-50| Q2{성장 속도?}
    Q2 -->|느림| Mono
    Q2 -->|빠름| MM[Modular Monolith]
    Q1 -->|50-200| MM
    Q1 -->|200+| MS[Microservices]
    MM -->|"진짜 필요해지면"| MS

시작은 Monolith (Fowler 의 “Monolith First”)

flowchart LR
    Start[새 프로젝트] --> Mono[Monolith로 시작]
    Mono --> Grow[성장 + 도메인 명확]
    Grow --> MM[Modular Monolith]
    MM --> Carve[필요시 service 분리]
    Carve --> MS[Microservices 일부]

[!IMPORTANT] 대부분의 새 프로젝트는 monolith 로 시작 이 정답. 마이크로서비스로 시작 한 팀이 2년 후 distributed monolith 가 되는 사례가 압도적.

Microservices 가 진짜 도움될 때

flowchart TD
    Q1{독립 배포 절실?}
    Q1 -->|예| C1[조건 1 ✓]
    Q2{팀 별 자율성 절실?}
    Q2 -->|예| C2[조건 2 ✓]
    Q3{스케일 차이 큼?}
    Q3 -->|예| C3[조건 3 ✓]
    C1 & C2 & C3 -->|모두 ✓| Go[Microservices 도입]

Distributed Monolith (안티 패턴)

flowchart LR
    A[Service A] -->|동기 호출| B[Service B]
    B -->|동기 호출| C[Service C]
    C -->|동기 호출| D[Service D]
    Note1[하나 다운 = 전체 다운]

증상:

여러 service 가 함께 배포 되어야 함 (calling contract 변경 시)
한 service 다운 = 전체 다운
분산의 비용 + monolith 의 결합 동시
코드 변경 영향이 service 경계 넘김

[!CAUTION] 마이크로서비스의 최악의 결과. monolith 보다 모든 면에서 나쁨.

Service Boundary 가르는 기준

flowchart TD
    Best[좋은 boundary]
    Best --> B1["Domain (DDD bounded context)"]
    Best --> B2["Team ownership (Conway's Law)"]
    Best --> B3[데이터 모델 자연 분리]
    Bad[나쁜 boundary]
    Bad --> X1["기술 계층 (API / DB / UI)"]
    Bad --> X2["유사 데이터 기준 (DB 테이블 1:1)"]
    Bad --> X3["CRUD 단위 (UserService, OrderService 의 진짜 분리는 어디서?)"]

Conway’s Law

“시스템 구조는 그것을 만든 조직의 의사소통 구조를 닮는다”

flowchart TB
    Team1["Team A<br/>(독립 의사소통)"] --> Service1[Service A]
    Team2["Team B<br/>(독립 의사소통)"] --> Service2[Service B]
    Team3["Team C<br/>(독립 의사소통)"] --> Service3[Service C]
    Team1 -.협업.-> Team2
    Service1 -.API.-> Service2

팀 경계와 service 경계의 일치 가 Conway’s Law 의 실용적 활용. 한 service 가 두 팀에 걸치면 운영 사고.

Inverse Conway Maneuver

반대로 service 구조부터 정해 → 팀 구조 맞추기. 큰 조직 재편 에서 사용.

분리 비용 카탈로그

flowchart TB
    Cost[Microservices 의 추가 비용]
    Cost --> Net[네트워크 호출]
    Cost --> Obs["관측성 (Tracing 필수)"]
    Cost --> Auth[mTLS / Service Mesh]
    Cost --> Data["데이터 일관성 (Saga)"]
    Cost --> Deploy[K8s, CI/CD 복잡도]
    Cost --> Test[Contract / E2E 테스트]
    Cost --> Skill[엔지니어 학습 비용]

모듈 모놀리스 (Modular Monolith)

flowchart TB
    subgraph App[Single deployable]
        U[User module]
        O[Order module]
        P[Payment module]
    end
    U -.interface only.-> O
    O -.interface only.-> P
    App --> DB[(단일 DB<br/>스키마 분리)]

모듈 간 직접 호출 금지. interface만.
같은 DB, 다른 스키마.
나중에 service 분리 쉬움.
대부분의 회사가 결국 여기서 멈춤 (충분).

흔한 함정

[!WARNING]

너무 일찍 분리 = 도메인 잘못 잡고 분리 후 재경계. 가장 큰 후회.

DB 공유 = “Service 단위 분리” 가 DB 결합 으로 무의미. 각 service 자기 DB.

분산 트랜잭션 (2PC) = 마이크로서비스의 영혼. Saga 패턴으로 대체.

shared library 의 영원한 결합 = service A 가 라이브러리 v2 로 못 올라가면 모든 service 정체.

[Pattern] Outbox Pattern: DB + 메시지의 원자성

koa (김신건) — Thu, 25 Jun 2026 00:00:00 GMT

정의

Outbox Pattern = DB 변경 + 메시지 발행 의 원자성 보장. 이중 쓰기 (dual write) 문제 의 표준 해결.

문제: Dual Write

sequenceDiagram
    autonumber
    participant App
    participant DB
    participant Broker as Kafka/RabbitMQ

    App->>DB: BEGIN<br/>INSERT order<br/>COMMIT
    DB-->>App: OK
    App->>Broker: publish OrderCreated
    Note over App,Broker: ✗ App crash, 또는<br/>Broker timeout
    Broker--xApp: 응답 없음
    Note over DB,Broker: DB 는 INSERT 됨<br/>이벤트는 안 감 → *불일치*

시나리오	결과
DB OK + Publish OK	일관성
DB OK + Publish fail	불일치 (DB 만 변경)
DB fail + Publish OK	불일치 (이벤트만 갔음)
둘 다 fail	OK (취소)

→ 두 시스템을 한 번에 일관 시키는 건 불가능. 2PC 는 비현실적.

해결: Outbox 테이블

flowchart LR
    App -->|단일 트랜잭션| DB
    DB --> Orders[(orders)]
    DB --> Outbox[(outbox)]
    Outbox -.relay.-> Broker[(Broker)]

BEGIN;
  INSERT INTO orders (id, ...) VALUES (?, ...);
  INSERT INTO outbox (event_type, payload, aggregate_id)
    VALUES ('OrderCreated', ?, ?);
COMMIT;
-- 한 트랜잭션 = 원자성!

이후 별도 프로세스 가 outbox 를 읽고 broker 로 publish.

2가지 Relay 방식

1. Polling Publisher

flowchart LR
    Outbox[(outbox)] -.SELECT unpublished.-> Relay[Relay process]
    Relay -->|publish| Broker
    Relay -->|UPDATE published=true| Outbox

while True:
    rows = db.query("SELECT * FROM outbox WHERE published=false LIMIT 100")
    for row in rows:
        broker.publish(row.event)
        db.execute("UPDATE outbox SET published=true WHERE id=?", row.id)
    time.sleep(0.1)

구현 간단.
DB 부담 (polling).
Latency ≈ polling 주기.

2. CDC (Change Data Capture)

flowchart LR
    DB[(DB)] -->|WAL / binlog| CDC[Debezium / Maxwell]
    CDC --> Kafka[(Kafka)]
    Kafka -->|topic| Consumers

DB 의 transaction log (PostgreSQL WAL / MySQL binlog) 를 실시간 캡처.

도구	DB
Debezium	PG, MySQL, MongoDB, Oracle 등
Maxwell	MySQL
AWS DMS	다양
Striim	다양

[!IMPORTANT] Outbox + CDC 는 2026 시점 마이크로서비스 메시징의 표준. 더 이상 애플리케이션 코드에서 publish 하지 않는다.

Outbox 테이블 디자인

CREATE TABLE outbox (
  id BIGSERIAL PRIMARY KEY,
  aggregate_type TEXT NOT NULL,        -- 'Order'
  aggregate_id TEXT NOT NULL,           -- 'order_42'
  event_type TEXT NOT NULL,             -- 'OrderCreated'
  payload JSONB NOT NULL,
  occurred_at TIMESTAMPTZ DEFAULT NOW(),
  published BOOLEAN DEFAULT false,
  published_at TIMESTAMPTZ
);

CREATE INDEX idx_outbox_unpublished
  ON outbox(id) WHERE published = false;

[!TIP] partial index 로 unpublished 만 빠른 SELECT.

처리 후 정리

flowchart TD
    P[Outbox 너무 큼?]
    P --> O1[옵션 1: published row 즉시 DELETE]
    P --> O2[옵션 2: 별도 archive 테이블]
    P --> O3["옵션 3: TTL (며칠 보관)"]

CDC 가 binlog stream 위주 라 published 컬럼 자체 필요 없음. Debezium 이 INSERT 이벤트 그대로 전송.

메시지 순서 보장

flowchart LR
    Tx1[Tx 1: INSERT outbox id=100] --> Order
    Tx2["Tx 2: INSERT outbox id=99 (먼저 시작했지만 commit 늦음)"]
    Tx2 --> Order
    Note["DB ID 순 ≠ commit 순"]

[!CAUTION] concurrent transaction 때문에 id 순서 ≠ commit 순서. strict 순서 보장 이 필요하면 aggregate ID 별 partition 으로.

At-least-once + Idempotency

Outbox + relay 는 at-least-once. 중복 발행 가능 (relay 가 publish 후 update 전 crash).

→ consumer 가 idempotent 처리. 자세한 건 [[idempotency-keys]].

Inbox Pattern (반대 방향)

flowchart LR
    Broker -->|consume| Inbox[(inbox)]
    Inbox -->|단일 트랜잭션| DB
    DB -->|이미 처리?| Skip[중복 skip]

수신 측의 멱등 보장. Outbox 와 대칭.

흔한 함정

[!WARNING]

*UPDATE published=true 와 publish 가 별도 transaction = relay crash 시 중복 발행. at-least-once 인정 + consumer idempotent.

Outbox 의 순서 무시 = 다운스트림이 순서 가정. partition / sequence 명시.

Outbox 가 너무 큼 = 정리 필요. 보관 정책.

SELECT FOR UPDATE SKIP LOCKED 없이 multi worker = 같은 row 동시 처리 → 중복.

[Pattern] Saga: 분산 트랜잭션의 보상 흐름

koa (김신건) — Thu, 25 Jun 2026 00:00:00 GMT

정의

Saga = 여러 service 의 로컬 트랜잭션 을 연결한 긴 흐름. 한 단계 실패 시 이전 단계의 보상 (compensating) 트랜잭션 으로 논리적 롤백.

[!IMPORTANT] Saga 는 ACID 트랜잭션이 아니다. 분산 환경에서 2PC (XA) 가 비현실적이라 eventually consistent + 보상 으로 대체.

시나리오: 주문

sequenceDiagram
    autonumber
    participant O as Order Service
    participant P as Payment Service
    participant I as Inventory Service
    participant S as Shipping Service

    O->>O: T1: 주문 생성 (pending)
    O->>P: T2: 결제 요청
    P-->>O: 결제 완료
    O->>I: T3: 재고 차감
    I-->>O: 차감 완료
    O->>S: T4: 배송 요청
    S-->>O: 배송 시작
    O->>O: T5: 주문 confirmed

실패 시 보상:

sequenceDiagram
    O->>P: T2 결제
    P-->>O: ✓
    O->>I: T3 재고
    I-->>O: 실패 (재고 부족)
    O->>P: C2: 결제 환불 (보상)
    O->>O: C1: 주문 취소 (보상)

단계	Compensating
T1 주문 생성	C1 주문 취소
T2 결제	C2 환불
T3 재고 차감	C3 재고 복원
T4 배송	C4 배송 취소

두 스타일: Choreography vs Orchestration

1. Choreography (이벤트 기반)

flowchart LR
    O[Order] -->|OrderCreated| P[Payment]
    P -->|PaymentSucceeded| I[Inventory]
    I -->|StockReserved| S[Shipping]
    S -->|Shipped| O
    P -->|PaymentFailed| O
    I -->|StockUnavailable| P

각 service 가 event 듣고 자기 일.
중앙 제어자 없음.
유연, 낮은 결합.
흐름 추적 어려움 (어디까지 갔는지).

2. Orchestration (중앙 코디네이터)

flowchart LR
    Coord[Saga Orchestrator] --> O[Order]
    O -->|성공| Coord
    Coord --> P[Payment]
    P -->|성공| Coord
    Coord --> I[Inventory]
    I -->|실패| Coord
    Coord -->|보상| P
    Coord -->|보상| O

중앙 상태 기계.
흐름 명확.
결합도 약간 높음 (orchestrator 가 모든 service 안)
문제 추적 쉬움.

항목	Choreography	Orchestration
결합도	낮음	약간 높음
흐름 추적	어려움	쉬움
디버깅	어려움	쉬움
적합	단순 흐름 (3-4 단계)	복잡 흐름 (5+ 단계)
운영 도구	event tracer	상태 기계 시각화

[!TIP] 3-4 단계까지는 choreography, 그 이상은 orchestration 이 일반 권장. Netflix 도 Conductor 라는 orchestrator 사용.

보상 트랜잭션의 함정

flowchart TD
    Q[보상이 *항상 가능* 한가?]
    Q --> X1["✗ 이메일 발송 (취소 불가)"]
    Q --> X2["✗ SMS / push 알림"]
    Q --> X3["✗ 외부 API 호출 (paypal 환불 한도)"]
    Q --> Sol1["→ 가능한 단계만 saga 안"]
    Q --> Sol2["→ 비가역 단계는 saga *마지막* 으로"]

[!CAUTION] 비가역 작업 (이메일, push, 외부 API) 은 saga 가 commit 결정 후 실행. 그 전에 실행하면 보상 불가.

멱등성 + Idempotency Key

각 단계 / 보상은 멱등 (idempotent) 해야 한다. 자세한 건 [[idempotency-keys]].

# 보상 시
async def compensate_payment(saga_id, payment_id):
    if already_refunded(saga_id):
        return                       # 멱등
    await payment_service.refund(payment_id, key=saga_id)

Saga 상태 저장

flowchart LR
    Orch[Orchestrator] --> Store[(Saga State Store)]
    Store --> SQL[(PostgreSQL)]
    Store --> Stream[(Kafka)]
    Store --> SF[(Step Functions)]

Store	특징
PostgreSQL (DB)	트랜잭션 친화
Kafka topic	event log 자연 통합
AWS Step Functions	managed orchestrator
Temporal	워크플로 엔진
Camunda	BPMN 표준

Temporal / Step Functions (워크플로 엔진)

flowchart LR
    SDK["Application code<br/>(workflow + activity)"] --> Temporal[Temporal Server]
    Temporal --> StateDB[(상태 DB)]
    Temporal --> Workers["Workers<br/>(activity 실행)"]

워크플로 코드 가 durable execution.
retry / timeout / sleep 이 언어 native 처럼.
마치 함수 호출 같은데 분산 + 영속.

흔한 함정

[!WARNING]

모든 분산 흐름 = saga = 단순 async event 가 충분한데도 복잡한 saga. 진짜 보상 필요한 흐름에만.

보상 없거나 미구현 = “해피 패스만 만들고 실패는 운영자 처리”. 1년 뒤 데이터 불일치 폭증.

Choreography 의 순환 의존성 = A → B → C → A 같은 흐름. 디버깅 지옥.

상태 저장 안 함 = orchestrator 다운 시 진행 잃음. event log 또는 DB 필수.

[Voice AI] 파이프라인 디커플링: Redis Streams / Kafka 적용

koa (김신건) — Thu, 25 Jun 2026 00:00:00 GMT

정의

대규모 음성 에이전트 = STT/LLM/TTS 를 분리 배포 + 메시지 큐로 디커플링. 수평 확장 + 독립 실패.

[!NOTE] 소규모 (수십 동시 통화) 는 monolith pipeline (Pipecat 한 프로세스) 으로 충분. 수백 ~ 수천 동시 부터 디커플링 의미.

Monolith vs Decoupled

flowchart TB
    subgraph Mono["Monolith"]
        M1["Pipecat process<br/>(STT + LLM + TTS 한 프로세스)"]
    end
    subgraph Decoupled["Decoupled"]
        D1["Orchestrator (stateless)"]
        D2[STT Workers]
        D3[LLM Workers]
        D4[TTS Workers]
        Q1[(Queue: stt-tasks)]
        Q2[(Queue: llm-tasks)]
        Q3[(Queue: tts-tasks)]
        D1 --> Q1 --> D2
        D2 --> Q2 --> D3
        D3 --> Q3 --> D4
        D4 --> D1
    end

	Monolith	Decoupled
운영 복잡도	낮음	높음
수평 확장	동일 비율	단계별 독립
독립 실패	전체 다운	단계별 격리
지연	최저	+ queue hop (~10ms)
동시 통화	수십	수천+

큐 선택

큐	적합
Redis Streams	가장 단순, < 수만 RPS
Redis Pub/Sub	손실 OK, 알림만
Kafka	큰 throughput, 영속, replay
NATS JetStream	가벼움, edge
AWS SQS	managed, AWS only

음성 에이전트 = Redis Streams 가 가장 흔함 (latency 낮음, 운영 단순).

Redis Streams 패턴

# Producer (STT worker)
async def stt_worker():
    while True:
        # stt-tasks 에서 받음
        msgs = await redis.xreadgroup(
            "stt-group", "stt-worker-1",
            {"stt-tasks": ">"},
            count=10, block=100,
        )
        for stream, items in msgs:
            for msg_id, data in items:
                audio_url = data["audio_url"]
                transcript = await deepgram.transcribe(audio_url)

                # 다음 단계로 전달
                await redis.xadd("llm-tasks", {
                    "session_id": data["session_id"],
                    "transcript": transcript,
                })
                await redis.xack("stt-tasks", "stt-group", msg_id)

자세한 Streams 는 [[Redis Streams]].

Orchestrator (stateless)

class VoiceOrchestrator:
    """Session 만 관리. 실제 처리는 worker."""

    async def on_call_start(self, call_id: str):
        # Session 을 Redis 에 저장 (stateless 의 외부 상태)
        await redis.hset(f"call:{call_id}", mapping={
            "started_at": time.time(),
            "status": "active",
        })

    async def on_audio_chunk(self, call_id: str, audio: bytes):
        # 큐에 던지고 끝
        await redis.xadd("stt-tasks", {
            "call_id": call_id,
            "audio": audio,
        })

    async def on_llm_result(self, call_id: str, text: str):
        # TTS 큐로
        await redis.xadd("tts-tasks", {
            "call_id": call_id,
            "text": text,
        })

    async def on_tts_audio(self, call_id: str, audio_chunk: bytes):
        # 사용자에게 stream
        await self.send_to_user(call_id, audio_chunk)

Orchestrator 인스턴스 자체는 상태 없음. 모든 상태 Redis. 수평 확장 + 무중단 배포 자유.

수평 확장

flowchart TB
    LB[Load Balancer] --> O1[Orchestrator 1]
    LB --> O2[Orchestrator 2]
    LB --> O3[Orchestrator 3]
    O1 & O2 & O3 --> Redis[(Redis: 상태 + 큐)]
    Redis --> STT_W["STT Workers (auto-scale)"]
    Redis --> LLM_W["LLM Workers (auto-scale)"]
    Redis --> TTS_W["TTS Workers (auto-scale)"]

컴포넌트	스케일링 기준
Orchestrator	동시 connection 수
STT Worker	stt-tasks lag
LLM Worker	llm-tasks lag, GPU
TTS Worker	tts-tasks lag

각자 다른 자원. STT 는 CPU, LLM 은 GPU, TTS 는 GPU 또는 API. 분리 = 효율적 자원.

Sticky vs Stateless

flowchart LR
    Q{Voice agent stateless?}
    Q -->|"Yes (모든 state Redis)"| Stateless[수평 확장 자유]
    Q -->|"No (메모리에 conversation)"| Sticky[Sticky session 필수]

Sticky = 같은 통화 = 같은 orchestrator. SFU + WebRTC 환경에서 불가피할 때 있음.

Failure Recovery

flowchart LR
    Crash[Orchestrator 1 죽음]
    Crash --> Detect[Health check fail]
    Detect --> Drain[기존 통화 drain]
    Detect --> NewO[다른 orchestrator 가 이어받음]
    NewO --> Restore[Redis 에서 state 복원]

async def take_over_call(call_id: str):
    state = await redis.hgetall(f"call:{call_id}")
    if not state:
        return False

    # 이미 다른 orchestrator 처리 중?
    owner = await redis.set(
        f"call:{call_id}:owner",
        self.instance_id,
        nx=True, ex=30,
    )
    if not owner:
        return False

    # 이어받음
    await self.resume_call(call_id, state)
    return True

자세한 상태 관리 는 [[Redis Sorted Sets]] 의 session 패턴.

Sentinel + Cluster

flowchart LR
    Voice[Voice agents] --> Sentinel["Redis Sentinel<br/>(자동 failover)"]
    Sentinel --> Primary[(Redis Primary)]
    Primary --> Replica1[(Replica 1)]
    Primary --> Replica2[(Replica 2)]

음성 = Redis 단일 장애 = 모든 통화 끊김. Sentinel 또는 Cluster + sticky session 보호 필수.

외부 API 복원력

flowchart TB
    Q[복원력 패턴]
    Q --> T1["Timeout (짧게)"]
    Q --> T2["Retry + backoff (idempotent only)"]
    Q --> T3[Circuit Breaker]
    Q --> T4["Fallback (다른 vendor)"]
    Q --> T5[Health check]

단계	timeout	fallback
STT	5초	Deepgram → AssemblyAI
LLM	30초	GPT-4o-mini → Claude Haiku
TTS	10초	Cartesia → Azure

자세한 건 [[retry-with-backoff]], [[circuit-breaker]].

흔한 함정

[!WARNING]

Monolith → Decouple 전환 너무 일찍 = 운영 복잡도 폭증. 수십 동시 통화는 monolith.

상태 메모리 보관 = orchestrator restart = 통화 끊김. Redis 외부 상태.

Redis Streams MAXLEN 무제한 = 메모리 폭증. MAXLEN ~ 100K 권장.

Queue lag 모니터링 없음 = 어디서 병목인지 모름. Prometheus + alert.

[Distributed Systems] CAP Theorem과 PACELC

koa (김신건) — Wed, 24 Jun 2026 00:00:00 GMT

정의

CAP Theorem (Eric Brewer, 2000): 분산 시스템에서 3가지 중 2개만 동시에 보장 가능.

C (Consistency): 모든 노드가 같은 시점에 같은 데이터 반환 (강한 일관성)
A (Availability): 모든 요청이 응답 받음 (실패도 응답)
P (Partition Tolerance): 네트워크 분할이 있어도 동작

현실: P 는 선택지 아님 (네트워크는 항상 깨질 수 있음). 따라서 실질적 선택은:

CP: 분할 시 일관성 우선 → 일부 노드 응답 안 함
AP: 분할 시 가용성 우선 → 일관성 일시 깨짐

CAP 의 한계와 PACELC

CAP 는 “분할 시” 시나리오만 다룸. 정상 작동 시의 trade-off 는?

PACELC (Daniel Abadi, 2010):

P artition 시: A vailability vs C onsistency
E lse (정상): L atency vs C onsistency

시스템	PACELC	해석
MongoDB	PA / EC	분할 시 A, 정상 시 C
Cassandra	PA / EL	분할 시 A, 정상 시 L (낮은 latency)
HBase	PC / EC	항상 C
DynamoDB	PA / EL	항상 가용성 / latency 우선
PostgreSQL	PC / EC	단일 노드 강한 일관성

PACELC 가 더 실제적: 정상 시간이 훨씬 길기 때문.

CP 시스템 예: HBase, MongoDB (default)

[Node A (Primary)] ←── network OK ──→ [Node B (Secondary)]
                    ↓
                replication
                    ↓
            consistent read

[Node A] ←── network 분할 ──→ [Node B]
   ↓ leader election 발동
   write → A 만 받음
   B 의 read → 실패 또는 stale 반환 거부

분할 시 minority partition 은 응답 거부 → 가용성 손실, 일관성 보장.

장점: 사용자가 항상 최신 데이터를 봄. 단점: 일부 사용자가 아예 응답 못 받음.

AP 시스템 예: Cassandra, DynamoDB

[Node A] ←── 분할 ──→ [Node B]

write A → A 의 view 만 업데이트
write B → B 의 view 만 업데이트
both nodes 응답 OK → 가용성 보존

나중에 분할 복구:
A 와 B 의 view 가 다름 → conflict resolution (LWW, vector clock 등)

장점: 사용자가 항상 응답 받음. 단점: 일시적으로 다른 사용자가 다른 결과 봄 (eventual consistency).

Consistency Spectrum

CAP 의 “C” 는 strong consistency. 실무는 더 세밀한 spectrum:

Strong consistency     ─── 가장 엄격
   ↓
Linearizability        (실시간 순서 보장)
   ↓
Sequential consistency
   ↓
Causal consistency     (인과 관계만 보장)
   ↓
Eventual consistency   ─── 가장 느슨

대부분 AP 시스템 = eventual. CP 시스템 = strong (or linearizable).

Tunable consistency (Cassandra 패턴)

CONSISTENCY LEVEL = ONE / QUORUM / ALL / EACH_QUORUM

ONE: 1개 노드 응답이면 OK (빠르지만 stale 위험)
QUORUM: 과반수 (N/2 + 1)
ALL: 모든 replica 응답 (느리지만 가장 일관)

write QUORUM + read QUORUM = strong consistency 보장 (N=3 면 2+2 = 4 > 3).

실무 선택 기준

금융 / 결제: CP

계좌 잔액은 절대 stale 안 됨
→ HBase, PostgreSQL (single instance), Spanner
→ 분할 시 거래 차단이 안전

SNS / Feed: AP

타임라인이 일시적으로 다르게 보여도 됨
→ Cassandra, DynamoDB
→ 분할이라도 게시 / 조회 가능

검색 인덱스: AP (eventual)

검색 결과가 몇 초 지연돼도 OK
→ Elasticsearch (near real-time)

메시지 큐: 두 모드

Kafka: AP (high throughput)
RabbitMQ: 모드별 선택 (mirror queue 는 CP)

CAP 의 흔한 오해

오해 1: CA 시스템도 가능?

NO. 분산 환경에서 P 는 선택지 아님 (네트워크는 항상 깨질 수 있음). “CA” 는 single-node 시스템 (MySQL standalone).

오해 2: AP = 일관성 없음?

NO. AP 는 eventual consistency 또는 weaker. 결국엔 수렴.

오해 3: CAP 가 영구 선택?

NO. 분할 발생 시점에만 trade-off. 정상 시간엔 PACELC 의 E (latency vs consistency).

오해 4: P 는 datacenter 분할만?

분할 = network 가 잠시라도 깨짐. 짧은 packet loss / latency spike 도 포함. 빈번히 발생.

consensus 와의 관계

CAP 의 “C” 를 보장하려면 합의 (consensus) 필요. Raft, Paxos 같은 알고리즘이 분할 시 majority 만 진행:

5-node cluster
└── 3-node majority (가능, 진행)
└── 2-node minority (정지)

majority 가 사라지면 (3+ 노드 분할) cluster 전체 정지. [[distributed-systems-consensus]] 참고.

함정과 베스트 프랙티스

CAP 는 정상 시 trade-off 안 다룸: PACELC 가 더 현실적
P 는 항상: CA 시스템은 single-node 에서만
eventual consistency 도 정확한 정의: 결국 수렴, 시간 보장 X
Tunable consistency 활용: Cassandra 의 QUORUM 패턴
금융은 CP, SNS 는 AP: 도메인 별 명확
단순화하지 말 것: 모든 read 가 strong 필요 X, 모든 write 가 eventual OK X
monitoring: stale read 비율, partition 빈도 추적

[Distributed Systems] Consensus: Raft, Paxos

koa (김신건) — Wed, 24 Jun 2026 00:00:00 GMT

정의

Consensus (합의): 여러 노드가 같은 값에 동의 하는 분산 알고리즘. CAP 의 C 보장의 기반.

용도:

Leader election: 1개 leader 선출 (ZooKeeper, etcd, Consul)
Replicated log: 모든 노드가 같은 명령 순서로 적용 (DB replication, K8s etcd)
Distributed lock: 글로벌 락
Configuration management: cluster 설정

대표 알고리즘:

Paxos (1989, Lamport): 이론적 정석, 이해 어려움
Raft (2014, Ongaro & Ousterhout): Paxos 의 이해 가능한 대안. 현재 대세
PBFT, Byzantine fault tolerance: 악의적 노드 가정 (blockchain)

이 페이지는 Raft 중심 (가장 보편적).

Raft 의 3가지 역할

[Leader]   ─── 1명만 존재
   └── 모든 write 받음, log replication 책임
   
[Follower] ─── 나머지 모두
   └── leader 의 명령 받아 적용

[Candidate] ─── 전이 상태 (선거 중)
   └── leader 가 사라지면 follower 가 candidate 로 전환, 투표 요청

Raft 의 핵심: term

시간을 term (선거 회차) 으로 나눔:

term 1: Leader = A
term 2: Leader = B  (A 죽음, B 선출)
term 3: Leader = A  (B 죽음, A 복귀)

각 노드는 자신의 currentTerm 보유. term 이 낮은 노드의 요청은 거부 (오래된 leader 격리).

Leader Election

follower 가 randomized timeout (150~300ms) 동안 leader heartbeat 못 받으면:
  1. 자신을 candidate 로 전환
  2. currentTerm++
  3. 자기 자신에 투표
  4. 다른 노드에 RequestVote RPC 전송
  
응답 시나리오:
  - 과반수 (N/2 + 1) 표 받으면 → Leader 됨
  - 다른 candidate 의 더 높은 term 보면 → follower 로 복귀
  - 표 안 모이면 → 새 election (다른 timeout 후)

randomized timeout 이 split vote 회피의 핵심.

Log Replication

[Leader] receives "x = 5" from client
   ↓
1. Leader appends to its log:  [..., (term=3, x=5)]
2. Leader sends AppendEntries RPC to all followers
3. Each follower appends to its log + replies OK
4. Once majority replied → Leader commits (apply to state machine)
5. Leader notifies followers in next AppendEntries
6. Followers apply committed entries to their state machine

핵심: commit = majority 가 log 에 기록. apply 는 그 후.

Log Matching Property

같은 index + 같은 term 의 entry = 같은 명령 (강력한 invariant)

따라서 leader 의 log 가 truth. follower 가 mismatch 면 leader 의 것으로 덮어쓰기.

Safety: 어떤 leader 가 선출되나?

새 leader 는 모든 committed entry 를 가진 노드 만 가능.

RequestVote 시 candidate 가 자신의 last log term, index 보냄. follower 는 자기보다 stale 한 candidate 에게 투표 안 함 (rejects vote if candidate’s log is less up-to-date).

majority vote 보장 + commit 조건 = “어느 commit 된 entry 는 영구히 보존”.

Membership Changes

cluster 멤버 추가 / 제거는 위험 (두 majority 존재 시 split brain):

old: {A, B, C} → majority = 2
new: {A, B, C, D, E} → majority = 3

전환 중에 둘 다 자기를 majority 라고 주장 가능

Raft 의 해결:

Joint consensus (논문): old 와 new config 의 majority 모두 필요
Single server changes (실용): 한 번에 1명만 추가 / 제거

Snapshot + Log Compaction

log 가 무한히 커지면 안 됨. 주기적으로 snapshot:

1. State machine 의 현재 상태를 disk 에 저장
2. 그 시점 이전 log entry 삭제
3. Snapshot 에 last included index, term 기록

복구 시 snapshot 적용 + 그 이후 log replay.

Raft 구현체

시스템	사용처
etcd	Kubernetes 의 control plane
Consul	service discovery
CockroachDB	distributed SQL
TiKV	TiDB 의 storage
MongoDB (3.2+)	replication
Hazelcast (4.0+)	distributed cache

대부분 시스템이 직접 구현하거나 hashicorp/raft 라이브러리 사용.

Paxos 와의 비교

항목	Paxos	Raft
발표	1989	2014
이해도	매우 어려움	비교적 쉬움
Leader 개념	명시적 X (Multi-Paxos 추가)	명시적
Log replication	명시적 X	명시적
산업 채택	Spanner, Chubby	etcd, Consul, …

Raft 가 “이해 가능한 alternative” 를 목표로 설계. 안전성은 동등.

Paxos 의 단계

Prepare (round): proposer 가 proposal number 보내 majority 의 promise 받음
Accept: 가장 높은 proposal number 의 value 를 majority 에 보냄
Learn: 결정된 값 전파

Multi-Paxos: leader 가 prepare 한 번 + 여러 accept (Raft 의 leader 와 유사).

ZooKeeper 와 Zab

ZooKeeper 의 합의 알고리즘 Zab (ZooKeeper Atomic Broadcast):

Paxos / Raft 와 유사하지만 total order 강제
Leader 가 모든 update 를 ordered broadcast
ZooKeeper 의 zxid (zookeeper transaction id) 가 순서 보장

ZooKeeper 는 분산 락 / leader election 의 standard. ephemeral node + watch 가 강력.

CAP 와 합의의 관계

합의 알고리즘 = CP (강한 일관성).

분할 시 minority partition 의 노드들은:

leader 가 없음 → write 불가
또는 old leader 였다면 commit 못 함 → 정지

majority partition 만 진행. 가용성 손실 + 일관성 보장.

자주 보는 함정

함정 1: split brain

분할 후 양쪽이 각자 leader 선출 → 둘 다 update → 복구 후 충돌.

Raft 의 term + majority 가 방어. minority 의 “leader” 는 다음 term 의 leader 로 인해 거부됨.

함정 2: clock skew

Lamport timestamp / Vector clock 같은 logical clock 사용. wall clock 의존 시 NTP drift 로 깨짐.

Raft 는 wall clock 의존 안 함 (term 이 logical).

함정 3: 2 노드 cluster 의 위험

majority = 2/2. 1 노드 죽으면 cluster 정지. 3 노드가 최소.

함정 4: 짝수 노드 cluster

4 노드 cluster 의 majority = 3. 즉 3 노드 cluster 와 같은 fault tolerance (1 노드 fail). 그러나 메시지 비용 ↑. 홀수 권장.

함정 5: cross-DC 합의의 latency

majority 가 다른 DC 면 매 write 가 cross-DC latency. 보통 같은 region 에 3 노드. cross-region 은 별도 consensus (geo-replication).

성능 trade-off

3 node cluster: 1 fail tolerance, 빠른 합의
5 node cluster: 2 fail tolerance, 약간 느림
7+: 거의 안 함 (메시지 비용 폭증)

write throughput = 1 / RTT (대략). leader 가 majority 응답 기다림.

함정과 베스트 프랙티스

홀수 노드 (3, 5, 7): 짝수는 메시지 비용만 ↑
majority 가 같은 region: cross-DC 면 latency 폭주
clock skew 무관: 합의 자체엔 영향 X (logical clock)
snapshot 주기적 + tunable: log 무한 성장 방지
client retry + idempotent: leader 전환 중에도 안전
monitoring: leader election 빈도, log size, applied vs committed gap

[Distributed Systems] 분산 트랜잭션: 2PC, Saga, Outbox

koa (김신건) — Wed, 24 Jun 2026 00:00:00 GMT

정의

분산 트랜잭션 은 여러 service / DB / 메시지 큐에 걸친 작업을 ACID 처럼 묶는 문제. 마이크로서비스 / 이벤트 기반 아키텍처의 핵심 도전.

3가지 접근:

2PC (Two-Phase Commit): 동기 ACID, 전통적, 거의 안 씀
Saga: 비동기 compensating action, 마이크로서비스 표준
Outbox: DB 트랜잭션 + 메시지 큐 일관성 보장 (Saga 의 보조)

선택 기준: 시스템 복잡도, 일관성 요구, 가용성 trade-off.

2PC (Two-Phase Commit)

1단계 (Prepare): coordinator → 모든 participant 에게 “준비 됐어?” 2단계 (Commit): 모두 OK 면 → “commit”. 한 명이라도 NO 면 → “rollback”

       [Coordinator]
            │
   ┌────────┼────────┐
   ↓        ↓        ↓
 [DB A]   [DB B]   [DB C]

Phase 1 (Prepare):
   coordinator → "준비?"
   each DB → write log, lock rows, "yes"

Phase 2 (Commit):
   coordinator → "commit"
   each DB → commit, release lock, "done"

장점:

강한 ACID 보장
표준 (XA Transaction)
동기적 - 결과 즉시

단점:

Blocking: coordinator 죽으면 participant 가 락 잡은 채 영원히 대기
Performance: 매 트랜잭션 = 2 라운드 + N participant
Single point of failure: coordinator
CP 시스템: 가용성 손실

JTA (Java Transaction API) + XA driver 가 구현. 대부분 modern 시스템은 회피.

Saga Pattern

전체 트랜잭션을 여러 local 트랜잭션의 chain 으로:

T1 (서비스 A) → T2 (서비스 B) → T3 (서비스 C)
                                ↓ 실패
              C2 (B 보상) ← C3 (실패 처리)

각 step 이 commit 후 다음 발동. 실패 시 compensating transaction 으로 되돌리기.

예: 주문 처리

Step 1: Order Service → 주문 생성 (status=pending)
Step 2: Payment Service → 결제 시도
   성공 → Step 3
   실패 → Compensating: Order Service → 주문 취소

Step 3: Inventory Service → 재고 차감
   성공 → Step 4
   실패 → Compensating: Payment Service → 환불 → Order Service → 취소

Step 4: Shipping Service → 배송 시작
   성공 → 완료
   실패 → Compensating: 재고 복구, 환불, 주문 취소

각 service 가 자기 local 트랜잭션만 책임. cross-service 락 없음.

두 가지 구현 방식

1. Choreography: 각 service 가 이벤트 발행 + 구독

Order Service → "OrderCreated" 이벤트 → Kafka
Payment Service ← "OrderCreated" 구독 → 결제 시도 → "PaymentCompleted" 발행
Inventory Service ← "PaymentCompleted" 구독 → ...

장점: 분산, 결합도 낮음. 단점: 흐름 추적 어려움, 디버깅 복잡.

2. Orchestration: 중앙 orchestrator 가 흐름 제어

Saga Orchestrator
  ├── Order Service: 생성
  ├── Payment Service: 결제 (실패 시 → 이전 단계 보상)
  ├── Inventory Service: 차감
  └── Shipping Service: 시작

장점: 흐름 명시적, 디버깅 쉬움. 단점: orchestrator 가 단일 장애점, 복잡한 로직.

도구: AWS Step Functions, Camunda, Temporal, Conductor.

Saga 의 제약

Isolation 없음: 진행 중인 saga 의 중간 상태가 다른 트랜잭션에 보임 → “dirty read” 가능
Eventually consistent: 보상 완료까지 일시 비일관
Compensating transaction 설계 어려움: idempotent + 영구 부수효과 없어야 (이메일 발송 후 보상 어려움)

대응 패턴:

Semantic lock: 진행 중 자원에 flag 표시 (e.g., order.status=processing)
Commutative updates: 순서 무관하게 결과 동일하도록
Pessimistic view: 보수적 처리 (e.g., 미리 예약 → 확정)

Outbox Pattern

DB 트랜잭션 + 메시지 큐 발행 의 atomicity 보장:

[전통 문제]
INSERT order INTO orders ─ DB transaction ─ OK
kafka.publish(OrderPlaced) ─ network call ─ 실패
→ DB 에 order 있지만 알림 X (inconsistent)

또는 반대로:
kafka.publish(OrderPlaced) ─ 성공
INSERT order ─ rollback
→ 알림 갔지만 DB 에 order 없음 (worse!)

Outbox 패턴:

[같은 DB 트랜잭션 안]
BEGIN
  INSERT INTO orders (...);
  INSERT INTO outbox (event_type, payload, status='pending');
COMMIT

[별도 worker]
SELECT * FROM outbox WHERE status='pending'
  → Kafka publish
  → UPDATE outbox SET status='sent'

장점:

DB 트랜잭션 = 단일 commit (atomic)
Worker 가 죽어도 row 가 outbox 에 살아 있어 재시도
at-least-once delivery (idempotent consumer 필요)

도구:

Debezium: outbox 테이블의 CDC (Change Data Capture)
Spring Modulith Events: Spring 통합
직접 구현: 간단한 polling worker

Spring Boot 의 outbox 예

@Service
@Transactional
public class OrderService {
    private final OrderRepository orderRepo;
    private final OutboxRepository outboxRepo;
    private final ObjectMapper objectMapper;

    public Order place(Cart cart) {
        Order order = orderRepo.save(new Order(cart));

        OutboxEvent event = new OutboxEvent();
        event.setAggregateType("Order");
        event.setAggregateId(order.getId().toString());
        event.setEventType("OrderPlaced");
        event.setPayload(objectMapper.writeValueAsString(toEvent(order)));
        event.setStatus("pending");
        outboxRepo.save(event);

        return order;
    }
}

@Component
public class OutboxRelay {
    private final OutboxRepository outboxRepo;
    private final KafkaTemplate<String, String> kafka;

    @Scheduled(fixedDelay = 1000)
    public void relay() {
        List<OutboxEvent> events = outboxRepo.findTop100ByStatusOrderById("pending");
        for (OutboxEvent e : events) {
            kafka.send("orders", e.getAggregateId(), e.getPayload());
            e.setStatus("sent");
            outboxRepo.save(e);
        }
    }
}

@TransactionalEventListener(AFTER_COMMIT) 도 비슷한 효과 ([[spring-events]]) 지만 worker 인스턴스 죽으면 event 손실 → outbox 가 더 안전.

Outbox vs 2PC vs Saga 정리

항목	2PC	Saga	Outbox
일관성	Strong	Eventual	Eventual
Blocking	Yes (락)	No	No
Compensating 필요	No	Yes	(개별 step 에 따름)
운영 복잡도	높음	중간	낮음
가용성	낮음 (CP)	높음 (AP)	높음
사용처	legacy (XA)	마이크로서비스 표준	DB + MQ 양립

대부분 modern: Saga + Outbox 조합. 2PC 회피.

Idempotency

분산 시스템의 모든 작업은 idempotent:

재시도해도 결과 같음
중복 메시지 처리해도 OK
network 재시도 안전

구현 패턴:

Idempotency key: 클라이언트가 unique key 동봉 → 서버가 처음 보면 처리, 두 번째 보면 캐시 결과 반환
Conditional update: WHERE status='pending' → 이미 처리된 row 는 변경 안 됨
Distributed lock + check: race 회피

자주 보는 함정

함정 1: 보상 트랜잭션의 부수효과

“이메일 발송” 같은 영구 부수효과는 보상 불가. 패턴:

외부 호출은 saga 의 마지막 단계로
또는 confirmation 단계 분리 (PaymentPending → PaymentConfirmed)

함정 2: at-least-once delivery 의 중복

Kafka / SQS 는 at-least-once. consumer 는 idempotent 처리 필수. Outbox 자체도 publish 후 status update 사이 crash 시 중복 가능.

함정 3: outbox 의 throughput 한계

polling worker 가 단일 인스턴스면 bottleneck. 해결:

partition 별 worker
Debezium 같은 CDC tool 활용

함정 4: Saga 의 부분 실패 디버깅

choreography 면 흐름 추적 어려움. distributed tracing (OpenTelemetry) + correlation ID 필수.

함정 5: Two-Generals 문제

DB commit + 메시지 큐 publish 의 atomicity 는 본질적으로 불가 (network 위에선). Outbox 가 best-effort.

함정과 베스트 프랙티스

2PC 회피: 모든 modern 시스템
Saga + Orchestration: 흐름 추적 / 디버깅 우선이면
Outbox 가 DB+MQ 일관성의 표준
모든 작업 idempotent: idempotency key + conditional update
distributed tracing 필수: traceId + spanId
compensating action 설계가 핵심: 영구 부수효과는 마지막에
eventual consistency 명시적 안내: UX 에 반영
Outbox 의 worker scaling: 단일 worker 가 bottleneck

김신건의 로그 - 위키 / distributed-systems

[Distributed] Kafka Consumer Group: rebalancing, offset, lag

정의

Partition 할당

Rebalancing

Eager vs Cooperative

Static Membership (KIP-345)

Offset 관리

Auto commit 함정

Consumer Lag

Lag 기반 Auto-Scaling

Heartbeat / Session

흔한 함정

관련 위키

[Distributed] Kafka: 분산 로그, partition, consumer group

정의

토폴로지

Partition: 핵심 단위

Partition 수 선택

Consumer Group

Offset 관리

Replication + ISR

Exactly-once Semantics (EOS)

KRaft (Kafka Raft, ZooKeeper 제거)

Kafka 의 적합 / 부적합

흔한 함정

관련 위키

[Distributed] Message Broker 비교: Kafka / RabbitMQ / NATS / SQS / Redis Streams

결정 트리

6가지 broker 매트릭스

처리량 / 지연 / 운영비용 (직관)

시나리오별 추천

메시지 보장 비교

영속 / 재처리 비교

마이그레이션 비용

운영자 시점 체크리스트

관련 위키

[Distributed] NATS: 가벼움, JetStream, subject 라우팅

정의

두 모드: Core vs JetStream

Subject 계층

Request-Reply (Core NATS 의 강점)

JetStream 메시지 흐름

NATS KV / Object Store

NATS vs Kafka vs RabbitMQ

Edge / IoT 패턴

적합 / 부적합

흔한 함정

관련 위키

[Distributed] RabbitMQ: exchange, queue, routing key

정의

구조

Exchange 4 종류

1. Direct

2. Topic

3. Fanout

4. Headers

메시지 보장

DLQ (Dead Letter Queue)

RabbitMQ vs Kafka

RabbitMQ Streams (Kafka 흉내)

흔한 함정

관련 위키

[Pattern] API Gateway: BFF, 라우팅, auth, rate limit

정의

역할

책임 카탈로그

BFF (Backend For Frontend)

API Gateway vs Service Mesh

도구 비교

패턴: GraphQL Federation Gateway

흔한 함정

관련 위키

[Pattern] CQRS: Command / Query 분리, read model

정의

동기

기본 구조

예시: 전자상거래

Event Sourcing 과 자주 같이

Read Model 종류