llm-wiki/raw/official-docs/kafka-message-delivery-semantics-design.md

title, source_type, url, archive_url, related_branches, related_projects, tags, created

title	source_type	url	archive_url	related_branches	related_projects	tags	created
official-doc / Kafka Message Delivery Semantics — At-Least-Once, Idempotent Producer, Transactional Delivery Scope	official-doc	https://docs.confluent.io/kafka/design/delivery-semantics.html		feature-kafka-producer-runtime-contract	ca-skeleton	official-doc ca-skeleton messaging kafka idempotency	2026-07-28

Kafka Message Delivery Semantics — At-Least-Once, Idempotent Producer, Transactional Delivery Scope

Layer: raw/ — 외부 자료(공식 문서)의 원문 발췌·출처 기록. 문서 버전: Confluent Documentation "Kafka Message Delivery Guarantees" (Apache Kafka Design 섹션) — 특정 개정일 미표기.

source_type

official-doc — 이 페이지는 하단에 "This website includes content developed at the Apache Software Foundation under the terms of the Apache License v2" 고지를 명시한다. 즉 Confluent 문서 사이트가 호스팅하지만, 인용 대상 내용 자체는 Apache Kafka 프로젝트의 공식 semantics 설계 서술이다. 원 요청 URL은 접근 불가했다 — 아래 "URL Fetch 실패 기록" 참조.

URL Fetch 실패 기록 (원 요청 URL)

