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

Apache Kafka Consumer Configs — max.poll.interval.ms, max.poll.records, auto-commit, session/heartbeat timeouts, partition.assignment.strategy

Layer: raw/ — 외부 자료(공식 문서)의 원문 발췌·출처 기록. 문서 버전: Apache Kafka 4.1 (kafka.apache.org/41/generated/consumer_config.html, HTTP last-modified: Fri, 12 Dec 2025 04:07:23 GMT).

source_type

official-doc — Apache Software Foundation 이 직접 호스팅하는 Apache Kafka 프로젝트 공식 consumer configuration reference (Gradle 빌드가 매 릴리스마다 자동 생성하는 ConfigDef 기반 페이지).

URL Fetch 경위

요청된 URL 그대로 성공: https://kafka.apache.org/41/generated/consumer_config.html — curl 직접 요청 1회차에 HTTP 200, 87,328 bytes 수신. 이 URL 은 (기존 raw/official-docs/kafka-producer-configs-delivery-timeout.md 와 raw/official-docs/kafka-message-delivery-semantics-design.md 가 겪은) kafka.apache.org/documentation/#... client-side JS redirect 셸이 아니라, 이미 버전 고정된 generated 정적 페이지라 redirect 문제가 없었다.
저장 원본: curl 로 받은 raw HTML 전체를 세션 scratchpad 에 저장(kafka-consumer-config-raw.html, 87,328 bytes). 이후 HTML 태그를 제거한 평문(paragraph 단위 Description:/Type:/Default:/Valid Values:/Importance: 추출)을 별도 파일(kafka-consumer-config-fetch.txt)로 만들어 self-grep 대상으로 삼았다.
이중 검증: 아래 모든 인용은 (1) 평문 추출 파일에 대한 grep -nF, (2) 원본 raw HTML 파일에 대한 grep -nF 양쪽 모두 통과를 재확인했다(HTML 태그가 인용 문장 내부 단어를 끊지 않는 문장만 인용 대상으로 선정).

Parent / 활용 branch

Branch	이 자료가 정당화하는 결정
raw/branch-notes/feature-kafka-consumer-inbox-contract	ca-skeleton consumer 가 장시간 처리와 rebalance 안정성을 위해 조정하는 설정 노브(`max.poll.interval.ms`, `max.poll.records`, `enable.auto.commit`/`auto.commit.interval.ms`, `session.timeout.ms`/`heartbeat.interval.ms`, `partition.assignment.strategy`)의 공식 정의와 기본값 기준선

출처

원본 URL: https://kafka.apache.org/41/generated/consumer_config.html
아카이브 URL: (미제공)
저자 / 조직: Apache Software Foundation (Apache Kafka 프로젝트)
발행일: 명시 없음 (버전 고정 reference 페이지, HTTP last-modified: Fri, 12 Dec 2025 04:07:23 GMT)
마지막 확인일: 2026-07-28

왜 저장했는지

feature-kafka-consumer-inbox-contract 브랜치가 inbound leaf 의 rebalance·backpressure·auto-commit 계약을 설계할 때 임의 수치를 발명하지 않도록, 각 설정 노브의 공식 설명 전문과 기본값을 기준선으로 고정하기 위해 저장. 특히 max.poll.interval.ms 초과 시 그룹 이탈·rebalance 가 일어난다는 문장과 partition.assignment.strategy 기본값에 CooperativeStickyAssignor 가 이미 포함돼 있다는 사실이 본 branch 의 "bounded concurrency·pause/resume backpressure" 및 "rebalance 처리" 결정의 직접 근거가 된다.

핵심 인용

[§max.poll.interval.ms] "The maximum delay between invocations of poll() when using consumer group management." [...] "If poll() is not called before expiration of this timeout, then the consumer is considered failed and the group will rebalance in order to reassign the partitions to another member." (Default: 300000 — 5 minutes)

[§max.poll.records] "The maximum number of records returned in a single call to poll()." (Default: 500)

[§enable.auto.commit] "If true the consumer's offset will be periodically committed in the background." (Default: true)

