donghyeon.kang/llm-wiki

Fork 0

Files

T

DongHyeonka 58515ab0f3 feat: 공식 문서 근거자료, 브랜치 기능 문서 작성

2026-07-29 18:05:17 +09:00

16 KiB

Raw Permalink Blame History

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

title

source_type

url

archive_url

related_branches

related_projects

official-doc / Apache Kafka — KafkaProducer Javadoc (acks, idempotent producer, ordering, flush/close)

Layer: raw/ — 외부 자료(공식 문서)의 원문 발췌·출처 기록. 검증된 요약은 /ingest 후 wiki/concepts/에 별도 작성.

Parent / 활용 branch

Branch	이 자료가 정당화하는 결정
raw/branch-notes/feature-kafka-producer-runtime-contract	ca-skeleton 의 Kafka producer 런타임 계약에서 `acks=all` + idempotent producer 를 기본값으로 못박고, 순서 보장 경계(파티션 단위)와 graceful flush/close 의 의미를 메커니즘 수준(L1+)으로 확정하는 근거. 단, in-flight 상한(`max.in.flight.requests.per.connection`)에 대한 근거는 이 URL 범위 밖 — 아래 Usage Boundaries 참조.

출처

원본 URL: https://kafka.apache.org/40/javadoc/org/apache/kafka/clients/producer/KafkaProducer.html
아카이브 URL: (미제공 — 사용자 입력 없음)
저자 / 조직: Apache Software Foundation — Apache Kafka 프로젝트 공식 Javadoc (clients 모듈, org.apache.kafka.clients.producer.KafkaProducer). 페이지 타이틀 "KafkaProducer (kafka 4.0.2 API)" 로 버전 확인.
발행일: 명시 없음 (Kafka 4.0.x 라인 최신 Javadoc — URL 경로 /40/ = 4.0 branch)
마지막 확인일: 2026-07-28

왜 저장했는지

feature-kafka-producer-runtime-contract branch 가 acks=all + idempotent producer 를 기본값으로 못박으려면, acks 의 완료 판정 기준·idempotence 의 정확한 보장 범위와 전제조건·순서 보장 경계·flush/close 의 blocking semantics 가 공식 API 문서 수준에서 확정되어야 한다. 이 문서는 KafkaProducer 클래스 Javadoc 원문에서 그 근거를 직접 인용한다.

핵심 인용

[source: KafkaProducer class-level Javadoc, 클래스 상단 설명 문단] (line 번호는 /tmp/source-fetch-20260728-165959.txt 기준 — HTML→텍스트 변환 후 줄 번호)

[line 34] "The acks config controls the criteria under which requests are considered complete." [...] "The default setting "all" will result in blocking on the full commit of the record, the slowest but most durable setting."
[line 40] "The idempotent producer strengthens Kafka's delivery semantics from at least once to exactly once delivery." [...] "In particular producer retries will no longer introduce duplicates."
[line 41] "From Kafka 3.0, the enable.idempotence configuration defaults to true." [...] "When enabling idempotence, retries config will default to Integer.MAX_VALUE and the acks config will default to all."
[line 42] "the producer can only guarantee idempotence for messages sent within a single session."
[line 257, send(ProducerRecord, Callback) 메서드 설명] "Callbacks for records being sent to the same partition are guaranteed to execute in order."
[line 261, send(ProducerRecord, Callback) 메서드 설명] "it is possible to continue sending after receiving an OutOfOrderSequenceException, but doing so can result in out of order delivery of pending messages." [...] "To ensure proper ordering, you should close the producer and create a new instance."
[line 279, flush() 메서드 설명] "Invoking this method makes all buffered records immediately available to send (even if linger.ms is greater than 0) and blocks on the completion of the requests associated with these records." — 그리고 "A request is considered completed when it is successfully acknowledged according to the acks configuration you have specified or else it results in an error."
[line 346, close() 메서드 설명] "Close this producer. This method blocks until all previously sent requests complete. This method is equivalent to close(Long.MAX_VALUE, TimeUnit.MILLISECONDS)."
[line 347, close() 메서드 설명] "If close() is called from Callback, a warning message will be logged and close(0, TimeUnit.MILLISECONDS) will be called instead."
[line 38, 클래스 상단 설명 문단] "The buffer.memory controls the total amount of memory available to the producer for buffering." [...] "When the buffer space is exhausted additional send calls will block. The threshold for time to block is determined by max.block.ms after which it throws a TimeoutException."