• 요청된 URL: https://kafka.apache.org/documentation/#semantics
• 시도 1 (WebFetch, #semantics 앵커 포함): nav/redirect 셸만 반환, "Message Delivery Semantics" 섹션 본문 없음
• 시도 2 (WebFetch, 앵커 제거 https://kafka.apache.org/documentation/): 동일 — 네비게이션 메뉴·릴리스 목록·footer만 포함
• 시도 3 (curl 직접 fetch, kafka.apache.org/documentation.html 및 /40/, /39/, /38/, /37/, /36/documentation.html 버전별 순회): 전부 <title>Documentation Redirect Legacy | Apache Kafka</title> 셸 페이지(19,985 bytes 동일), "Message Delivery" 문자열 0건
• 판정: 현재 kafka.apache.org 문서 사이트는 JS 렌더링 SPA로 전환되어 정적 fetch로는 본문에 도달 불가. 사용자가 사전 승인한 fallback 절차에 따라 https://docs.confluent.io/kafka/design/delivery-semantics.html 사용.

Parent / 활용 branch

Branch	이 자료가 정당화하는 결정
raw/branch-notes/feature-kafka-producer-runtime-contract	ca-skeleton 이 producer 측 보증을 "idempotent producer 로 파티션 단위 중복 제거된 at-least-once" 로 표현하고, DB 와 broker 를 걸친 exactly-once 는 주장하지 않는다는 상속 결정(DEC-CA-SKELETON-OPERATIONAL-CONTRACT-DELIVERY-SEMANTICS-001@1)의 경계를 공식 문장으로 고정한다

출처

• 원본 URL (요청됨, 접근 불가): https://kafka.apache.org/documentation/#semantics
• 실제 인용 URL (fallback, 사용됨): https://docs.confluent.io/kafka/design/delivery-semantics.html
• 아카이브 URL: (미제공)
• 저자 / 조직: Confluent, Inc. (문서 콘텐츠는 Apache Software Foundation 개발분 재게시, Apache License v2 고지)
• 발행일: 명시 없음 (footer: "Copyright © Confluent, Inc. 2014-", 개정일 미표기)
• 마지막 확인일: 2026-07-28

왜 저장했는지

feature-kafka-producer-runtime-contract 브랜치가 상속한 project 결정(DEC-CA-SKELETON-OPERATIONAL-CONTRACT-DELIVERY-SEMANTICS-001@1: "end-to-end 메시징 보증은 at-least-once 전달과 멱등 consumer·inbox로 표현하고 DB와 broker를 걸친 exactly-once를 주장하지 않는다")의 경계를 Kafka 공식 semantics 개념(at-least-once/exactly-once 정의, idempotent producer, transactional producer, exactly-once 적용 범위)으로 뒷받침하기 위함. 단, "그 보장이 파티션 단위"라는 정확한 스코프 표현은 본 페이지 어디에도 없다 — Self-Grep 결과 및 §메모 참조.

핵심 인용

[§Semantic guarantees] "At least once: This means messages are delivered one or more times. If there is a system failure, messages are never lost, but they may be delivered more than once."

[§Semantic guarantees] "Exactly once: This is the preferred behavior in that each message is delivered once and only once. Messages are never lost or read twice even if some part of the system fails."

[§Producer delivery — idempotent 옵션] "The idempotent delivery option guarantees that resending a message will not result in duplicate entries in the log, and that log order is maintained. To achieve this, the broker assigns each producer an ID and deduplicates messages using a sequence number that is sent by the producer with every message."

[§Producer delivery — Exactly once (transactional)] "Exactly once - Starting with version 0.11.0.0, producers can utilize transactional delivery. This means a producer can request acknowledgment that messages were received and successfully replicated, and if it resends a message, it resends with idempotency, meaning existing messages are overwritten rather than duplicated."

[§Exactly once support] "Kafka supports exactly-once delivery in Kafka Streams and uses transactional producers and consumers to provide exactly-once delivery when transferring and processing data between Kafka topics." [...] "Otherwise, by default Kafka guarantees at-least-once delivery."

Claims Extracted

Claim ID	Claim	Evidence quote	Strength	Applies to	Does not prove
KAFKA-SEM-C1	at-least-once 는 "메시지가 1회 이상 전달됨: 실패 시 유실되지 않지만 중복 전달될 수 있음" 으로 정의된다	"At least once: This means messages are delivered one or more times. If there is a system failure, messages are never lost, but they may be delivered more than once."	official-vendor-doc	Kafka broker/producer/consumer 간 semantic guarantee 용어 정의 일반	ca-skeleton 이 실제로 at-least-once 를 달성한다는 것(설정·구현 사실)은 증명하지 않는다 — 이는 용어 정의일 뿐 프로젝트 구현 증거가 아니다
KAFKA-SEM-C2	exactly-once 는 "각 메시지가 정확히 한 번만 전달됨: 시스템 일부가 실패해도 유실되거나 두 번 읽히지 않음" 으로 정의되며 "선호되는(preferred) 동작" 으로 서술된다	"Exactly once: This is the preferred behavior in that each message is delivered once and only once. Messages are never lost or read twice even if some part of the system fails."	official-vendor-doc	exactly-once 라는 용어 자체의 정의	Kafka 가 모든 상황에서 exactly-once 를 실제로 제공한다는 것은 증명하지 않는다 — 페이지 자체가 바로 다음 문장에서 "many systems claim to provide exactly once ... but this might not always what you think it is" 라고 경고하며, 적용 범위는 KAFKA-SEM-C5 로 별도 한정된다
KAFKA-SEM-C3	idempotent producer 옵션은 "메시지 재전송이 로그에 중복 항목을 만들지 않고, 로그 순서가 유지됨"을 보장하며, 이는 broker가 producer마다 ID를 부여하고 매 메시지에 동봉되는 sequence number로 중복 제거하는 방식으로 달성된다	"The idempotent delivery option guarantees that resending a message will not result in duplicate entries in the log, and that log order is maintained. To achieve this, the broker assigns each producer an ID and deduplicates messages using a sequence number that is sent by the producer with every message."	official-vendor-doc	Kafka producer의 idempotent delivery(0.11.0.0+) 재시도 시 broker측 중복 제거 메커니즘	"파티션 단위(per-partition)" 라는 단어를 이 페이지는 전혀 쓰지 않는다. "log" 라는 표현만 사용하며, Kafka의 로그가 topic-partition 단위로 존재한다는 사실은 이 문서 밖의 일반 지식으로 추론될 뿐 본문이 명시적으로 진술하지 않는다 — Self-Grep 실패 항목으로 아래 보고. 또한 producer 재시작(새 PID 발급) 시 이전 세션의 중복 제거 상태가 유지되는지도 이 문서는 언급하지 않는다
KAFKA-SEM-C4	0.11.0.0부터 producer는 transactional delivery를 쓸 수 있으며, 메시지 수신·복제 완료 ack를 요청할 수 있고, 재전송 시 idempotency로 기존 메시지를 덮어써 중복시키지 않는다(더 높은 지연 대신 더 높은 내구성)	"Exactly once - Starting with version 0.11.0.0, producers can utilize transactional delivery. This means a producer can request acknowledgment that messages were received and successfully replicated, and if it resends a message, it resends with idempotency, meaning existing messages are overwritten rather than duplicated."	official-vendor-doc	Kafka 내부(브로커/토픽/파티션)에 대한 transactional producer 동작	DB 트랜잭션과의 원자성은 증명하지 않는다. 이 인용은 Kafka 브로커에 대한 producer의 ack/재전송 동작만 서술하며, 외부 데이터베이스 write 와 Kafka publish 를 하나의 원자적 단위로 묶는다는 진술은 어디에도 없다
KAFKA-SEM-C5	Kafka Streams는 transactional producer/consumer를 이용해 "Kafka 토픽 간(between Kafka topics) 데이터를 옮기고 처리할 때" exactly-once를 제공하며, 그 외 consumer/producer 시스템은 Kafka Connect API의 자동 offset 관리를 써야 하고, 그렇지 않으면 Kafka는 기본적으로 at-least-once를 보장한다	"Kafka supports exactly-once delivery in Kafka Streams and uses transactional producers and consumers to provide exactly-once delivery when transferring and processing data between Kafka topics." [...] "Otherwise, by default Kafka guarantees at-least-once delivery."	official-vendor-doc	Kafka 내장 exactly-once의 적용 범위(intra-Kafka topic-to-topic) vs 그 밖의 시스템	이 문장은 "DB와 broker를 걸친 exactly-once가 불가능하다"를 명시적으로 부정하지 않는다. "between Kafka topics" 로 범위를 한정하고, 외부 시스템은 Connect API의 offset 관리에 위임한다고만 말할 뿐이며, 임의의 DB write 가 Kafka publish 와 원자적으로 결합될 수 있는지/없는지에 대한 직접 진술은 이 페이지에 없다

Strength 참고

모두 official-vendor-doc — RFC/표준(official-standard)이 아니라 Kafka 프로젝트(Apache Software Foundation 개발분, Confluent 재게시)의 공식 설계 문서 서술이다.

Usage Boundaries

• 이 자료가 직접 증명하는 것:
  • KAFKA-SEM-C1: at-least-once 의 정의(1회 이상 전달, 실패 시 무손실이나 중복 가능)
  • KAFKA-SEM-C2: exactly-once 의 정의(정확히 1회, 무손실·무중복) 및 이 페이지가 이를 "선호되는 동작"으로 규정한다는 것
  • KAFKA-SEM-C3: idempotent producer 가 broker-assigned ID + per-message sequence number 로 재전송 시 로그 중복을 막는다는 메커니즘
  • KAFKA-SEM-C4: 0.11.0.0+ transactional producer 가 ack 요청 + idempotent 재전송(overwrite, not duplicate)을 제공한다는 것
  • KAFKA-SEM-C5: Kafka 내장 exactly-once 의 명시적 적용 범위가 "Kafka 토픽 간"이며, 그 밖의 시스템은 Connect API offset 관리에 의존한다는 것, 기본값은 at-least-once 라는 것
• 이 자료가 증명하지 않는 것:
  • idempotent producer 보장이 "파티션 단위"라는 정확한 스코프 문구. 이 페이지는 그 단어를 쓰지 않는다(KAFKA-SEM-C3 참조) — branch-note 나 project 결정문에서 "파티션 단위"라는 표현을 쓰려면 이 문서만으로는 근거가 부족하고, Kafka producer configs 공식 문서(enable.idempotence 항목, Javadoc)로 별도 보강이 필요하다
  • Kafka transactional producer 가 DB write 와 원자적으로 결합된다는 것(KAFKA-SEM-C4, KAFKA-SEM-C5) — 이 문서 범위 안에서는 Kafka 내부(토픽/파티션) transactional write만 다루며, DB-broker 이중 쓰기(dual-write) 원자성에 대한 진술은 전혀 없다
  • Kafka 가 모든 상황에서 exactly-once 를 보장한다는 일반 주장 — 페이지 스스로 "many systems claim to provide exactly once delivery semantics, but this might not always be what you think it is" 라고 경고하며 범위를 한정한다
• 내 프로젝트에 적용하려면 추가 확인이 필요한 것:
  • "파티션 단위 중복 제거"의 정확한 공식 문구 — Kafka producer configs 문서(enable.idempotence) 또는 Javadoc 별도 인용 필요
  • acks=all + idempotent producer 조합이 실제로 ca-skeleton 설정에 반영되는지 — 별도 구현 증거(코드/설정) 필요
  • Kafka Connect API 의 offset 관리가 실제로 임의 외부 DB(비-Connect 커스텀 consumer)에도 원자성을 제공하는지 — 이 페이지는 Connect 커넥터 예시(HDFS)만 들며 일반화하지 않는다

메모

• Self-Grep 실패 보고: "파티션 단위" 관련 원문 문구를 이 페이지(Confluent fallback)에서 찾지 못했다. 추측으로 채우지 않고 KAFKA-SEM-C3의 "Does not prove"에 명시했다. 필요 시 Apache Kafka producer configs 공식 문서(enable.idempotence)를 별도 raw 문서로 수집해 이 gap 을 메워야 한다.
• 원 요청 URL(kafka.apache.org/documentation/#semantics)은 현재 정적 fetch로 접근 불가한 JS 렌더링 nav 셸이다 — 향후 재시도 시 브라우저 렌더링 기반 도구가 필요할 수 있다.
• 같은 branch 의 다른 raw 문서(raw/official-docs/spring-kafka-sending-messages-kafkatemplate.md)가 이미 "acks=all + enable.idempotence 설정 자체"를 다루는 Kafka producer configs 공식 문서 보강이 필요하다고 지적한 바 있다 — 동일 gap.

관련

• 같은 branch 의 다른 official-doc: raw/official-docs/spring-kafka-sending-messages-kafkatemplate.md — KafkaTemplate.send() 반환 타입/동기 대기 메커니즘 (같은 branch, 인접 관심사)
• 이 자료를 인용한 wiki 요약: (생성 시 링크)