[§auto.commit.interval.ms] "The frequency in milliseconds that the consumer offsets are auto-committed to Kafka if enable.auto.commit is set to true." (Default: 5000 — 5 seconds)

[§session.timeout.ms] "If no heartbeats are received by the broker before the expiration of this session timeout, then the broker will remove this client from the group and initiate a rebalance." (Default: 45000 — 45 seconds)

[§heartbeat.interval.ms] "In that case, the value must be set lower than session.timeout.ms, but typically should be set no higher than 1/3 of that value." (Default: 3000 — 3 seconds)

[§partition.assignment.strategy] "The default assignor is [RangeAssignor, CooperativeStickyAssignor], which will use the RangeAssignor by default," [...] "but allows upgrading to the CooperativeStickyAssignor with just a single rolling bounce that removes the RangeAssignor from the list." (Default: class org.apache.kafka.clients.consumer.RangeAssignor,class org.apache.kafka.clients.consumer.CooperativeStickyAssignor)

Claims Extracted

Claim ID	Claim	Evidence quote	Strength	Applies to	Does not prove
KAFKA-CONSCFG-C1	`max.poll.interval.ms` 는 consumer group management 사용 시 `poll()` 호출 간 최대 허용 지연이며, 기본값은 300000ms(5분)이다. 이 시간 내에 `poll()` 이 호출되지 않으면 consumer 는 실패한 것으로 간주되어 그룹이 rebalance 되어 파티션이 다른 member 에게 재할당된다	"The maximum delay between invocations of poll() when using consumer group management." ... "If poll() is not called before expiration of this timeout, then the consumer is considered failed and the group will rebalance in order to reassign the partitions to another member."	`official-vendor-doc`	장시간 처리(long-running handler)가 있는 consumer 가 `max.poll.interval.ms` 를 초과하면 강제 rebalance 를 유발한다는 근거 — bounded concurrency·pause/resume backpressure 설계의 기본값 기준선	ca-skeleton 워크로드의 실제 처리 시간이 300000ms 이내인지는 증명하지 않는다. `group.instance.id` 설정 시 즉시 재할당이 아니라 `session.timeout.ms`(또는 consumer 프로토콜의 `group.consumer.session.timeout.ms`) 만료 후 재할당된다는 예외 조건은 이 인용에는 없지만 원문에는 명시돼 있음(§메모 참고)
KAFKA-CONSCFG-C2	`max.poll.records` 는 단일 `poll()` 호출에서 반환되는 최대 레코드 수이며 기본값은 500이다	"The maximum number of records returned in a single call to poll()."	`official-vendor-doc`	consumer 가 한 번에 처리할 배치 크기 상한을 계약값으로 고정하는 근거	이 값이 fetch 자체의 크기(`fetch.max.bytes`/`max.partition.fetch.bytes`)에 영향을 준다는 뜻은 아님 — 원문은 "does not impact the underlying fetching behavior" 라고 명시(캐시된 레코드를 incremental 하게만 반환)
KAFKA-CONSCFG-C3	`enable.auto.commit` 이 `true`(기본값)이면 consumer offset 이 백그라운드에서 주기적으로 커밋된다	"If true the consumer's offset will be periodically committed in the background."	`official-vendor-doc`	manual acknowledgement 설계 시 기본값(`true`)을 명시적으로 `false` 로 override 해야 한다는 근거	커밋 주기의 정확한 타이밍(다음 `poll()` 호출 시점과의 관계 등)은 이 인용문 자체에는 없음 — `auto.commit.interval.ms`(C4)가 주기 값만 정의
KAFKA-CONSCFG-C4	`auto.commit.interval.ms` 는 `enable.auto.commit=true` 일 때 offset 이 자동 커밋되는 주기(밀리초)이며 기본값은 5000ms(5초)이다	"The frequency in milliseconds that the consumer offsets are auto-committed to Kafka if enable.auto.commit is set to true."	`official-vendor-doc`	auto-commit 모드를 쓸 경우의 커밋 주기 기본값 기준선	`enable.auto.commit=false`(manual ack 설계)에서는 이 설정 자체가 무의미해진다는 것 — 원문은 그 상호작용을 명시하지 않음
KAFKA-CONSCFG-C5	`session.timeout.ms` 는 group management 사용 시 client 장애를 탐지하는 타임아웃이며 기본값은 45000ms(45초)이다. 이 시간 내에 broker 가 heartbeat 을 받지 못하면 broker 가 해당 client 를 그룹에서 제거하고 rebalance 를 시작한다	"If no heartbeats are received by the broker before the expiration of this session timeout, then the broker will remove this client from the group and initiate a rebalance."	`official-vendor-doc`	broker 측 장애 탐지 타임아웃의 기본값 기준선 — `max.poll.interval.ms`(C1, poll 미호출 탐지)와는 별개 메커니즘(heartbeat thread 기반)이라는 근거	값 범위가 broker 설정(`group.min.session.timeout.ms`/`group.max.session.timeout.ms`)에 종속된다는 제약과, `group.protocol=consumer` 사용 시 이 client 설정 자체가 무시되고 broker 설정(`group.consumer.session.timeout.ms`)이 대신 적용된다는 것은 인용문에는 없지만 원문 본문에 명시(§메모 참고)
KAFKA-CONSCFG-C6	`heartbeat.interval.ms` 는 group management 사용 시 heartbeat 간격이며 기본값은 3000ms(3초)이다. `group.protocol=classic` 인 경우 이 값은 `session.timeout.ms` 보다 반드시 작아야 하고, 통상적으로 `session.timeout.ms` 의 1/3 이하로 설정하는 것이 권장된다	"In that case, the value must be set lower than session.timeout.ms, but typically should be set no higher than 1/3 of that value."	`official-vendor-doc`	classic rebalance protocol 하에서 `heartbeat.interval.ms` ≤ `session.timeout.ms`/3 비율 기준선(기본값 3000ms vs 45000ms 는 정확히 1/15 비율로 권장 상한보다 여유 있음)	`group.protocol=consumer` 로 설정 시 이 client 설정 자체가 지원되지 않고 broker 설정(`group.consumer.heartbeat.interval.ms`)이 heartbeat 간격을 통제한다는 것은 이 인용문에는 없지만 원문에 명시(§메모 참고)
KAFKA-CONSCFG-C7	`partition.assignment.strategy` 기본값은 `[RangeAssignor, CooperativeStickyAssignor]` 이며, 이 기본 목록은 RangeAssignor 를 우선 사용하되 목록에서 RangeAssignor 를 제거하는 단 한 번의 rolling bounce 만으로 CooperativeStickyAssignor 로 업그레이드할 수 있게 해준다	"The default assignor is [RangeAssignor, CooperativeStickyAssignor], which will use the RangeAssignor by default," ... "but allows upgrading to the CooperativeStickyAssignor with just a single rolling bounce that removes the RangeAssignor from the list."	`official-vendor-doc`	Kafka 4.1 기본값 자체가 이미 `CooperativeStickyAssignor` 로의 무중단 업그레이드 경로를 지원한다는 근거 — cooperative rebalancing 채택 여부를 branch 결정으로 명시할 때의 기준선	기본값이 RangeAssignor 를 "우선 사용"한다는 것이지, cooperative(비-eager) rebalancing 이 기본으로 활성화되어 있다는 뜻은 아님 — RangeAssignor 는 eager assignor 이며, 순수 cooperative 동작을 얻으려면 목록에서 RangeAssignor 를 제거하는 별도 rolling bounce 가 필요하다는 것이 원문의 요지

