partition ordering, producer idempotence, Kafka EOS, external effects를 분리
00 · epistemic contract
설명보다 먼저, 증거의 종류
한 문단 안에서도 Kafka 계약, 실제 관찰, 권고, 프로젝트 선택을 섞지 않습니다. 이 구분이 보장 과장을 막습니다.
공식 계약
Apache Kafka 또는 선택한 registry의 1차 문서가 명시한 의미입니다.
실행 증거
고정된 버전과 이 저장소의 명령으로 재현하고 보존해야 하는 관찰 대상입니다.
운영 권고
계약과 실패 비용에서 도출한 권고이며 Kafka 보장으로 오해하면 안 됩니다.
이 실습의 선택
재현성과 학습을 위해 이 프로젝트가 의도적으로 고정한 결정입니다.
01 · end-to-end trace
record 하나를 끝까지 추적하라
각 단계를 선택해 어떤 식별자와 metric이 다음 경계까지 이어지는지 확인하세요.
직렬화된 bytes가 batch에 들어간다
key는 partition 선택에 관여하고, delivery callback은 broker 응답 또는 최종 오류를 관찰한다. timeout은 기록 실패의 증명이 아니라 결과 불명의 시작일 수 있다.
eventId=ord_7f3 · key=customer_42 · acks=all · idempotent=true02 · capstone pipeline
주문을 event로 잇고, 틈을 드러낸다
주문 생성 → 재고 → 결제 결과 → 알림을 event로 연결하고, 각 원자 경계와 실패 창을 trace·test·reconciliation으로 증명한다.
1 · 주문 생성
orders와 outbox row를 한 DB transaction에 기록한다.
orders.created.v12 · 재고
inbox unique(event ID, consumer)로 dedupe한 뒤 SKU version/stock을 조건부 갱신한다.
inventory.results.v1 · reserved/rejected3 · 결제 결과
payment adapter에 order ID idempotency key를 전달하고 attempt/result ledger를 기록한다.
payments.results.v1 · succeeded/failed4 · 알림
notification inbox와 template/version을 기록하고 pipeline.retry.v1에서 bounded retry한 뒤 pipeline.dlq.v1로 보낸다.
notifications.sent.v1 또는 pipeline.dlq.v15 · 조정
source-of-truth 상태와 event projection을 비교해 missing/duplicate/illegal transition을 보고하고 승인된 repair event를 만든다.
reconciliation.findings / repair audit03 · one lab, three paths
같은 증거를 어느 OS에서도 만든다
host에 Kafka를 직접 설치하지 않습니다. Docker Compose가 고정된 broker, registry, database, app, metric stack을 실행합니다.
orders.created.v1 · inventory.results.v1 · payments.results.v1 · notifications.sent.v1 · pipeline.retry.v1 · pipeline.dlq.v1 · java.client.smoke.v1
한 번에 시작하고 검증
Docker Desktop 20.10.4+와 Node 22가 필요합니다.
./scripts/lab.sh start
./scripts/lab.sh test경로 구분자까지 별도 제공
Windows용 wrapper가 같은 Compose와 assertion을 호출합니다.
.\scripts\lab.ps1 start
.\scripts\lab.ps1 testhost 도구 최소화
service build와 cluster lifecycle을 Compose로 고정합니다.
docker compose up -d --build
docker compose ps로그가 아니라 판정 가능한 증거
offset, eventId, inbox count, ISR, lag, latency를 함께 보존합니다.
make evidence
make source-validate04 · forced failure curriculum
실패를 설명하지 말고 주입한다
14개 실습은 trigger, expected evidence, recovery, cleanup을 하나의 계약으로 묶습니다.
producer timeout 후 결과 불명
PROJECT POLICY · 주입send Future에 의도적으로 매우 짧은 application caller deadline을 적용해 broker 결과가 알려지기 전에 호출만 timeout시킨다. delivery.timeout.ms를 만료시키거나 broker 응답을 차단하는 실습은 아니다.
VERIFIED BEHAVIOR · 증거caller timeout 뒤 같은 Future의 최종 ack와 동일 event ID의 consumer 기록이 존재한다. caller deadline만으로 write 부재를 결론낼 수 없다.
RECOMMENDED PRACTICE · 복구process가 살아 있으면 같은 Future/callback의 최종 결과를 먼저 확인한다. 결과를 끝내 알 수 없다면 동일 event ID로 bounded retry하고 downstream inbox unique key로 중복 효과를 막는다.
SPEC · 위험무심한 새 ID 재전송은 business duplicate를 만든다.
P02 · P04acks/min ISR 설정 충돌
PROJECT POLICY · 주입RF=3, min.insync.replicas=2, acks=all에서 ISR을 1로 줄이고 produce한다.
VERIFIED BEHAVIOR · 증거NotEnoughReplicas 계열 오류, failed callback, ISR=1을 함께 보존한다.
RECOMMENDED PRACTICE · 복구replica를 복구해 ISR이 하한을 만족한 뒤 write를 재개한다. min ISR을 낮추는 것은 durability 변경 승인이 필요하다.
SPEC · 위험availability를 위해 durability gate를 낮추면 acknowledged data의 손실 위험이 바뀐다.
P01 · P02consumer 처리 후 commit 전 crash
PROJECT POLICY · 주입side effect 성공 직후 process를 kill하고 같은 group으로 재시작한다.
VERIFIED BEHAVIOR · 증거같은 topic/partition/offset과 event ID가 다시 전달되고 inbox duplicate count가 증가한다.
RECOMMENDED PRACTICE · 복구side effect를 idempotency key로 보호하고 성공한 offset+1만 commit한다.
SPEC · 위험at-least-once의 duplicate window다.
P03 · P04commit 후 side effect 실패
PROJECT POLICY · 주입offset을 먼저 commit한 다음 DB/API 효과를 실패시키고 consumer를 재시작한다.
VERIFIED BEHAVIOR · 증거committed offset은 record를 지나갔지만 side-effect ledger에는 결과가 없다.
RECOMMENDED PRACTICE · 복구commit-before-effect를 제거하고 outbox/inbox 또는 reconciliation으로 누락을 수선한다.
SPEC · 위험at-most-once의 loss window다.
P03 · P04rebalance 중 중복 처리
PROJECT POLICY · 주입처리 중 consumer를 추가하거나 max.poll.interval을 초과해 assignment를 이동시킨다.
VERIFIED BEHAVIOR · 증거generation/assignment 변경과 같은 offset의 두 processing attempt가 trace에 나타난다.
RECOMMENDED PRACTICE · 복구partition ownership을 worker까지 전달하고 revoke 시 drain/commit하며 side effect를 멱등화한다.
SPEC · 위험cooperative/static membership은 이동량을 줄일 뿐 duplicate 가능성을 제거하지 않는다.
P03 · P04hot partition
PROJECT POLICY · 주입고정 hot key에 80% 이상 traffic을 보내 한 partition leader에 집중시킨다.
VERIFIED BEHAVIOR · 증거cluster 평균은 정상처럼 보여도 한 partition의 bytes/s, p99, lag가 편향된다.
RECOMMENDED PRACTICE · 복구business ordering 요구를 재검토하고 shard key, adaptive routing 또는 upstream throttle을 선택한다.
SPEC · 위험key 변경은 entity ordering과 replay 호환성을 바꾼다.
P00 · P08slow consumer
PROJECT POLICY · 주입처리 시간을 늘려 ingress가 drain rate를 넘고 일부 batch가 max poll budget에 근접하게 한다.
VERIFIED BEHAVIOR · 증거lag 기울기, processing p99, poll 간격, rebalance 여부가 함께 변한다.
RECOMMENDED PRACTICE · 복구원인을 CPU/IO/downstream으로 분류하고 batch 제한, pause/resume, partition 여유 내 scale, backpressure를 적용한다.
SPEC · 위험consumer만 추가하면 downstream overload와 rebalance가 악화될 수 있다.
P03 · P08 · P10ISR 감소
PROJECT POLICY · 주입follower broker의 network/disk를 지연시켜 replica lag 하한을 넘긴다.
VERIFIED BEHAVIOR · 증거ISR shrink, URP 증가, follower lag와 replication fetch 저하가 같은 timeline에 나타난다.
RECOMMENDED PRACTICE · 복구follower 자원/경로를 복구하고 catch-up을 관찰한다. 반복되면 placement와 capacity를 수정한다.
SPEC · 위험ISR shrink는 즉시 데이터 손실 증거는 아니지만 다음 leader failure의 선택지를 줄인다.
P01 · P10broker kill
PROJECT POLICY · 주입leader를 가진 broker를 SIGKILL/컨테이너 kill하고 traffic을 유지한다.
VERIFIED BEHAVIOR · 증거client retry/metadata refresh, leader election, 잠시 증가한 latency, ISR/URP 변화가 기록된다.
RECOMMENDED PRACTICE · 복구quorum/partition 상태를 확인한 뒤 broker를 복구하고 replica catch-up과 lag drain 완료를 검증한다.
SPEC · 위험성공 callback과 durability는 acks/min ISR/unclean 정책을 포함해 판정해야 한다.
P01 · P10poison message
PROJECT POLICY · 주입항상 deterministic하게 실패하는 유효 schema event를 보낸다.
VERIFIED BEHAVIOR · 증거bounded attempts 뒤 DLQ/quarantine에 원본 좌표·error class·attempt가 남고 main partition이 계속 진행한다.
RECOMMENDED PRACTICE · 복구payload를 redacted 조사해 코드/data를 수정하고 contract test 후 승인된 replay를 수행한다.
SPEC · 위험무한 local retry는 partition을 막고 무차별 skip은 data loss를 숨긴다.
P05 · P06schema incompatibility
PROJECT POLICY · 주입호환성 규칙을 깨는 schema를 CI fixture와 runtime producer에서 각각 시도한다.
VERIFIED BEHAVIOR · 증거registry rejection 또는 consumer deserialization error와 해당 schema ID/offset 범위가 보존된다.
RECOMMENDED PRACTICE · 복구bad producer 중단, quarantine, 호환 schema/consumer 배포, corrected backfill 순서로 복구한다.
SPEC · 위험runtime skip은 poison traffic을 숨기고 rolling compatibility를 증명하지 못한다.
P05 · P06replay가 외부 시스템 중복 변경
PROJECT POLICY · 주입이미 처리된 offset 범위를 새 group으로 replay해 같은 결제/알림 adapter를 호출한다.
VERIFIED BEHAVIOR · 증거Kafka에는 합법적인 재읽기지만 외부 ledger에 같은 event ID의 두 attempt/effect가 나타난다.
RECOMMENDED PRACTICE · 복구dry-run, idempotency preflight, isolated sink, throttle, approval manifest, reconciliation을 replay gate로 둔다.
SPEC · 위험replay 가능성과 side-effect 안전성은 별개의 보장이다.
P04 · P06retry topic에서 순서 변경
PROJECT POLICY · 주입같은 key의 sequence 1을 retry로 보내고 sequence 2를 main path에서 먼저 성공시킨다.
VERIFIED BEHAVIOR · 증거원본 offset은 1<2지만 side-effect timestamp/version 적용은 2<1로 뒤집힌다.
RECOMMENDED PRACTICE · 복구key별 blocking, version guard/compare-and-set, ordered retry lane, compensation 중 domain에 맞는 정책을 선택한다.
SPEC · 위험throughput을 얻는 retry 분리는 원본 ordering을 포기할 수 있다.
P00 · P06disk 포화
PROJECT POLICY · 주입제한된 lab volume에 filler 또는 I/O throttle을 적용해 high-water threshold에 도달시킨다.
VERIFIED BEHAVIOR · 증거disk used/latency, broker request queue/p99, replica lag/ISR, producer timeout, consumer lag의 인과 순서가 보인다.
RECOMMENDED PRACTICE · 복구traffic throttle, 안전한 공간 확보, broker/replica rebalance, retention/capacity 수정 후 ISR·lag 회복을 검증한다.
SPEC · 위험파일 수동 삭제나 급격한 retention 축소는 replay/RPO를 깨뜨릴 수 있다.
P08 · P1005 · metrics as contracts
상태보다 전이를 관측한다
단일 초록불은 정상의 증거가 아닙니다. broker, replica, group, application 지표를 같은 trace와 시간축에서 읽습니다.
PROJECT POLICY · 예시 목표P00—P10 · full curriculum
11개 모듈, 같은 16개 검증 질문
각 모듈은 16개 관점으로 반복됩니다. 개념→코드→trace→failure→runbook이 끊기지 않아야 완료입니다.
Append-only log
011. 실체와 오해SPEC
용어의 닮은꼴과 실제 보장 경계를 분리한다.
topic은 partition들의 집합이고 record는 선택된 partition 끝에 append되어 offset을 받는다. 순서는 topic 전체가 아니라 한 partition 안에서만 정의된다.
Kafka를 단순 queue로 보면 서로 다른 consumer group의 독립 offset과 replay가 설명되지 않고, database로 보면 임의 조회·제약·트랜잭션 범위를 과장하게 된다.
022. 선수 지식PROJECT POLICY
실습 전에 알아야 할 최소 모델을 확인한다.
byte serialization, hash/key 분배, 순차 파일 I/O, 보존 시간과 논리 삭제의 차이를 설명할 수 있어야 한다.
033. 15분 구조PROJECT POLICY
읽기보다 관찰과 설명에 시간을 쓴다.
0–3분: record · topic · partition · offset 모델링. 3–8분: 정상 trace 수집. 8–13분: retention을 짧게 줄여 old offset을 만료시키고, compaction 전후 key history를 비교한다. 예상 증거는 OffsetOutOfRange 또는 reset과, tombstone이 즉시 사라지지 않는 로그다. 13–15분: 증거로 보장 경계를 설명한다.
044. broker/client 내부SPEC
API 뒤의 상태 전이를 그린다.
producer의 key/partition 선택 → leader append → active segment/index 갱신 → high watermark 이하 fetch를 추적한다. segment는 offset이 아니라 로그 파일 묶음이며 offset은 partition-local 위치다.
055. 최소 코드VERIFIED BEHAVIOR
가장 작은 실행 단위로 계약을 드러낸다.
같은 key 10개와 key 없는 10개를 기록하고 topic/partition/offset/key를 출력한 뒤 partition별 순서만 비교한다.
docker compose exec kafka-1 /opt/kafka/bin/kafka-console-consumer.sh \
--bootstrap-server kafka-1:19092 --topic orders.created.v1 \
--from-beginning --property print.key=true \
--property print.partition=true --property print.offset=true066. production 코드RECOMMENDED PRACTICE
명시적 실패 처리와 운영 경계를 더한다.
business entity의 ordering 요구가 있을 때만 안정적인 key를 정하고, retention.ms/bytes와 cleanup.policy를 복구 목표·disk 예산에 맞춰 명시한다. tombstone은 compacted topic의 null value이지 즉시 물리 삭제가 아니다.
예제는 무한 retry, 무제한 batch, 암묵적 offset commit을 허용하지 않는다.
077. record 하나의 end-to-end traceVERIFIED BEHAVIOR
record ID 하나로 인과 경로를 복원한다.
correlation ID로 serialization 전 payload hash, send callback의 partition/offset, segment dump, consumer fetch/commit offset을 연결한다.
088. 장애 주입VERIFIED BEHAVIOR
정상 경로가 숨기는 모호성을 강제로 노출한다.
retention을 짧게 줄여 old offset을 만료시키고, compaction 전후 key history를 비교한다. 예상 증거는 OffsetOutOfRange 또는 reset과, tombstone이 즉시 사라지지 않는 로그다.
099. integration/contract/load testPROJECT POLICY
실행 결과를 재현 가능한 주장으로 바꾼다.
partition별 offset 단조 증가, 동일 key의 동일 partition 배치, tombstone null 보존을 integration test로 검증한다. topic 전체 순서는 assertion으로 만들지 않는다.
1010. 성능과 용량RECOMMENDED PRACTICE
처리량만이 아니라 tail latency와 자원 비용을 본다.
평균 record bytes × 초당 record × retention seconds × replication factor에 segment/index/안전 여유를 더해 disk를 산정하고, key skew를 partition별 bytes/s로 확인한다.
1111. 보안RECOMMENDED PRACTICE
신뢰 경계와 데이터 노출면을 표시한다.
key, header, payload는 모두 민감할 수 있다. 교육 로그에는 payload 대신 event ID·schema ID·size·hash만 남긴다.
1212. 관측PROJECT POLICY
원인과 증상을 구분하는 최소 신호를 정한다.
LogEndOffset, consumer position/committed offset, segment count/bytes, partition별 ingress를 함께 표시한다.
1313. runbookPROJECT POLICY
경보에서 안전한 복구까지의 의사결정을 고정한다.
offset 만료 시 자동 latest 이동을 금지한다. 영향 group과 필요한 기간을 확인하고 archive/backfill 또는 승인된 reset을 선택해 audit에 남긴다.
1414. 산출물PROJECT POLICY
설명을 대신할 실행 증거를 남긴다.
partition log 지도, key 분배 표, retention/compaction 실험 로그, queue/database 비교표를 제출한다.
1515. 완료 조건PROJECT POLICY
통과 조건을 관찰 가능한 문장으로 만든다.
임의 record ID에서 물리 partition과 offset을 찾고, 무엇이 순서·보존·삭제를 보장하지 않는지 증거로 말할 수 있다.
1616. 자가시험RECOMMENDED PRACTICE
외운 정의가 아니라 장애 상황의 결정을 답한다.
각 답은 보장 범위, 실패 창, 관측 증거, 복구의 부작용을 포함해야 한다.
- 같은 주문 key의 두 record가 다른 partition에 갈 수 있는 변경은 무엇인가?
- tombstone을 보냈는데 disk가 즉시 줄지 않는 이유는?
Cluster
011. 실체와 오해SPEC
용어의 닮은꼴과 실제 보장 경계를 분리한다.
현재 Kafka는 KRaft controller quorum이 metadata log를 관리한다. 각 partition leader가 client read/write를 처리하고 follower가 fetch하여 따라오며 ISR은 현재 동기 상태인 replica 집합이다.
replication factor 3은 언제나 세 복사본이 최신이라는 뜻이 아니며, controller가 data record를 복제하는 것도 아니다.
022. 선수 지식PROJECT POLICY
실습 전에 알아야 할 최소 모델을 확인한다.
quorum과 majority, failure detector, replication factor와 availability의 trade-off, advertised listener를 설명할 수 있어야 한다.
033. 15분 구조PROJECT POLICY
읽기보다 관찰과 설명에 시간을 쓴다.
0–3분: broker · controller quorum · metadata 모델링. 3–8분: 정상 trace 수집. 8–13분: follower broker 중단으로 ISR 감소를 만든 뒤 leader broker도 중단한다. 예상 증거는 ISR shrink, leader election 또는 offline partition, metadata refresh이며 데이터 소실은 설정에 따라 별도 판정한다. 13–15분: 증거로 보장 경계를 설명한다.
044. broker/client 내부SPEC
API 뒤의 상태 전이를 그린다.
active controller의 metadata record → broker MetadataLoader → leader/follower state 전이 → client metadata refresh를 구분한다. controller quorum과 data-plane replica set은 서로 다른 quorum이다.
055. 최소 코드VERIFIED BEHAVIOR
가장 작은 실행 단위로 계약을 드러낸다.
3 broker와 3 controller-voter 구성을 기동하고 topic describe에서 leader/replicas/ISR을 기록한 뒤 한 broker를 중단한다.
docker compose exec kafka-1 /opt/kafka/bin/kafka-topics.sh \
--bootstrap-server kafka-1:19092 --describe --topic orders.created.v1066. production 코드RECOMMENDED PRACTICE
명시적 실패 처리와 운영 경계를 더한다.
failure domain을 rack으로 선언하고 replica를 분산하며, min ISR/unclean election/metadata quorum을 RPO·RTO에 맞춰 검토한다. broker와 controller 역할은 배치 모드에 따라 분리할 수 있다.
예제는 무한 retry, 무제한 batch, 암묵적 offset commit을 허용하지 않는다.
077. record 하나의 end-to-end traceVERIFIED BEHAVIOR
record ID 하나로 인과 경로를 복원한다.
record의 partition leader epoch, send callback, follower fetch, high watermark, leader change 시 새 metadata epoch와 client 재시도를 한 timeline에 놓는다.
088. 장애 주입VERIFIED BEHAVIOR
정상 경로가 숨기는 모호성을 강제로 노출한다.
follower broker 중단으로 ISR 감소를 만든 뒤 leader broker도 중단한다. 예상 증거는 ISR shrink, leader election 또는 offline partition, metadata refresh이며 데이터 소실은 설정에 따라 별도 판정한다.
099. integration/contract/load testPROJECT POLICY
실행 결과를 재현 가능한 주장으로 바꾼다.
cluster startup, broker kill 중 produce/consume, controller voter 상실 전후 admin 요청을 검증하고 recovery 시간과 오류 유형을 기록한다.
1010. 성능과 용량RECOMMENDED PRACTICE
처리량만이 아니라 tail latency와 자원 비용을 본다.
partition/replica 수가 data disk뿐 아니라 metadata, controller event processing, open files, recovery network를 늘린다. broker 평균만 보지 말고 최대 replica bytes와 leader 수를 본다.
1111. 보안RECOMMENDED PRACTICE
신뢰 경계와 데이터 노출면을 표시한다.
inter-broker와 controller listener도 TLS/SASL 및 별도 ACL/identity 경계가 필요하다. client listener를 controller에 노출하지 않는다.
1212. 관측PROJECT POLICY
원인과 증상을 구분하는 최소 신호를 정한다.
ActiveControllerCount, current/under-replicated/offline partitions, ISR shrink/expand, leader election, MetadataLoader lag와 broker request latency를 함께 본다.
1313. runbookPROJECT POLICY
경보에서 안전한 복구까지의 의사결정을 고정한다.
broker down → failure domain 확인 → offline/URP와 ISR 확인 → client error/lag 확인 → 재시작 또는 replica reassignment 결정 순서로 진행한다. unclean election은 데이터 손실 승인이 있어야 한다.
1414. 산출물PROJECT POLICY
설명을 대신할 실행 증거를 남긴다.
KRaft node/role 지도, partition replica 표, broker-kill timeline, rack placement 검사를 제출한다.
1515. 완료 조건PROJECT POLICY
통과 조건을 관찰 가능한 문장으로 만든다.
controller 장애와 partition leader 장애를 구분하고, metadata 전파 지연과 data durability를 서로 다른 지표로 증명한다.
1616. 자가시험RECOMMENDED PRACTICE
외운 정의가 아니라 장애 상황의 결정을 답한다.
각 답은 보장 범위, 실패 창, 관측 증거, 복구의 부작용을 포함해야 한다.
- controller quorum이 살아 있고 partition leader가 없을 때 무엇이 가능한가?
- ISR 1개가 곧 record 1개만 존재함을 뜻하지 않는 이유는?
Producer
011. 실체와 오해SPEC
용어의 닮은꼴과 실제 보장 경계를 분리한다.
serializer 결과는 partition별 batch에 모이고 sender가 leader로 전송한다. acks=all과 min.insync.replicas는 승인 가능한 ISR 하한을 만들며 idempotence는 한 producer session의 retry 중복을 억제한다.
send() 성공 반환은 broker 기록 성공이 아니다. timeout은 실패가 확정되었다는 뜻도 아니어서 callback 결과가 없으면 outcome unknown 창이 생긴다.
022. 선수 지식PROJECT POLICY
실습 전에 알아야 할 최소 모델을 확인한다.
Future/callback, bounded buffer와 backpressure, latency percentile, retryable/non-retryable error를 구분할 수 있어야 한다.
033. 15분 구조PROJECT POLICY
읽기보다 관찰과 설명에 시간을 쓴다.
0–3분: serialization · partitioner · key 모델링. 3–8분: 정상 trace 수집. 8–13분: application이 매우 짧은 Future.get deadline을 먼저 만료시켜 그 시점의 결과 불명을 만든 뒤, 같은 Future의 최종 ack와 consumer record를 확인한다. 이 실습은 delivery.timeout.ms 만료나 broker response 지연을 주장하지 않는다. 13–15분: 증거로 보장 경계를 설명한다.
044. broker/client 내부SPEC
API 뒤의 상태 전이를 그린다.
application thread → serializer/interceptors → partition accumulator → RecordBatch → network sender → ProduceResponse/callback을 추적한다. delivery.timeout.ms는 record 전송 완료 전체 상한이고 request.timeout.ms는 개별 요청 대기와 관련된다.
055. 최소 코드VERIFIED BEHAVIOR
가장 작은 실행 단위로 계약을 드러낸다.
동기 get()으로 callback metadata를 출력하고, 존재하지 않는 broker와 작은 timeout에서 예외를 보존한다. fire-and-forget 예제는 통과시키지 않는다.
var record = new ProducerRecord<String, byte[]>("orders.created.v1", orderId, payload);
RecordMetadata md = producer.send(record, (metadata, error) -> {
if (error != null) failures.increment();
}).get(10, TimeUnit.SECONDS);
log.info("partition={} offset={}", md.partition(), md.offset());066. production 코드RECOMMENDED PRACTICE
명시적 실패 처리와 운영 경계를 더한다.
acks=all, enable.idempotence=true, bounded delivery timeout, retry budget, delivery callback, key policy를 명시하고 batch/linger/compression은 측정 후 조정한다. transaction은 원자적으로 묶을 Kafka writes/offsets가 있을 때만 쓴다.
예제는 무한 retry, 무제한 batch, 암묵적 offset commit을 허용하지 않는다.
077. record 하나의 end-to-end traceVERIFIED BEHAVIOR
record ID 하나로 인과 경로를 복원한다.
event ID와 producer client ID, attempt, partition, producer ID/epoch, base sequence, broker correlation ID, callback offset/latency를 연결한다.
088. 장애 주입VERIFIED BEHAVIOR
정상 경로가 숨기는 모호성을 강제로 노출한다.
application이 매우 짧은 Future.get deadline을 먼저 만료시켜 그 시점의 결과 불명을 만든 뒤, 같은 Future의 최종 ack와 consumer record를 확인한다. 이 실습은 delivery.timeout.ms 만료나 broker response 지연을 주장하지 않는다.
099. integration/contract/load testPROJECT POLICY
실행 결과를 재현 가능한 주장으로 바꾼다.
serialization error, invalid record size, ISR 부족, timeout/retry, restart 후 business duplicate를 integration test로 구분한다. callback을 기다려 테스트 종료를 결정한다.
1010. 성능과 용량RECOMMENDED PRACTICE
처리량만이 아니라 tail latency와 자원 비용을 본다.
records/s뿐 아니라 batch fill ratio, records/request, compression ratio, buffer available bytes, queue time, request p95/p99를 payload 크기별로 측정한다.
1111. 보안RECOMMENDED PRACTICE
신뢰 경계와 데이터 노출면을 표시한다.
serializer 전 PII 분류, TLS hostname verification, SASL secret 외부 주입, producer ACL 최소화가 필요하다. callback error에 payload를 남기지 않는다.
1212. 관측PROJECT POLICY
원인과 증상을 구분하는 최소 신호를 정한다.
record-send-rate/error-rate/retry-rate, request-latency p95/p99, record-queue-time, buffer-available-bytes, batch-size와 broker produce latency를 correlation한다.
1313. runbookPROJECT POLICY
경보에서 안전한 복구까지의 의사결정을 고정한다.
outcome unknown이면 동일 event ID로 안전하게 재시도하고 downstream idempotency로 확인한다. 임의 key 변경이나 retry 무제한 확장은 금지하며 callback 오류와 broker 상태를 함께 보존한다.
1414. 산출물PROJECT POLICY
설명을 대신할 실행 증거를 남긴다.
producer config 표, callback trace, idempotence 비교 로그, batch/compression benchmark를 제출한다.
1515. 완료 조건PROJECT POLICY
통과 조건을 관찰 가능한 문장으로 만든다.
각 producer 설정이 latency, ordering, duplicate, durability 중 무엇을 바꾸는지 말하고 timeout 결과 불명을 재현한다.
1616. 자가시험RECOMMENDED PRACTICE
외운 정의가 아니라 장애 상황의 결정을 답한다.
각 답은 보장 범위, 실패 창, 관측 증거, 복구의 부작용을 포함해야 한다.
- acks=all인데도 business event가 중복될 수 있는 두 경로는?
- linger.ms를 늘릴 때 p50과 p99가 반드시 같은 방향으로 움직이는가?
Consumer
011. 실체와 오해SPEC
용어의 닮은꼴과 실제 보장 경계를 분리한다.
group은 partition을 member에 할당하고 consumer는 poll 계약을 지켜야 한다. classic protocol에서는 CooperativeStickyAssignor가 cooperative rebalancing을 지원하며, 새 consumer group protocol은 server-side assignor 경로와 별도 설정/제한을 가진다.
poll은 한 record 처리 완료를 의미하지 않고 committed offset은 마지막 처리한 offset이 아니라 다음에 읽을 위치다. lag 0도 side effect 완료를 증명하지 않는다.
022. 선수 지식PROJECT POLICY
실습 전에 알아야 할 최소 모델을 확인한다.
thread ownership, heartbeat/session timeout, offset exclusive upper bound, idempotent side effect를 이해해야 한다.
033. 15분 구조PROJECT POLICY
읽기보다 관찰과 설명에 시간을 쓴다.
0–3분: fetch · poll loop · group 모델링. 3–8분: 정상 trace 수집. 8–13분: processing 후 commit 전에 process를 kill하고 재시작해 duplicate를 만든다. 처리 시간을 max.poll.interval보다 길게 만들어 rebalance 중 stale commit/재처리도 관찰한다. 13–15분: 증거로 보장 경계를 설명한다.
044. broker/client 내부SPEC
API 뒤의 상태 전이를 그린다.
coordinator discovery → join/sync or consumer protocol assignment → fetch session → poll return → processing → commit을 그린다. max.poll.interval.ms는 application poll 간격 계약이며 max.poll.records는 fetch byte 상한이 아니다.
055. 최소 코드VERIFIED BEHAVIOR
가장 작은 실행 단위로 계약을 드러낸다.
enable.auto.commit=false로 poll한 batch를 처리한 뒤 partition별 마지막 성공 offset+1을 commit하고, assignment/revocation callback을 기록한다.
var records = consumer.poll(Duration.ofMillis(500));
for (var tp : records.partitions()) {
long next = processInOrder(records.records(tp));
consumer.commitSync(Map.of(tp, new OffsetAndMetadata(next)));
}066. production 코드RECOMMENDED PRACTICE
명시적 실패 처리와 운영 경계를 더한다.
consumer thread와 worker 간 partition ownership을 유지하고, 느린 partition은 pause/resume하며, revocation 전에 완료·commit 가능한 작업만 정리한다. group.instance.id는 고유하고 안정적인 instance identity가 있을 때만 쓴다.
예제는 무한 retry, 무제한 batch, 암묵적 offset commit을 허용하지 않는다.
077. record 하나의 end-to-end traceVERIFIED BEHAVIOR
record ID 하나로 인과 경로를 복원한다.
fetch offset, consumer position, processing start/end, side-effect idempotency key, commit request/response, group generation/assignment를 record ID로 연결한다.
088. 장애 주입VERIFIED BEHAVIOR
정상 경로가 숨기는 모호성을 강제로 노출한다.
processing 후 commit 전에 process를 kill하고 재시작해 duplicate를 만든다. 처리 시간을 max.poll.interval보다 길게 만들어 rebalance 중 stale commit/재처리도 관찰한다.
099. integration/contract/load testPROJECT POLICY
실행 결과를 재현 가능한 주장으로 바꾼다.
duplicate/restart, rebalance, cooperative rollout, static identity 충돌, pause/resume, slow processing을 검증한다. assignment 소유권 없이 commit한 경로가 실패해야 한다.
1010. 성능과 용량RECOMMENDED PRACTICE
처리량만이 아니라 tail latency와 자원 비용을 본다.
group parallelism 상한은 일반적으로 대상 partition 수이며, record 처리 p99 × poll batch가 max poll budget과 충돌하지 않게 한다. lag의 기울기와 ETA를 함께 계산한다.
1111. 보안RECOMMENDED PRACTICE
신뢰 경계와 데이터 노출면을 표시한다.
group.id와 transactional/idempotency store가 tenant 경계다. READ topic, DESCRIBE topic, READ group 권한을 최소화하고 replay group을 운영 group과 분리한다.
1212. 관측PROJECT POLICY
원인과 증상을 구분하는 최소 신호를 정한다.
records-lag-max와 partition별 lag, fetch rate/latency, poll idle ratio, processing p95/p99, commit latency/failure, assigned partitions, rebalance count/duration을 같은 dashboard에 둔다.
1313. runbookPROJECT POLICY
경보에서 안전한 복구까지의 의사결정을 고정한다.
lag 증가 시 ingress 급증, processing 지연, broker fetch 지연, rebalance storm을 먼저 분류한다. offset reset이나 consumer 추가는 원인과 partition 여유 확인 후에만 수행한다.
1414. 산출물PROJECT POLICY
설명을 대신할 실행 증거를 남긴다.
poll-loop 코드, offset timeline, crash/rebalance 로그, lag ETA 계산표를 제출한다.
1515. 완료 조건PROJECT POLICY
통과 조건을 관찰 가능한 문장으로 만든다.
position/committed/end offset을 구분하고, commit 전·후 crash가 loss/duplicate에 미치는 영향을 trace로 설명한다.
1616. 자가시험RECOMMENDED PRACTICE
외운 정의가 아니라 장애 상황의 결정을 답한다.
각 답은 보장 범위, 실패 창, 관측 증거, 복구의 부작용을 포함해야 한다.
- 왜 max.poll.records를 줄여도 큰 record fetch 문제가 자동 해결되지 않는가?
- static membership이 중복 처리를 제거하지 않는 이유는?
Delivery semantics
011. 실체와 오해SPEC
용어의 닮은꼴과 실제 보장 경계를 분리한다.
producer idempotence는 retry duplicate를 producer session/partition sequence 범위에서 줄이고, Kafka transactions는 transaction-aware consumer의 read-process-write와 consumed offsets를 Kafka 안에서 원자적으로 commit할 수 있다. 외부 시스템은 그 transaction에 자동 참여하지 않는다.
‘exactly once’는 Kafka에 연결된 모든 DB/API 효과가 한 번만 일어난다는 전역 보장이 아니다. 범위를 말하지 않은 exactly-once 주장은 불합격이다.
022. 선수 지식PROJECT POLICY
실습 전에 알아야 할 최소 모델을 확인한다.
atomicity와 idempotency, unique constraint, write-ahead/outbox, crash point 분석을 구분할 수 있어야 한다.
033. 15분 구조PROJECT POLICY
읽기보다 관찰과 설명에 시간을 쓴다.
0–3분: at-most-once · at-least-once 모델링. 3–8분: 정상 trace 수집. 8–13분: commit 후 외부 API를 실패시키고, replay에서 같은 event가 외부 시스템을 다시 변경하게 한다. 예상 증거는 Kafka offset은 전진했지만 side effect가 없거나 두 번인 불일치다. 13–15분: 증거로 보장 경계를 설명한다.
044. broker/client 내부SPEC
API 뒤의 상태 전이를 그린다.
transactional.id → producer ID/epoch → begin/send/sendOffsetsToTransaction → commit/abort marker → read_committed LSO를 추적하고, DB transaction/outbox poller 경계는 별도 선으로 그린다.
055. 최소 코드VERIFIED BEHAVIOR
가장 작은 실행 단위로 계약을 드러낸다.
side effect 후 commit 전 crash로 at-least-once duplicate를, commit 후 side effect로 순서를 바꿔 at-most-once loss를 재현한다.
producer.beginTransaction();
producer.send(resultRecord);
producer.sendOffsetsToTransaction(offsets, consumer.groupMetadata());
producer.commitTransaction(); // Kafka records + offsets only
// An external DB/API is NOT enlisted by this call.066. production 코드RECOMMENDED PRACTICE
명시적 실패 처리와 운영 경계를 더한다.
DB 변경+outbox insert를 한 DB transaction에 넣고 event ID unique inbox로 consumer side effect를 멱등화한다. reconciliation은 source of truth와 projection의 차이를 주기적으로 수선한다.
예제는 무한 retry, 무제한 batch, 암묵적 offset commit을 허용하지 않는다.
077. record 하나의 end-to-end traceVERIFIED BEHAVIOR
record ID 하나로 인과 경로를 복원한다.
event ID를 source DB transaction, outbox row, Kafka partition/offset, inbox insert, side effect result, offset/transaction commit까지 추적한다. 각 원자 경계 사이의 crash 창을 표시한다.
088. 장애 주입VERIFIED BEHAVIOR
정상 경로가 숨기는 모호성을 강제로 노출한다.
commit 후 외부 API를 실패시키고, replay에서 같은 event가 외부 시스템을 다시 변경하게 한다. 예상 증거는 Kafka offset은 전진했지만 side effect가 없거나 두 번인 불일치다.
099. integration/contract/load testPROJECT POLICY
실행 결과를 재현 가능한 주장으로 바꾼다.
crash point를 outbox insert 전/후, publish 전/후, inbox insert 전/후, side effect 전/후, commit 전/후로 이동하며 최종 invariant를 검사한다.
1010. 성능과 용량RECOMMENDED PRACTICE
처리량만이 아니라 tail latency와 자원 비용을 본다.
dedupe key 보존 기간은 최대 replay horizon 이상이어야 하며 inbox/outbox 증가량, transaction latency, abort rate, reconciliation scan 비용을 예산화한다.
1111. 보안RECOMMENDED PRACTICE
신뢰 경계와 데이터 노출면을 표시한다.
idempotency key를 인증/tenant와 결합해 교차 tenant 충돌을 막고, outbox/inbox에는 필요한 최소 payload만 저장한다.
1212. 관측PROJECT POLICY
원인과 증상을 구분하는 최소 신호를 정한다.
outbox unpublished age/count, inbox duplicate count, transaction aborts, read_committed lag, side-effect attempts/results, reconciliation drift를 event ID로 묶는다.
1313. runbookPROJECT POLICY
경보에서 안전한 복구까지의 의사결정을 고정한다.
중복/누락 신고 시 offset만 reset하지 않는다. event ledger와 source of truth를 비교하고 멱등 여부를 확인한 뒤 replay, compensation, manual repair 중 하나를 승인한다.
1414. 산출물PROJECT POLICY
설명을 대신할 실행 증거를 남긴다.
failure-window 표, EOS scope 문장, outbox/inbox schema, crash matrix, reconciliation report를 제출한다.
1515. 완료 조건PROJECT POLICY
통과 조건을 관찰 가능한 문장으로 만든다.
‘Kafka→Kafka read-process-write와 offset commit은 transaction 범위에서 원자적’과 ‘외부 DB/API는 별도 패턴 필요’를 코드·trace로 입증한다.
1616. 자가시험RECOMMENDED PRACTICE
외운 정의가 아니라 장애 상황의 결정을 답한다.
각 답은 보장 범위, 실패 창, 관측 증거, 복구의 부작용을 포함해야 한다.
- read_committed consumer가 외부 결제 API 중복을 막지 못하는 이유는?
- dedupe 보존 기간이 replay 기간보다 짧으면 어떤 invariant가 깨지는가?
Schema
011. 실체와 오해SPEC
용어의 닮은꼴과 실제 보장 경계를 분리한다.
Kafka broker는 payload 의미를 검증하지 않는다. schema registry 계열은 format별 schema ID/compatibility 규칙을 제공하지만 선택한 제품과 mode의 실제 규칙을 확인해야 한다.
JSON이면 schema가 필요 없거나 optional field 추가가 언제나 안전하다는 가정은 producer/consumer 배포 순서와 enum 처리에서 깨진다.
022. 선수 지식PROJECT POLICY
실습 전에 알아야 할 최소 모델을 확인한다.
reader/writer schema, optional과 default의 차이, unknown field/enum 처리, rolling deployment 순서를 이해해야 한다.
033. 15분 구조PROJECT POLICY
읽기보다 관찰과 설명에 시간을 쓴다.
0–3분: serialization format · registry family 모델링. 3–8분: 정상 trace 수집. 8–13분: required field를 default 없이 추가하거나 enum unknown 처리를 제거해 incompatibility를 만든다. 예상 증거는 CI compatibility rejection 또는 runtime deserialization error이며 둘을 혼동하지 않는다. 13–15분: 증거로 보장 경계를 설명한다.
044. broker/client 내부SPEC
API 뒤의 상태 전이를 그린다.
domain object → serializer → schema lookup/register → wire schema ID+bytes → deserializer reader schema를 추적한다. tombstone null은 schema-encoded empty object와 구분한다.
055. 최소 코드VERIFIED BEHAVIOR
가장 작은 실행 단위로 계약을 드러낸다.
v1 consumer에 v2 producer를 연결해 field add/remove, default 유무, enum 추가, null tombstone을 compatibility mode별로 contract test한다.
{
"type": "record",
"name": "OrderCreated",
"fields": [
{"name": "orderId", "type": "string"},
{"name": "couponCode", "type": ["null", "string"], "default": null}
]
}066. production 코드RECOMMENDED PRACTICE
명시적 실패 처리와 운영 경계를 더한다.
schema ID를 payload에 포함하고 auto-register를 production에서 통제하며, compatibility gate를 CI에 둔다. consumer-first/producer-first 순서를 변화 유형별 migration plan에 기록한다.
예제는 무한 retry, 무제한 batch, 암묵적 offset commit을 허용하지 않는다.
077. record 하나의 end-to-end traceVERIFIED BEHAVIOR
record ID 하나로 인과 경로를 복원한다.
event ID, schema subject/version/ID, producer build, consumer build, decode result를 기록해 어느 배포 조합에서 실패했는지 재현한다.
088. 장애 주입VERIFIED BEHAVIOR
정상 경로가 숨기는 모호성을 강제로 노출한다.
required field를 default 없이 추가하거나 enum unknown 처리를 제거해 incompatibility를 만든다. 예상 증거는 CI compatibility rejection 또는 runtime deserialization error이며 둘을 혼동하지 않는다.
099. integration/contract/load testPROJECT POLICY
실행 결과를 재현 가능한 주장으로 바꾼다.
N-1/N/N+1 producer-consumer matrix, golden bytes, tombstone, malformed payload, registry unavailable 경로를 계약 테스트한다.
1010. 성능과 용량RECOMMENDED PRACTICE
처리량만이 아니라 tail latency와 자원 비용을 본다.
schema 조회 cache hit/miss, registry latency, serialized bytes, compression ratio, decode CPU/allocations를 format별 p95/p99로 비교한다.
1111. 보안RECOMMENDED PRACTICE
신뢰 경계와 데이터 노출면을 표시한다.
schema에도 PII 이름과 business 구조가 노출된다. registry 인증·ACL·TLS를 적용하고 payload/schema 전문을 로그에 남기지 않는다.
1212. 관측PROJECT POLICY
원인과 증상을 구분하는 최소 신호를 정한다.
schema ID/version 분포, serialization/deserialization error, registry latency/error, unknown enum/field fallback, quarantine count를 배포 버전별로 본다.
1313. runbookPROJECT POLICY
경보에서 안전한 복구까지의 의사결정을 고정한다.
incompatibility 발생 시 bad producer를 중지하고 schema ID·offset 범위를 quarantine한다. consumer hotfix 또는 corrected backfill 후 원본 audit를 보존한다.
1414. 산출물PROJECT POLICY
설명을 대신할 실행 증거를 남긴다.
versioned schema, compatibility matrix, rolling deployment plan, golden contract fixtures를 제출한다.
1515. 완료 조건PROJECT POLICY
통과 조건을 관찰 가능한 문장으로 만든다.
변경 하나마다 backward/forward/full 결과와 안전한 배포 순서를 실제 contract test 출력으로 설명한다.
1616. 자가시험RECOMMENDED PRACTICE
외운 정의가 아니라 장애 상황의 결정을 답한다.
각 답은 보장 범위, 실패 창, 관측 증거, 복구의 부작용을 포함해야 한다.
- optional이지만 default가 없는 field를 old reader가 만날 때 format별 차이를 어떻게 확인할 것인가?
- tombstone과 `{}`를 같은 event로 처리하면 어떤 compaction 문제가 생기는가?
Failure handling
011. 실체와 오해SPEC
용어의 닮은꼴과 실제 보장 경계를 분리한다.
Kafka는 일반 consumer application의 business retry/DLQ 의미를 자동 제공하지 않는다. application이 attempt, due time, original topic/partition/offset, error class를 record에 명시해야 한다.
DLQ 전송은 처리 완료가 아니며, retry topic은 원본 partition 순서를 보존하지 않는다. replay는 read-only 작업이 아니라 외부 side effect를 다시 일으킬 수 있다.
022. 선수 지식PROJECT POLICY
실습 전에 알아야 할 최소 모델을 확인한다.
transient/permanent/poison 분류, exponential backoff+jitter, idempotency, offset reset과 새 group replay 차이를 이해해야 한다.
033. 15분 구조PROJECT POLICY
읽기보다 관찰과 설명에 시간을 쓴다.
0–3분: bounded retry · backoff · jitter 모델링. 3–8분: 정상 trace 수집. 8–13분: 한 key의 첫 event만 retry topic으로 보내고 다음 event를 main topic에서 성공시켜 순서 역전을 만든다. 예상 증거는 event sequence와 side-effect timestamp 불일치다. 13–15분: 증거로 보장 경계를 설명한다.
044. broker/client 내부SPEC
API 뒤의 상태 전이를 그린다.
main consume → classification → local bounded retry 또는 retry topic → DLQ/quarantine → operator decision → replay/backfill을 그린다. retry topic마다 partition/key/시간 기준이 바뀔 수 있다.
055. 최소 코드VERIFIED BEHAVIOR
가장 작은 실행 단위로 계약을 드러낸다.
항상 실패하는 poison event와 두 번 실패 후 성공하는 transient event를 보내 attempt와 최종 destination을 검증한다.
{
"eventId": "evt-42",
"original": {"topic": "payments.results.v1", "partition": 2, "offset": 91},
"retryTopic": "pipeline.retry.v1",
"dlqTopic": "pipeline.dlq.v1",
"attempt": 3,
"errorCode": "PAYMENT_TIMEOUT",
"scheduledAt": "2026-07-15T14:00:00Z"
}066. production 코드RECOMMENDED PRACTICE
명시적 실패 처리와 운영 경계를 더한다.
retry budget, max attempts/age, jitter, retryable error allow-list, DLQ envelope, replay approval와 idempotency preflight를 코드/설정으로 고정한다.
예제는 무한 retry, 무제한 batch, 암묵적 offset commit을 허용하지 않는다.
077. record 하나의 end-to-end traceVERIFIED BEHAVIOR
record ID 하나로 인과 경로를 복원한다.
original event ID와 topic/partition/offset, attempt, scheduledAt, error code, destination offset, operator/replay run ID를 연결한다.
088. 장애 주입VERIFIED BEHAVIOR
정상 경로가 숨기는 모호성을 강제로 노출한다.
한 key의 첫 event만 retry topic으로 보내고 다음 event를 main topic에서 성공시켜 순서 역전을 만든다. 예상 증거는 event sequence와 side-effect timestamp 불일치다.
099. integration/contract/load testPROJECT POLICY
실행 결과를 재현 가능한 주장으로 바꾼다.
attempt/age 한계, jitter 범위, poison→DLQ, retry 순서 역전, replay dedupe, malformed DLQ envelope를 deterministic clock으로 검사한다.
1010. 성능과 용량RECOMMENDED PRACTICE
처리량만이 아니라 tail latency와 자원 비용을 본다.
retry traffic amplification, delayed backlog, DLQ retention, replay throttle, downstream quota를 정상 peak와 합산한다. 장애 중 retry storm을 별도 부하로 모델링한다.
1111. 보안RECOMMENDED PRACTICE
신뢰 경계와 데이터 노출면을 표시한다.
DLQ는 원본 payload와 stack trace로 가장 민감한 topic이 되기 쉽다. 별도 ACL/retention, redaction, restricted remediation tool을 둔다.
1212. 관측PROJECT POLICY
원인과 증상을 구분하는 최소 신호를 정한다.
retry attempts/rate/age, DLQ ingress/depth/oldest age, error class, replay rate/success/duplicate, key 순서 위반을 dashboard와 audit에 남긴다.
1313. runbookPROJECT POLICY
경보에서 안전한 복구까지의 의사결정을 고정한다.
DLQ 증가 → 공통 error/schema/dependency 확인 → producer 차단 여부 결정 → 표본 redacted 검사 → fix 검증 → throttle된 replay → reconciliation 순서로 수행한다.
1414. 산출물PROJECT POLICY
설명을 대신할 실행 증거를 남긴다.
error taxonomy, retry state machine, DLQ envelope, replay manifest와 operator audit를 제출한다.
1515. 완료 조건PROJECT POLICY
통과 조건을 관찰 가능한 문장으로 만든다.
모든 실패가 유한 시간/시도 안에 success·DLQ·quarantine 중 하나로 끝나고 replay가 추적·제한·멱등임을 증명한다.
1616. 자가시험RECOMMENDED PRACTICE
외운 정의가 아니라 장애 상황의 결정을 답한다.
각 답은 보장 범위, 실패 창, 관측 증거, 복구의 부작용을 포함해야 한다.
- 순서를 유지해야 하는 key에서 장기 backoff가 필요하면 어떤 대안들이 있는가?
- DLQ depth가 0인데도 장애가 남아 있을 수 있는 경로는?
Stream processing
011. 실체와 오해SPEC
용어의 닮은꼴과 실제 보장 경계를 분리한다.
stateless transform은 record별 계산이고 stateful transform은 partitioned local state와 changelog 복구를 사용한다. Kafka Streams EOS는 Kafka input/state/output 경계에 적용되며 외부 side effect는 별도다.
window와 watermark는 Kafka broker의 보편적 consumer 기능이 아니다. Kafka Streams의 window/grace/state-store semantics와 다른 엔진의 watermark 모델을 같은 말로 쓰면 안 된다.
022. 선수 지식PROJECT POLICY
실습 전에 알아야 할 최소 모델을 확인한다.
event time/processing time, window 종류, partitioned state, changelog replay, late event 정책을 이해해야 한다.
033. 15분 구조PROJECT POLICY
읽기보다 관찰과 설명에 시간을 쓴다.
0–3분: stateless · stateful 모델링. 3–8분: 정상 trace 수집. 8–13분: state directory를 제거하고 restart하여 full restore를 유도한 뒤, restore 중 lag와 output 정지 시간을 측정한다. late event를 grace 전후로 넣어 결과 차이도 확인한다. 13–15분: 증거로 보장 경계를 설명한다.
044. broker/client 내부SPEC
API 뒤의 상태 전이를 그린다.
source partition → task → processor topology → state store/cache → changelog → output/transaction commit을 추적하고 restart 시 restore lag를 별도 표시한다.
055. 최소 코드VERIFIED BEHAVIOR
가장 작은 실행 단위로 계약을 드러낸다.
order amount를 1분 window로 집계하고 process를 재시작해 changelog에서 state가 복구된 뒤 같은 결과가 나오는지 확인한다.
066. production 코드RECOMMENDED PRACTICE
명시적 실패 처리와 운영 경계를 더한다.
key/partition co-location, timestamp extractor, late/grace policy, store retention, standby/restore 목표, processing guarantee를 명시한다. 외부 API 호출은 topology transaction 밖임을 코드에 표시한다.
예제는 무한 retry, 무제한 batch, 암묵적 offset commit을 허용하지 않는다.
077. record 하나의 end-to-end traceVERIFIED BEHAVIOR
record ID 하나로 인과 경로를 복원한다.
input offset/timestamp, task ID, window bounds, state-store old/new value, changelog offset, output offset, transaction ID를 한 trace에 둔다.
088. 장애 주입VERIFIED BEHAVIOR
정상 경로가 숨기는 모호성을 강제로 노출한다.
state directory를 제거하고 restart하여 full restore를 유도한 뒤, restore 중 lag와 output 정지 시간을 측정한다. late event를 grace 전후로 넣어 결과 차이도 확인한다.
099. integration/contract/load testPROJECT POLICY
실행 결과를 재현 가능한 주장으로 바꾼다.
TopologyTestDriver 성격의 deterministic time test와 실제 broker restart/restore integration test를 분리하고, reprocessing 결과와 external side effect는 별도 검사한다.
1010. 성능과 용량RECOMMENDED PRACTICE
처리량만이 아니라 tail latency와 자원 비용을 본다.
input rate 외에 state bytes/key, changelog write amplification, cache/commit interval, restore bandwidth/time, window cardinality와 skew p99를 측정한다.
1111. 보안RECOMMENDED PRACTICE
신뢰 경계와 데이터 노출면을 표시한다.
local state와 changelog도 원문에서 파생된 민감 데이터다. disk encryption, topic ACL, state-dir lifecycle, interactive query 인증을 적용한다.
1212. 관측PROJECT POLICY
원인과 증상을 구분하는 최소 신호를 정한다.
task/partition lag, process/commit latency, state store size, cache hit/flush, changelog rate, restore remaining/latency, dropped late records를 본다.
1313. runbookPROJECT POLICY
경보에서 안전한 복구까지의 의사결정을 고정한다.
instance loss 시 assignment와 standby 존재를 확인하고 restore ETA가 RTO를 넘으면 scale/standby/rebuild 선택을 한다. state를 임의 복사하지 않는다.
1414. 산출물PROJECT POLICY
설명을 대신할 실행 증거를 남긴다.
topology diagram, time semantics 표, store/changelog mapping, restart/late-event evidence를 제출한다.
1515. 완료 조건PROJECT POLICY
통과 조건을 관찰 가능한 문장으로 만든다.
state가 어디에 있고 어떤 log로 복구되며 EOS가 어느 output까지 미치는지 restart trace로 설명한다.
1616. 자가시험RECOMMENDED PRACTICE
외운 정의가 아니라 장애 상황의 결정을 답한다.
각 답은 보장 범위, 실패 창, 관측 증거, 복구의 부작용을 포함해야 한다.
- late event와 out-of-order event는 항상 같은 처리 결과를 가져야 하는가?
- standby replica가 있어도 외부 API exactly-once가 되지 않는 이유는?
Capacity
011. 실체와 오해SPEC
용어의 닮은꼴과 실제 보장 경계를 분리한다.
한 consumer group에서 partition은 동시에 한 member에 할당되므로 parallelism 상한을 만든다. replication은 leader ingress 외 follower replication network/disk 비용을 추가한다.
partition을 늘리면 처리량이 선형 증가하지 않는다. metadata, file handles, leader election, recovery, client memory 비용과 key skew가 먼저 병목이 될 수 있다.
022. 선수 지식PROJECT POLICY
실습 전에 알아야 할 최소 모델을 확인한다.
Little's Law, percentile, saturation, compression CPU trade-off, growth/peak/safety factor를 계산할 수 있어야 한다.
033. 15분 구조PROJECT POLICY
읽기보다 관찰과 설명에 시간을 쓴다.
0–3분: partition count · consumer parallelism 모델링. 3–8분: 정상 trace 수집. 8–13분: 한 hot key로 대부분의 traffic을 한 partition에 몰아넣고, disk write 제한으로 포화를 만든다. 예상 증거는 cluster 평균과 달리 한 partition/broker의 p99·lag·queue만 치솟는 것이다. 13–15분: 증거로 보장 경계를 설명한다.
044. broker/client 내부SPEC
API 뒤의 상태 전이를 그린다.
producer accumulator/network → broker network/request threads → page cache/log flush/replication → consumer fetch/processing을 자원별 queue로 모델링한다.
055. 최소 코드VERIFIED BEHAVIOR
가장 작은 실행 단위로 계약을 드러낸다.
payload size, key distribution, batch, compression, producer concurrency, consumer cost를 한 번에 하나씩 바꿔 throughput과 p95/p99를 기록한다.
066. production 코드RECOMMENDED PRACTICE
명시적 실패 처리와 운영 경계를 더한다.
peak ingress/egress, replication, retention, replay, broker-loss N-1을 포함한 capacity sheet를 유지한다. partition 증가는 rollback이 어렵고 partitioner ordering에 영향을 줄 수 있어 change review가 필요하다.
예제는 무한 retry, 무제한 batch, 암묵적 offset commit을 허용하지 않는다.
077. record 하나의 end-to-end traceVERIFIED BEHAVIOR
record ID 하나로 인과 경로를 복원한다.
load run ID로 producer queue/send latency, broker request/IO, partition bytes, replication, consumer lag/process latency를 시간축 정렬한다.
088. 장애 주입VERIFIED BEHAVIOR
정상 경로가 숨기는 모호성을 강제로 노출한다.
한 hot key로 대부분의 traffic을 한 partition에 몰아넣고, disk write 제한으로 포화를 만든다. 예상 증거는 cluster 평균과 달리 한 partition/broker의 p99·lag·queue만 치솟는 것이다.
099. integration/contract/load testPROJECT POLICY
실행 결과를 재현 가능한 주장으로 바꾼다.
warm-up/steady/cool-down 단계, repeat count, fixed seed, pass threshold를 가진 load test를 실행하고 broker loss N-1에서도 SLO를 따로 판정한다.
1010. 성능과 용량RECOMMENDED PRACTICE
처리량만이 아니라 tail latency와 자원 비용을 본다.
disk≈ingress bytes/s×retention×replicas÷compression + indexes + 30% headroom으로 시작하되 실제 segment bytes와 peak를 보정한다. p95/p99, not average,가 SLO gate다.
1111. 보안RECOMMENDED PRACTICE
신뢰 경계와 데이터 노출면을 표시한다.
quota는 noisy neighbor와 runaway replay를 막는 보안/가용성 제어다. principal/client-id별 produce/fetch/request quota를 tenant budget과 연결한다.
1212. 관측PROJECT POLICY
원인과 증상을 구분하는 최소 신호를 정한다.
partition별 bytes/records, request queue/handler idle, network/disk utilization, page-cache pressure, URP, producer/consumer p95/p99, lag slope를 함께 표시한다.
1313. runbookPROJECT POLICY
경보에서 안전한 복구까지의 의사결정을 고정한다.
포화 시 먼저 hot partition, disk, network, CPU, downstream 중 병목을 증거로 분류한다. throttle/rebalance/scale/retention 변경은 RPO와 복구 비용을 검토 후 적용한다.
1414. 산출물PROJECT POLICY
설명을 대신할 실행 증거를 남긴다.
capacity model, reproducible load profile, p95/p99 report, hot-partition와 disk-saturation flame/timeline을 제출한다.
1515. 완료 조건PROJECT POLICY
통과 조건을 관찰 가능한 문장으로 만든다.
목표 traffic과 N-1에서 headroom을 수치로 제시하고 가장 먼저 포화되는 자원과 증거를 재현한다.
1616. 자가시험RECOMMENDED PRACTICE
외운 정의가 아니라 장애 상황의 결정을 답한다.
각 답은 보장 범위, 실패 창, 관측 증거, 복구의 부작용을 포함해야 한다.
- partition 2배가 consumer throughput 2배가 아닐 수 있는 세 이유는?
- compression이 network를 줄였는데 end-to-end p99가 늘 수 있는 이유는?
보안
011. 실체와 오해SPEC
용어의 닮은꼴과 실제 보장 경계를 분리한다.
Kafka는 TLS, SASL 기반 authentication, authorizer/ACL, client quota를 제공한다. 실제 지원 mechanism과 default는 고정한 Kafka/client 배포 문서와 설정에서 확인해야 한다.
private network나 TLS만으로 tenant 분리·권한·PII 보호가 끝나지 않는다. TLS는 transport를 보호하지만 잘못된 principal의 topic 접근을 막는 ACL을 대신하지 않는다.
022. 선수 지식PROJECT POLICY
실습 전에 알아야 할 최소 모델을 확인한다.
CA/certificate/hostname, principal, resource-pattern ACL, least privilege, secret rotation, data classification을 이해해야 한다.
033. 15분 구조PROJECT POLICY
읽기보다 관찰과 설명에 시간을 쓴다.
0–3분: TLS · authentication 모델링. 3–8분: 정상 trace 수집. 8–13분: 인증서 만료/hostname mismatch, revoked ACL, quota 초과를 각각 주입한다. 예상 증거는 authentication, authorization, throttling이 서로 다른 error/metric으로 나타나는 것이다. 13–15분: 증거로 보장 경계를 설명한다.
044. broker/client 내부SPEC
API 뒤의 상태 전이를 그린다.
TLS handshake → SASL authentication → principal mapping → request authorization → quota accounting → audit signal을 listener별로 추적한다.
055. 최소 코드VERIFIED BEHAVIOR
가장 작은 실행 단위로 계약을 드러낸다.
권한 없는 principal의 produce/consume/admin 요청이 거부되고, 올바른 principal은 필요한 topic/group만 접근함을 integration test한다.
066. production 코드RECOMMENDED PRACTICE
명시적 실패 처리와 운영 경계를 더한다.
broker/client/controller/inter-broker listener를 구분하고 TLS hostname validation, secret manager injection, least-privilege ACL, quota, rotation rehearsal을 적용한다.
예제는 무한 retry, 무제한 batch, 암묵적 offset commit을 허용하지 않는다.
077. record 하나의 end-to-end traceVERIFIED BEHAVIOR
record ID 하나로 인과 경로를 복원한다.
request correlation ID, client ID, authenticated principal, source, resource/operation, allow/deny, throttle time을 payload 없이 연결한다.
088. 장애 주입VERIFIED BEHAVIOR
정상 경로가 숨기는 모호성을 강제로 노출한다.
인증서 만료/hostname mismatch, revoked ACL, quota 초과를 각각 주입한다. 예상 증거는 authentication, authorization, throttling이 서로 다른 error/metric으로 나타나는 것이다.
099. integration/contract/load testPROJECT POLICY
실행 결과를 재현 가능한 주장으로 바꾼다.
allow/deny matrix, wildcard leakage, secret 없음/오류/rotation, TLS trust failure, quota isolation, payload redaction을 자동 검사한다.
1010. 성능과 용량RECOMMENDED PRACTICE
처리량만이 아니라 tail latency와 자원 비용을 본다.
TLS handshake/crypto CPU, re-authentication, ACL cardinality, quota throttle가 throughput/p99에 주는 비용을 측정하되 보안 해제를 튜닝으로 인정하지 않는다.
1111. 보안RECOMMENDED PRACTICE
신뢰 경계와 데이터 노출면을 표시한다.
PII payload를 최소화·암호화하고 headers/keys/logs/DLQ/schema의 간접 노출도 data lifecycle과 deletion 요청 범위에 포함한다.
1212. 관측PROJECT POLICY
원인과 증상을 구분하는 최소 신호를 정한다.
authn/authz failure, connection churn, certificate expiry, principal/client quota throttle, admin changes를 보되 secret·payload는 metric label로 쓰지 않는다.
1313. runbookPROJECT POLICY
경보에서 안전한 복구까지의 의사결정을 고정한다.
credential leak 시 principal 차단 → 영향 ACL/topic 확인 → secret/cert rotate → client rollout → audit/replay exposure 조사 순서로 진행한다.
1414. 산출물PROJECT POLICY
설명을 대신할 실행 증거를 남긴다.
threat model, listener/identity map, ACL test matrix, rotation log, PII/redaction inventory를 제출한다.
1515. 완료 조건PROJECT POLICY
통과 조건을 관찰 가능한 문장으로 만든다.
unauthorized path가 실제로 실패하고 authorized path가 최소 권한으로 작동하며 rotation 중 허용된 영향 범위를 측정한다.
1616. 자가시험RECOMMENDED PRACTICE
외운 정의가 아니라 장애 상황의 결정을 답한다.
각 답은 보장 범위, 실패 창, 관측 증거, 복구의 부작용을 포함해야 한다.
- topic READ ACL만 있는데 consumer가 실패할 수 있는 group 권한 경로는?
- payload를 안 찍어도 key/header/schema로 PII가 새는 예는?
운영
011. 실체와 오해SPEC
용어의 닮은꼴과 실제 보장 경계를 분리한다.
partition availability, ISR, request 처리, controller metadata, group assignment, disk는 서로 다른 상태 기계다. rolling upgrade와 reassignment는 version guide와 throttle/replica state를 따라야 한다.
consumer lag 하나로 cluster 건강을 판단할 수 없고, broker 재시작이 모든 경보의 안전한 첫 조치도 아니다. lag은 원인이 아니라 backlog 증상일 수 있다.
022. 선수 지식PROJECT POLICY
실습 전에 알아야 할 최소 모델을 확인한다.
SLO/error budget, RPO/RTO, saturation vs failure, rollback, change window와 evidence preservation을 이해해야 한다.
033. 15분 구조PROJECT POLICY
읽기보다 관찰과 설명에 시간을 쓴다.
0–3분: lag · URP · offline · ISR 모델링. 3–8분: 정상 trace 수집. 8–13분: broker kill과 disk 포화를 각각 주입해 URP/offline/request latency/lag의 순서를 비교한다. controller voter를 잃되 quorum 상실 전 stop condition을 지킨다. 13–15분: 증거로 보장 경계를 설명한다.
044. broker/client 내부SPEC
API 뒤의 상태 전이를 그린다.
client error/lag → broker request queue/disk → partition ISR/leader → controller metadata → client metadata/group rebalance의 인과 후보를 metric과 logs로 좁힌다.
055. 최소 코드VERIFIED BEHAVIOR
가장 작은 실행 단위로 계약을 드러낸다.
dashboard alert에서 시작해 topic describe, consumer group describe, broker/controller metric, structured log를 같은 incident timestamp로 수집한다.
066. production 코드RECOMMENDED PRACTICE
명시적 실패 처리와 운영 경계를 더한다.
모든 runbook에 trigger, blast radius, precheck, reversible mitigation, stop condition, validation, rollback, owner/audit를 둔다. rolling change는 compatibility matrix와 canary를 통과한다.
예제는 무한 retry, 무제한 batch, 암묵적 offset commit을 허용하지 않는다.
077. record 하나의 end-to-end traceVERIFIED BEHAVIOR
record ID 하나로 인과 경로를 복원한다.
incident ID로 first symptom, alert, client error, ISR/election/rebalance, operator command, recovery, backlog drain을 단일 timeline에 놓는다.
088. 장애 주입VERIFIED BEHAVIOR
정상 경로가 숨기는 모호성을 강제로 노출한다.
broker kill과 disk 포화를 각각 주입해 URP/offline/request latency/lag의 순서를 비교한다. controller voter를 잃되 quorum 상실 전 stop condition을 지킨다.
099. integration/contract/load testPROJECT POLICY
실행 결과를 재현 가능한 주장으로 바꾼다.
대표 broker/consumer failure, rolling restart, reassignment throttle, offset replay, backup/restore drill을 staging-sized data로 실행하고 RTO/RPO를 측정한다.
1010. 성능과 용량RECOMMENDED PRACTICE
처리량만이 아니라 tail latency와 자원 비용을 본다.
정상 headroom에 broker N-1, replica catch-up, reassignment, replay/backfill을 동시에 감당할 emergency budget을 별도 둔다.
1111. 보안RECOMMENDED PRACTICE
신뢰 경계와 데이터 노출면을 표시한다.
admin ACL과 break-glass credential을 일반 client에서 분리하고 모든 topic config, ACL, reassignment, offset reset 명령을 승인·감사한다.
1212. 관측PROJECT POLICY
원인과 증상을 구분하는 최소 신호를 정한다.
lag/ETA, URP/offline, ISR changes, disk used/latency, request queue/p95/p99, rebalance rate/duration, active controller/metadata lag, quota throttle를 service SLO에 연결한다.
1313. runbookPROJECT POLICY
경보에서 안전한 복구까지의 의사결정을 고정한다.
severity 판정 → write/read 영향과 durability 위험 분리 → reversible throttle/traffic shed → component 복구 → ISR/lag drain 확인 → post-incident reconciliation 순서다.
1414. 산출물PROJECT POLICY
설명을 대신할 실행 증거를 남긴다.
dashboard, alert rule, 5개 핵심 runbook, failure drill timeline, rolling upgrade/DR 계획을 제출한다.
1515. 완료 조건PROJECT POLICY
통과 조건을 관찰 가능한 문장으로 만든다.
lag, URP, offline, ISR shrink, disk saturation, request latency, rebalance, controller 장애를 서로 구분해 안전한 첫 조치와 중단 조건을 실행한다.
1616. 자가시험RECOMMENDED PRACTICE
외운 정의가 아니라 장애 상황의 결정을 답한다.
각 답은 보장 범위, 실패 창, 관측 증거, 복구의 부작용을 포함해야 한다.
- URP 증가와 offline partition 증가의 고객 영향이 다른 이유는?
- disk 90%에서 retention을 즉시 줄이는 조치의 숨은 위험은?
primary evidence · checked 2026-07-15
문서도 versioned dependency다
Kafka core 주장은 Apache Kafka 4.3 문서에, schema compatibility 주장은 선택한 registry의 공식 문서에 연결합니다. vendor 규칙을 Kafka core SPEC으로 부르지 않습니다.
- 01Apache Kafka 4.3.1 downloadskafka.apache.org ↗
- 02Official Kafka Docker imagekafka.apache.org ↗
- 03KRaft controller and metadatakafka.apache.org ↗
- 04Kafka design and delivery semanticskafka.apache.org ↗
- 05Producer configurationkafka.apache.org ↗
- 06Consumer configurationkafka.apache.org ↗
- 07Consumer rebalance protocolkafka.apache.org ↗
- 08Eligible Leader Replicaskafka.apache.org ↗
- 09Kafka monitoringkafka.apache.org ↗
- 10Kafka security overviewkafka.apache.org ↗
- 11Confluent Schema Registry compatibilitydocs.confluent.io ↗
completion gate · three levels
test pass와 product 성공을 섞지 않는다
명령과 경로
cluster, producer/consumer, duplicate restart, schema, broker/consumer failure, load, web build가 검증 환경에서 실행되어야 합니다.
판정 가능한 출력
eventId·offset·ISR·lag·side effect count가 기대값과 일치하고 source/hash/accessibility 검사가 통과해야 합니다.
실제 설명 능력
학습자가 unknown outcome과 duplicate window를 증거로 분리하고 올바른 recovery를 선택하는지 관찰해야 합니다.
이 사이트가 증명하지 않는 것
laptop load 결과는 production capacity가 아니며, PLAINTEXT lab은 production security 구성이 아닙니다.