donghyeon.kang/llm-wiki

Fork 0

Files

T

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

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

15 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 — KafkaConsumer Javadoc (offset commit semantics — auto vs manual, commitSync/commitAsync)

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

Parent / 활용 branch

Branch 이 자료가 정당화하는 결정

raw/branch-notes/feature-kafka-consumer-inbox-contract ca-skeleton 의 Kafka consumer 가 "application use case 성공 + inbox/비즈니스 트랜잭션 커밋 이후에만 offset 을 커밋(ack)" 하는 계약을 채택하고 enable.auto.commit 자동 커밋을 기각하는 근거 — 자동 커밋의 at-least-once 전제조건(poll 이후 전량 소비 필요)과 수동 커밋의 중복 창(commit 직전 crash → 재소비) 메커니즘을 공식 문서 수준에서 확정한다

Branch	이 자료가 정당화하는 결정
raw/branch-notes/feature-kafka-consumer-inbox-contract	ca-skeleton 의 Kafka consumer 가 "application use case 성공 + inbox/비즈니스 트랜잭션 커밋 이후에만 offset 을 커밋(ack)" 하는 계약을 채택하고 `enable.auto.commit` 자동 커밋을 기각하는 근거 — 자동 커밋의 at-least-once 전제조건(poll 이후 전량 소비 필요)과 수동 커밋의 중복 창(commit 직전 crash → 재소비) 메커니즘을 공식 문서 수준에서 확정한다

출처

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

왜 저장했는지

feature-kafka-consumer-inbox-contract branch 가 "application 성공 이후에만 manual ack" 계약을 채택하고 enable.auto.commit(자동 커밋)을 기각하려면, 자동 커밋이 실제로 무엇을 보장/전제하는지와 수동 커밋에서도 남는 중복 창이 공식 API 문서 수준에서 확정되어야 한다. 이 문서는 KafkaConsumer Javadoc의 "Usage Examples" 절(Automatic Offset Committing / Manual Offset Control)과 commitSync/commitAsync 메서드 계약에서 그 근거를 직접 인용한다.

핵심 인용

[line 번호는 /tmp/source-fetch-20260728171542.txt 기준 — HTML→텍스트 변환 후 줄 번호. 원문은 여러 물리 줄로 개행되어 있어(Javadoc 소스 주석의 원 줄바꿈 보존), 인용 안 문장이 줄바꿈을 가로지르는 경우 그 사실을 명시한다.]

[line 147-148, §Automatic Offset Committing] "Setting enable.auto.commit means that offsets are committed automatically with a frequency controlled by the config auto.commit.interval.ms."
[line 190-193, §Automatic Offset Committing, Note] "Using automatic offset commits can also give you "at-least-once" delivery, but the requirement is that you must consume all data returned from each call to poll(Duration) before any subsequent calls, or before closing the consumer. If you fail to do either of these, it is possible for the committed offset to get ahead of the consumed position, which results in missing records."
[line 156, §Manual Offset Control] "a message should not be considered as consumed until it is completed processing."
[line 185-189, §Manual Offset Control] "the process could fail in the interval after the insert into the database but before the commit (even though this would likely just be a few milliseconds, it is a possibility). In this case the process that took over consumption would consume from last committed offset and would repeat the insert of the last batch of data. Used in this way Kafka provides what is often called "at-least-once" delivery guarantees, as each record will likely be delivered one time but in failure cases could be duplicated."
[line 879-881, commitSync() 메서드 설명] "This is a synchronous commit and will block until either the commit succeeds, an unrecoverable error is encountered (in which case it is thrown to the caller), or the timeout specified by default.api.timeout.ms expires (in which case a TimeoutException is thrown to the caller)." — 그리고 [line 1069-1070, commitAsync(OffsetCommitCallback) 메서드 설명] "This is an asynchronous call and will not block. Any errors encountered are either passed to the callback (if provided) or discarded."

총 5개 topic, 6개 원문 문장(인용 5는 commitSync/commitAsync 대조를 위해 2개 문장을 함께 인용). 전부 self-grep 통과(아래 Self-Grep 결과 참조 — 물리 줄바꿈을 포함하는 인용은 grep -Pzo로 개행 포함 패턴 매칭해 검증).

Claims Extracted