Strength 참고

모두 official-vendor-doc — Apache Kafka 프로젝트(Apache Software Foundation) 가 직접 게시한 configuration reference. official-standard(RFC/표준)는 아니다.

Usage Boundaries

이 자료가 직접 증명하는 것:
- KAFKA-CONSCFG-C1: max.poll.interval.ms 정의·기본값(300000ms)과 초과 시 rebalance 유발
- KAFKA-CONSCFG-C2: max.poll.records 정의·기본값(500)과 fetch 동작과의 독립성
- KAFKA-CONSCFG-C3: enable.auto.commit 정의·기본값(true)
- KAFKA-CONSCFG-C4: auto.commit.interval.ms 정의·기본값(5000ms)
- KAFKA-CONSCFG-C5: session.timeout.ms 정의·기본값(45000ms)과 heartbeat 미수신 시 broker 주도 제거·rebalance
- KAFKA-CONSCFG-C6: heartbeat.interval.ms 정의·기본값(3000ms)과 session.timeout.ms 대비 권장 비율(≤1/3)
- KAFKA-CONSCFG-C7: partition.assignment.strategy 기본값([RangeAssignor, CooperativeStickyAssignor])과 CooperativeStickyAssignor 로의 단일 rolling-bounce 업그레이드 경로
이 자료가 증명하지 않는 것:
- ca-skeleton 실제 워크로드에서 이 기본값들(300000ms poll interval, 500 records/poll, 45000ms session timeout 등)이 목표 처리율·지연·rebalance 빈도를 만족한다는 것 — 벤치마크·측정 필요
- group.protocol=consumer(새 KIP-848 consumer group protocol) 사용 시 client-side session.timeout.ms/heartbeat.interval.ms 설정이 무시되고 broker 설정으로 대체된다는 세부 동작의 완전한 구현 검증 — 원문은 이 상호작용을 명시하지만, ca-skeleton 이 group.protocol=classic(기본값)을 유지하는지 여부는 별도 branch 결정 필요
- manual acknowledgement 구현 시 정확한 커밋 API 호출 시점(예: Spring Kafka AckMode 매핑) — 이 문서는 Kafka client 설정값만 제공, Spring Kafka wrapper 동작은 별도 자료 필요
- poison message·역직렬화 실패 분류, retry topic·DLT 설계 — 이 문서 범위 밖(별도 branch 결정 + 별도 자료)
내 프로젝트에 적용하려면 추가 확인이 필요한 것:
- ca-skeleton 이 enable.auto.commit=false(manual ack)로 override 할 것이 확실하므로, auto.commit.interval.ms(C4) 기본값은 실제로는 무관해질 수 있음 — branch ## 구현 가이드 에서 명시적으로 정리 필요
- max.poll.interval.ms/max.poll.records/bounded concurrency 조합의 실제 계약값(ca-skeleton 이 채택할 숫자) — 이 문서는 기본값만 제공, 구체적 조정값은 branch-note에서 별도 결정 필요
- partition.assignment.strategy 를 기본값 그대로 둘지, 목록에서 RangeAssignor 를 제거해 순수 cooperative 로 고정할지는 별도 branch 결정 필요(이 문서는 두 옵션의 존재와 업그레이드 경로만 증명)