총 10개 인용 (요청된 5개 우선순위 topic 을 모두 커버하기 위해 3~5개 권장 범위를 초과 — 각 topic 이 "보장 내용 + 전제조건/한계"의 2개 문장을 요구했기 때문). 전부 self-grep 통과.

Claims Extracted

Claim ID	Claim (이 자료가 직접 말하는 것)	Evidence quote	Strength	Applies to	Does not prove
KAFKA-PROD-JD-C1	`acks=all`(기본값)은 요청 완료 판정 기준을 "레코드의 full commit 대기"로 설정하며, 가장 느리지만 가장 durable 한 설정이다	[line 34] "The default setting "all" will result in blocking on the full commit of the record, the slowest but most durable setting."	official-reference	KafkaProducer 의 `acks` 설정값별 완료 판정 기준 일반	이 문서는 "full commit" 이 정확히 몇 개의 in-sync replica(ISR)를 의미하는지, `min.insync.replicas` 와 `acks=all` 의 관계를 설명하지 않는다(ISR 단어 자체가 이 페이지에 없음). 또한 "항상 acks=all 을 써야 한다"는 권고문도 아니다 — 트레이드오프(느림) 서술만 있음.
KAFKA-PROD-JD-C2	idempotent producer 는 Kafka 의 전달 시맨틱을 at-least-once 에서 exactly-once 로 강화하며, producer 재시도가 더 이상 중복을 유발하지 않는다	[line 40] "The idempotent producer strengthens Kafka's delivery semantics from at least once to exactly once delivery. In particular producer retries will no longer introduce duplicates."	official-reference	`enable.idempotence=true` 일 때 producer 재전송으로 인한 duplicate 제거 보장	DB write 등 producer 바깥의 side effect 까지 포함한 end-to-end exactly-once 를 주장하지 않는다. 이 문서 자체가 이 범위를 명시하지 않으므로 확대 해석 금지 — project 결정(`DEC-CA-SKELETON-OPERATIONAL-CONTRACT-DELIVERY-SEMANTICS-001@1`, at-least-once + 멱등 consumer)과 병기해야 함.
KAFKA-PROD-JD-C3	Kafka 3.0+ 부터 `enable.idempotence` 기본값이 `true`이며, idempotence 활성 시 `retries`는 `Integer.MAX_VALUE`, `acks`는 `all` 로 자동 기본 설정된다	[line 41] "From Kafka 3.0, the enable.idempotence configuration defaults to true. When enabling idempotence, retries config will default to Integer.MAX_VALUE and the acks config will default to all."	official-reference	idempotent producer 활성 시 `acks`/`retries` 자동 강제값의 근거	`max.in.flight.requests.per.connection` 상한과 idempotence 의 관계는 이 URL(KafkaProducer 클래스 Javadoc)에 언급이 없다 — self-grep 결과 0건(negative control 확인됨). 순서 보장을 위한 in-flight 상한 수치는 별도 `ProducerConfig` 공식 문서로 보강 필요(`UNSUPPORTED_DECISION` 후보 — 아래 Usage Boundaries 참조).
KAFKA-PROD-JD-C4	producer 는 단일 세션(session) 내에서 전송된 메시지에 대해서만 idempotence 를 보장한다	[line 42] "the producer can only guarantee idempotence for messages sent within a single session."	official-reference	producer 재시작/재생성 시 idempotence 보장이 리셋됨을 아는 근거	"세션"의 정확한 경계(예: producer epoch 변경 시점, transactional.id fencing 과의 관계)를 상세히 정의하지 않는다.
KAFKA-PROD-JD-C5	같은 파티션으로 전송되는 레코드의 콜백은 전송 순서대로 실행됨이 보장된다	[line 257] "Callbacks for records being sent to the same partition are guaranteed to execute in order."	official-reference	파티션 단위(partition-level) 순서 보장의 1차 근거	파티션을 넘나드는 전역 순서를 보장한다고 말하지 않는다. 또한 이 순서 보장이 `max.in.flight.requests.per.connection` 값에 어떻게 의존하는지는 이 페이지에 없다(negative control 확인됨).
KAFKA-PROD-JD-C6	idempotence 활성 상태에서 `OutOfOrderSequenceException` 수신 후 재전송을 계속하면 pending 메시지의 out-of-order 전달이 발생할 수 있으며, 순서를 보장하려면 producer 를 close 하고 새 인스턴스를 만들어야 한다	[line 261] "it is possible to continue sending after receiving an OutOfOrderSequenceException, but doing so can result in out of order delivery of pending messages. To ensure proper ordering, you should close the producer and create a new instance."	official-reference	idempotent producer 에서 순서가 깨질 수 있는 구체적 실패 경로와 복구 절차(재발급)	이 실패가 `max.in.flight.requests.per.connection > 5` 조합에서만 발생하는지, 혹은 다른 조건에서도 발생하는지는 이 페이지가 설명하지 않는다.
KAFKA-PROD-JD-C7	`flush()`는 buffer 에 있는 모든 레코드를 즉시 전송 가능 상태로 만들고, 그 요청들이 acks 설정에 따라 성공 ack 되거나 에러가 날 때까지 블로킹한다	[line 279] "Invoking this method makes all buffered records immediately available to send (even if linger.ms is greater than 0) and blocks on the completion of the requests associated with these records." / "A request is considered completed when it is successfully acknowledged according to the acks configuration you have specified or else it results in an error."	official-reference	graceful flush 의 완료 판정 기준(acks 설정에 연동됨)	`flush()`에는 timeout 파라미터가 없다(무기한 대기)는 것 외의 취소/중단 메커니즘은 설명하지 않는다. send 콜백 안에서 호출하면 데드락이라는 점은 별도 문장(같은 메서드 doc 후반)에 있으나 본 claim 인용에는 포함하지 않음.
KAFKA-PROD-JD-C8	`close()`는 기본적으로 이전에 전송된 모든 요청이 완료될 때까지 블로킹하며 `close(Long.MAX_VALUE, TimeUnit.MILLISECONDS)`와 동일하다. 콜백 내부에서 `close()`가 호출되면 sender thread 의 self-join 데드락을 피하기 위해 `close(0, TimeUnit.MILLISECONDS)`로 대체 실행된다	[line 346] "Close this producer. This method blocks until all previously sent requests complete. This method is equivalent to close(Long.MAX_VALUE, TimeUnit.MILLISECONDS)." / [line 347] "If close() is called from Callback, a warning message will be logged and close(0, TimeUnit.MILLISECONDS) will be called instead."	official-reference	graceful shutdown 시 `close()` 기본 blocking 동작과 콜백 내 호출의 예외적 non-blocking 동작	`close(Duration timeout)` 오버로드에서 "timeout 초과 시 unsent/unacknowledged record 를 즉시 fail 처리한다"는 별도 동작은 이 두 quote 에 포함되지 않는다(문서 내 다른 위치, 별도 claim 필요 시 추가 인용).
KAFKA-PROD-JD-C9	`buffer.memory`가 소진되면 추가 `send()` 호출이 블로킹되며, 블로킹 대기 시간의 상한은 `max.block.ms`이고 이를 초과하면 `TimeoutException`이 발생한다	[line 38] "The buffer.memory controls the total amount of memory available to the producer for buffering." / "When the buffer space is exhausted additional send calls will block. The threshold for time to block is determined by max.block.ms after which it throws a TimeoutException."	official-reference	producer buffer backpressure 메커니즘(client-side back-pressure)의 근거	`max.block.ms` 초과 시 애플리케이션이 취해야 할 재시도/서킷브레이커 전략까지 규정하지 않는다 — 그건 애플리케이션 책임이라는 것도 명시하지 않는다(단순히 예외 발생만 서술).