Claim ID	Claim (이 자료가 직접 말하는 것)	Evidence quote	Strength	Applies to	Does not prove
KAFKA-OFFSET-C1	`enable.auto.commit=true` 는 offset 을 `auto.commit.interval.ms` 로 제어되는 주기로 자동 커밋한다	[line 147-148] "Setting enable.auto.commit means that offsets are committed automatically with a frequency controlled by the config auto.commit.interval.ms."	official-reference	`enable.auto.commit=true` 채택 시 커밋 타이밍 메커니즘 일반	이 자동 커밋 방식이 안전(무손실)함을 증명하지 않는다 — 그 전제조건은 별도 `KAFKA-OFFSET-C2`
KAFKA-OFFSET-C2	자동 오프셋 커밋으로도 "at-least-once" 전달을 얻을 수 있지만, 전제조건은 매 `poll(Duration)` 호출이 반환한 데이터를 다음 poll 또는 close 이전에 전부 소비해야 한다는 것이며, 이를 어기면 committed offset 이 consumed position 보다 앞서가 레코드 유실이 발생할 수 있다	[line 190-193] "Using automatic offset commits can also give you "at-least-once" delivery, but the requirement is that you must consume all data returned from each call to poll(Duration) before any subsequent calls, or before closing the consumer. If you fail to do either of these, it is possible for the committed offset to get ahead of the consumed position, which results in missing records."	official-reference	`enable.auto.commit=true` 채택을 기각하는 리스크 근거 — 비동기 처리/bounded concurrency/backpressure(pause-resume) 를 쓰는 handler 는 이 "poll 마다 전량 즉시 소비" 전제를 지키기 어렵다	ca-skeleton 의 실제 handler 실행 모델이 이 전제조건을 위반하는지 여부는 별도 구현 사실 확인이 필요 — 이 문서는 일반 리스크 조건만 서술하고 특정 구현을 언급하지 않는다
KAFKA-OFFSET-C3	consumption 이 별도 processing logic 과 결합된 경우, 메시지는 그 처리가 완료되기 전까지 consumed 로 간주되면 안 된다 — 이것이 Manual Offset Control(수동 오프셋 제어, `enable.auto.commit=false`)을 쓰는 이유로 제시된다	[line 156] "a message should not be considered as consumed until it is completed processing."	official-reference	manual commit 채택 근거 — "application/inbox 트랜잭션 커밋 이후에만 offset 을 ack" 하는 설계의 공식 문장 근거	정확히 어느 지점(같은 DB 트랜잭션 내부인지, 그 이후 별도 스텝인지)에서 commit 해야 하는지는 규정하지 않는다 — 그 구체 메커니즘은 project/branch 자체 결정(inbox 패턴) 소관
KAFKA-OFFSET-C4	수동 커밋을 쓰더라도 "DB insert 이후, commit 이전" 구간에 프로세스가 실패하면, 이어받은 프로세스가 마지막 committed offset 부터 재소비하여 마지막 batch 의 insert 를 반복하게 되고, 이것이 Kafka 가 "at-least-once" 라 부르는 전달 보증이며 레코드가 중복될 수 있다	[line 185-189] "the process could fail in the interval after the insert into the database but before the commit (even though this would likely just be a few milliseconds, it is a possibility). In this case the process that took over consumption would consume from last committed offset and would repeat the insert of the last batch of data. Used in this way Kafka provides what is often called "at-least-once" delivery guarantees, as each record will likely be delivered one time but in failure cases could be duplicated."	official-reference	수동 커밋을 채택해도 exactly-once 가 아니라 at-least-once + 재소비로 인한 중복 가능성이 남는다는 근거 — 별도 멱등(inbox/idempotency) 계층이 필요하다는 project 결정의 정당화	그 중복을 제거하는 멱등 메커니즘(unique key, owner token, inbox 테이블 등) 자체는 규정하지 않는다 — 이는 `DEC-CA-SKELETON-OPERATIONAL-CONTRACT-IDEMPOTENCY-OWNERSHIP-001` project 결정 소관이며 이 문서는 "중복이 가능하다"는 사실만 진술한다
KAFKA-OFFSET-C5	`commitSync()` 는 커밋 성공, 복구 불가능한 에러(호출자에게 throw), 또는 `default.api.timeout.ms` 만료(`TimeoutException` throw) 중 하나가 발생할 때까지 블로킹하는 동기 호출이다. 반대로 `commitAsync(OffsetCommitCallback)` 은 블로킹하지 않는 비동기 호출이며, 발생한 에러는 콜백으로 전달되거나(콜백 없으면) 버려진다	[line 879-881] "This is a synchronous commit and will block until either the commit succeeds, an unrecoverable error is encountered (in which case it is thrown to the caller), or the timeout specified by default.api.timeout.ms expires (in which case a TimeoutException is thrown to the caller)." / [line 1069-1070] "This is an asynchronous call and will not block. Any errors encountered are either passed to the callback (if provided) or discarded."	official-reference	manual ack 구현 시 `commitSync`/`commitAsync` 중 선택 기준 — 블로킹 허용 여부와 에러 가시성(throw vs callback/discard)의 근거	어느 것을 ca-skeleton 이 실제로 채택해야 하는지는 규정하지 않는다(트레이드오프만 서술) — 그 선택은 branch-local 결정(§구현 가이드) 소관. `commitAsync` 에러가 "discard" 될 수 있다는 것은 콜백 미제공 시의 위험을 알려줄 뿐, ca-skeleton 이 콜백을 반드시 제공해야 한다는 규범적 문장은 아니다