메모

원문에서 self-grep 은 통과했지만 위 Claims Extracted 표의 "Does not prove" 열에 요약 인용 없이 언급한 문장들(예: group.instance.id static member 예외, group.protocol=consumer 대체 동작)은 각각 raw HTML §max.poll.interval.ms, §session.timeout.ms, §heartbeat.interval.ms 문단 안에 그대로 존재함(kafka-consumer-config-raw.html line 284, 84, 63) — 별도 Claim 으로 분리하지 않고 인접 Claim 의 "Does not prove"에 원문 존재 사실만 남겼다. 필요 시 별도 Claim 으로 승격 가능.
partition.assignment.strategy 의 RangeAssignor/RoundRobinAssignor/StickyAssignor/CooperativeStickyAssignor 4종 개별 설명 문장도 raw HTML 에 존재(self-grep 가능)하나, 본 문서에서는 기본값 조합(C7)만 인용 — 개별 assignor 알고리즘 비교가 필요해지면 별도 인용 추가.
저장 원본: 세션 scratchpad kafka-consumer-config-raw.html(원본 HTML, 87,328 bytes) + kafka-consumer-config-fetch.txt(평문 추출본, self-grep 대상).

16 KiB Raw Permalink Blame History

Apache Kafka Consumer Configs — max.poll.interval.ms, max.poll.records, auto-commit, session/heartbeat timeouts, partition.assignment.strategy

source_type

URL Fetch 경위

Parent / 활용 branch

출처

왜 저장했는지

핵심 인용

Claims Extracted

Strength 참고

Usage Boundaries

메모

관련

16 KiB

Raw Permalink Blame History