Strength 근거

모든 claim 은 official-reference — Apache Kafka 프로젝트가 배포하는 공식 API Javadoc(kafka.apache.org/40/javadoc/...)이며 RFC/표준 수준(official-standard)은 아니지만 벤더 자체의 공식 reference 문서다.

Usage Boundaries

이 자료가 직접 증명하는 것:
- acks=all의 완료 판정 기준(full commit 대기, 가장 durable, 가장 느림) — KAFKA-PROD-JD-C1
- idempotent producer 의 exactly-once(중복 제거) 보장과 그 세션 스코프 한계 — KAFKA-PROD-JD-C2, C4
- idempotence 활성 시 acks=all/retries=MAX_VALUE 자동 기본값 — KAFKA-PROD-JD-C3
- 파티션 단위 콜백 순서 보장과 idempotence 하에서 순서가 깨질 수 있는 구체적 실패 경로(OutOfOrderSequenceException) — C5, C6
- flush()/close()의 기본 blocking 의미론 — C7, C8
- buffer.memory/max.block.ms backpressure 메커니즘 — C9
이 자료가 증명하지 않는 것 (중요 — branch 결정에 그대로 쓰면 안 됨):
- max.in.flight.requests.per.connection 관련 어떤 문장도 이 URL 에 없다. self-grep negative control로 확인(grep -nF 'max.in.flight.requests.per.connection' → 0 매치). 따라서 "idempotence 활성 시 in-flight 상한이 5로 제한되어 순서가 보장된다"는 흔히 알려진 사실은 이 raw 문서만으로는 뒷받침되지 않는다. branch 의 §구현 가이드에서 in-flight 상한 수치를 명시하려면 ProducerConfig 공식 문서(별도 URL, 예: kafka.apache.org/.../ProducerConfig.html 또는 Kafka 운영 가이드의 max.in.flight.requests.per.connection 설명)를 별도로 수집해 UNSUPPORTED_DECISION 라벨을 해소해야 한다.
- ISR(in-sync replica) 개수·min.insync.replicas와 acks=all의 정확한 상호작용(이 페이지에 "in-sync"/"ISR" 단어 자체가 없음 — grep 확인, min.insync.replicas는 트랜잭션 섹션에서만 "should be set to 2"로 1회 등장하며 acks=all 의 일반 정의와 직접 연결되어 서술되지 않음)
- "항상 acks=all을 써야 한다"는 규범적 권고 — 이 문서는 트레이드오프만 서술하고 prescriptive 하지 않음
- DB write 와 Kafka publish 를 아우르는 end-to-end exactly-once
- 압축(compression)·배치 상한·TLS/SASL·스키마 호환성 등 branch 범위의 다른 항목 (이 URL 은 다루지 않음 — 별도 자료 필요)
내 프로젝트에 적용하려면 추가 확인이 필요한 것:
- ca-skeleton Kafka producer adapter 의 실제 application.yml/ProducerConfig 설정값이 이 문서의 기본값과 일치하는지 (acks=all, enable.idempotence=true) — 코드 레벨 검증 필요
- max.in.flight.requests.per.connection 상한값 — 위 한계 참조, 별도 공식 문서 수집 필요

메모

검증되지 않은 추론은 여기에만 둔다. wiki/concepts 로 옮길 때 재검토.

HTML→텍스트 변환은 stdlib html.parser 로 직접 작성한 스크립트를 사용(환경에 bs4/html2text/pandoc/lynx 부재 확인). 블록 태그 경계에서만 줄바꿈을 넣고, 텍스트 노드 내부 개행은 공백으로 접어서 문장이 잘리지 않게 함 — self-grep 안정성을 위한 선택.
다음 작업 후보: ProducerConfig Javadoc 또는 Kafka 공식 "Configuration" 레퍼런스 페이지에서 max.in.flight.requests.per.connection 원문을 별도 raw 문서로 수집해 이 문서의 KAFKA-PROD-JD-C3/C5/C6 한계를 해소.
WebFetch 도구의 1차 결과(요약 모델 처리본)는 이 문서 작성에 사용하지 않음 — self-grep 검증이 불가능한 paraphrase 였기 때문에 폐기하고 curl raw HTML → 자체 텍스트 추출로 재작업함.

16 KiB Raw Permalink Blame History