Strength 근거

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

Usage Boundaries

이 자료가 직접 증명하는 것:
- enable.auto.commit=true 의 커밋 타이밍 메커니즘 — KAFKA-OFFSET-C1
- 자동 커밋으로 at-least-once 를 얻기 위한 전제조건과 그 위반 시 레코드 유실 리스크 — KAFKA-OFFSET-C2
- Manual Offset Control 채택 근거("처리 완료 전까지 consumed 간주 금지") — KAFKA-OFFSET-C3
- 수동 커밋에서도 남는 중복(재소비) 창의 메커니즘 — KAFKA-OFFSET-C4
- commitSync/commitAsync 의 블로킹·에러 전달 방식 대조 — KAFKA-OFFSET-C5
이 자료가 증명하지 않는 것 (중요 — branch 결정에 그대로 쓰면 안 됨):
- rebalance·max.poll.interval.ms·max.poll.records·pause/resume backpressure 의 상세 계약. 이 raw 문서는 offset commit semantics(§핵심 인용 5개)만 발췌했다 — 같은 Javadoc 페이지 안에 rebalance/liveness 관련 문장이 존재하는 것은 확인했으나(§핵심 인용에는 미포함), branch 범위의 "rebalance 처리, poison/역직렬화 실패 분류, retry topic/DLT" 결정에는 이 raw 문서를 근거로 쓸 수 없다 — 별도 raw 문서(또는 이 문서의 후속 확장) 필요
- inbox 테이블 스키마·owner token 프로토콜 등 프로젝트 자체 멱등 메커니즘의 구체 설계 — 이 문서는 "중복이 가능하다"는 사실만 증명하고 그 해결책은 규정하지 않는다(KAFKA-OFFSET-C4 한계 참조)
- commitSync(Map)/commitAsync(Map, callback) 의 partition-단위 세밀 commit 이 rebalance 중 재시도 시 offset 파라미터를 어떻게 갱신해야 하는지의 상세 — 이 문서에서 해당 오버로드의 RebalanceInProgressException 설명은 확인했으나 이번 5개 인용에는 포함하지 않음(필요 시 추가 인용으로 보강)
- "어느 commit 방식이 ca-skeleton 에 더 적합한가"에 대한 규범적 권고 — 이 문서는 트레이드오프만 서술하고 prescriptive 하지 않음
내 프로젝트에 적용하려면 추가 확인이 필요한 것:
- ca-skeleton Kafka consumer adapter 가 실제로 enable.auto.commit=false + 명시적 commit 호출 지점(inbox 트랜잭션 커밋 이후)을 코드로 구현했는지 — 코드 레벨 검증 필요
- rebalance·backpressure·DLT 관련 결정에 쓸 별도 공식 근거(같은 Javadoc 페이지의 나머지 절 또는 ConsumerRebalanceListener/ConsumerConfig Javadoc) 추가 수집

메모

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

WebFetch 도구의 1차 결과(요약 모델 처리본)는 "Automatic Offset Committing"/"Manual Offset Control" 문단을 paraphrase 했고 self-grep 검증이 불가능해 이 문서 작성에 사용하지 않았다. curl 로 raw HTML 을 받아 stdlib re/html.unescape 로 직접 텍스트를 추출(블록 태그 경계에서만 줄바꿈 삽입)한 뒤, 그 텍스트에서만 인용을 뽑았다 — raw/official-docs/kafka-producer-javadoc-acks-idempotence.md 작성 시 확립된 동일 절차.
원문 문단이 Javadoc 소스 주석의 원래 줄바꿈을 그대로 보존하고 있어(브라우저 렌더링과 달리 raw text 추출본은 문장 중간에 개행이 남음), 인용 2/4/5 는 물리적으로 2줄 이상에 걸쳐 있다. Self-Grep 은 grep -Pzo(null-delimited, 개행 포함 패턴)로 수행했다 — 아래 Self-Grep Verification 참조.
다음 작업 후보: 같은 KafkaConsumer Javadoc 페이지의 rebalance(ConsumerRebalanceListener)/backpressure(pause/resume) 절을 별도 인용 세트로 추가하거나 새 raw 문서로 분리해, branch 범위의 "rebalance·backpressure·DLT" 결정 근거를 보강해야 한다.

15 KiB Raw Permalink Blame History