---
title: official-doc / Apache Kafka Producer Configs — delivery.timeout.ms, retries, acks, enable.idempotence
source_type: official-doc
url: https://kafka.apache.org/documentation/#producerconfigs
archive_url:
related_branches: [feature-kafka-producer-runtime-contract]
related_projects: [ca-skeleton]
tags: [official-doc, ca-skeleton, messaging, kafka, idempotency]
created: 2026-07-28
---

# Apache Kafka Producer Configs — delivery.timeout.ms, retries, acks, enable.idempotence

> Layer: `raw/` — 외부 자료(공식 문서)의 **원문 발췌·출처 기록**.
> 문서 버전: Apache Kafka 4.3 (`kafka.apache.org/43/configuration/producer-configs/`, `last-modified: 2026-07-11`) — 아래 "URL Fetch 경위" 참조.

## source_type

`official-doc` — Apache Software Foundation 이 직접 호스팅하는 Apache Kafka 프로젝트 공식 configuration reference.

## URL Fetch 경위 (원 요청 URL은 client-side JS redirect 셸)

- 요청된 URL: `https://kafka.apache.org/documentation/#producerconfigs`
- 시도 1 (WebFetch): nav/release-dropdown/footer만 반환. "Redirecting..." 표시. producer config 본문 없음.
- 시도 2 (WebFetch, `documentation.html#producerconfigs`): 동일 실패.
- **원인 규명**: `curl` 로 원본 HTML 을 직접 받아보니 `<title>Documentation Redirect Legacy | Apache Kafka</title>` 셸이며, 내부 `<script>` 에 해시 앵커 → 실제 경로 매핑 테이블이 있다: `"#producerconfigs":"configuration/producer-configs/"`, 그리고 현재 버전 변수 `t="43"`. 즉 브라우저가 `window.location.replace("/43/configuration/producer-configs/")` 로 client-side redirect 하는 구조이며, 정적 WebFetch/curl 은 이 JS를 실행하지 못해 셸만 받는다.
- **판정**: fallback(Confluent 미러) 없이 **원 저작자(Apache Kafka) 사이트의 실제 목적지 페이지**를 직접 특정해 fetch 가능했다. 사용한 실제 URL: `https://kafka.apache.org/43/configuration/producer-configs/` (HTTP 200, 146,845 bytes). 이 페이지를 `curl` 로 받아 HTML 태그 제거 후 텍스트로 저장, 아래 모든 인용은 이 저장 텍스트에 대해 `grep -nF` 로 self-grep 검증했다.
- 저장 텍스트: `/tmp/claude-*/scratchpad/kafka-43-producer-configs.txt` (세션별 scratchpad, 1150 lines)

## Parent / 활용 branch

| Branch | 이 자료가 정당화하는 결정 |
|---|---|
| [[raw/branch-notes/feature-kafka-producer-runtime-contract]] | ca-skeleton 의 Kafka producer 가 재시도 예산을 `retries` 횟수가 아니라 bounded `delivery.timeout.ms` 로 표현하고, 압축·배치·요청 크기 상한을 계약값으로 고정한다 |

## 출처

- 원본 URL (요청됨, 앵커): https://kafka.apache.org/documentation/#producerconfigs
- 실제 인용 URL (client-side redirect 목적지, 버전 고정): https://kafka.apache.org/43/configuration/producer-configs/
- 아카이브 URL: (미제공)
- 저자 / 조직: Apache Software Foundation (Apache Kafka 프로젝트)
- 발행일: 명시 없음 (페이지 자체는 버전 문서, HTTP `last-modified: Sat, 11 Jul 2026 01:38:20 GMT`)
- 마지막 확인일: 2026-07-28

## 왜 저장했는지

`feature-kafka-producer-runtime-contract` 브랜치가 "재시도 예산을 `retries` 횟수가 아니라 bounded `delivery.timeout.ms` 로 표현"하는 결정과 "압축·배치·요청 크기 상한을 계약값으로 고정"하는 결정의 공식 기준값(기본값·제약 문장)을 확보하기 위해 저장. `acks`/`enable.idempotence`/`max.in.flight.requests.per.connection` 의 상호 제약도 idempotent producer 설정을 검증 계약 test 로 만들 때 그대로 근거가 된다.

## 핵심 인용

> [§delivery.timeout.ms] "An upper bound on the time to report success or failure after a call to send() returns." [...] "The value of this config should be greater than or equal to the sum of request.timeout.ms and linger.ms." (Default: `120000` — 2 minutes)

> [§retries] "Requests will be retried this many times until they succeed, fail with a non-transient error, or the delivery.timeout.ms expires." [...] "Users should generally prefer to leave this config unset and instead use delivery.timeout.ms to control retry behavior." (Default: `2147483647`)

> [§acks] "Note that enabling idempotence requires this config value to be 'all'." (Default: `all`)

> [§enable.idempotence] "Note that enabling idempotence requires max.in.flight.requests.per.connection to be less than or equal to 5 (with message ordering preserved for any allowable value), retries to be greater than 0, and acks must be 'all'." [...] "Idempotence is enabled by default if no conflicting configurations are set." (Default: `true`)

> [§max.in.flight.requests.per.connection] "Note that if this configuration is set to be greater than 1 and enable.idempotence is set to false, there is a risk of message reordering after a failed send due to retries (i.e., if retries are enabled); if retries are disabled or if enable.idempotence is set to true, ordering will be preserved." [...] "Additionally, enabling idempotence requires the value of this configuration to be less than or equal to 5, because broker only retains at most 5 batches for each producer." (Default: `5`)

> [§buffer.memory / §max.block.ms] "If records are sent faster than they can be delivered to the server the producer will block for max.block.ms after which it will fail with an exception." (buffer.memory Default: `33554432`, max.block.ms Default: `60000` — 1 minute)

> [§batch.size / §linger.ms] "This linger.ms setting defaults to 5, which means the producer will wait for 5ms or until the record batch is of batch.size (whichever happens first) before sending the record batch." (batch.size Default: `16384`, linger.ms Default: `5`)

> [§compression.type] "The default is none (i.e. no compression)." [...] "Compression is of full batches of data, so the efficacy of batching will also impact the compression ratio (more batching means better compression)."

> 참고 (self-grep 검증됨, 상기 인용 문맥 안): `max.request.size` Default: `1048576` — "The maximum size of a request in bytes." (§max.request.size)

## Claims Extracted

| Claim ID | Claim | Evidence quote | Strength | Applies to | Does not prove |
|---|---|---|---|---|---|
| KAFKA-PRODCFG-C1 | `delivery.timeout.ms` 는 `send()` 반환 후 성공/실패를 보고하기까지의 상한이며, 기본값은 120000(2분)이다. 이 값은 `request.timeout.ms` + `linger.ms` 의 합보다 크거나 같아야 한다는 제약이 있다 | "An upper bound on the time to report success or failure after a call to send() returns." ... "The value of this config should be greater than or equal to the sum of request.timeout.ms and linger.ms." | `official-vendor-doc` | `request.timeout.ms`·`linger.ms` 를 override 할 때 `delivery.timeout.ms` 를 재계산해야 한다는 설정 제약 일반 | ca-skeleton 워크로드에 120000ms 가 적절한 SLA 인지는 증명하지 않는다. 위반 시 어떤 예외가 던져지는지(타입)도 이 인용에는 없다 |
| KAFKA-PRODCFG-C2 | `retries` 는 사실상 무제한 기본값(2147483647)이며, 재시도 루프는 명시적 횟수가 아니라 `delivery.timeout.ms` 만료로 종료된다. 공식 문서는 `retries` 를 직접 조정하지 말고 `delivery.timeout.ms` 로 재시도 예산을 통제하라고 권고한다 | "Requests will be retried this many times until they succeed, fail with a non-transient error, or the delivery.timeout.ms expires." ... "Users should generally prefer to leave this config unset and instead use delivery.timeout.ms to control retry behavior." | `official-vendor-doc` | producer 재시도 예산을 카운트 기반이 아니라 시간 기반(`delivery.timeout.ms`)으로 설계하는 근거 | 단일 재시도 attempt 간 backoff 간격(`retry.backoff.ms`)이나, `delivery.timeout.ms` 만료 전 실제 몇 회 재시도가 일어나는지는 증명하지 않는다 |
| KAFKA-PRODCFG-C3 | `enable.idempotence` 가 활성화되려면 `max.in.flight.requests.per.connection` ≤ 5, `retries` > 0, `acks` = `'all'` 이어야 하고, 상충 설정이 없으면 idempotence 는 **기본값으로 활성화**된다(`enable.idempotence` Default: `true`, `acks` Default: `all`) | "Note that enabling idempotence requires max.in.flight.requests.per.connection to be less than or equal to 5 (with message ordering preserved for any allowable value), retries to be greater than 0, and acks must be 'all'." ... "Idempotence is enabled by default if no conflicting configurations are set." | `official-vendor-doc` | ca-skeleton 이 별도 override 없이 producer 기본 설정만 써도 idempotent producer 계약이 성립한다는 근거(세 조건의 기본값이 이미 요건을 만족: acks=all, retries=2147483647>0, max.in.flight=5) | acks=1 등으로 명시적으로 override 하면서 `enable.idempotence` 를 명시하지 않을 경우 idempotence 가 **조용히 비활성화**된다는 것 외의 상세 오류 처리(예외 메시지 등)는 증명하지 않는다 |
| KAFKA-PRODCFG-C4 | `max.in.flight.requests.per.connection` 기본값은 5이며, idempotence 활성 시 이 값은 5 이하로 제한된다(broker가 producer당 최대 5개 배치만 유지하기 때문). `enable.idempotence=false` 이면서 이 값이 1 초과이고 retries 가 활성화된 경우 메시지 순서가 바뀔 위험이 있고, retries 비활성 또는 idempotence 활성 시에는 순서가 보존된다 | "Note that if this configuration is set to be greater than 1 and enable.idempotence is set to false, there is a risk of message reordering after a failed send due to retries (i.e., if retries are enabled); if retries are disabled or if enable.idempotence is set to true, ordering will be preserved." ... "Additionally, enabling idempotence requires the value of this configuration to be less than or equal to 5, because broker only retains at most 5 batches for each producer." | `official-vendor-doc` | idempotent producer 하에서 in-flight 요청 수를 5(기본값)로 두어도 순서 보장이 유지된다는 근거 — branch 범위의 "key/partition 순서 보장 경계" 결정에 직접 적용 | 5보다 큰 값을 idempotence 활성 상태에서 설정했을 때 정확히 어떤 예외/오류가 발생하는지는 "previous batches may be removed on broker side" 이상으로 구체화하지 않는다 |
| KAFKA-PRODCFG-C5 | `buffer.memory`(기본값 33554432 byte)가 소진되면 producer 는 `max.block.ms`(기본값 60000ms, 1분) 동안 블로킹한 뒤 예외로 실패한다 — 즉 producer 의 블로킹은 무한이 아니라 두 설정값으로 상한이 걸린 계약이다 | "If records are sent faster than they can be delivered to the server the producer will block for max.block.ms after which it will fail with an exception." | `official-vendor-doc` | `buffer.memory` + `max.block.ms` 조합을 "bounded backpressure" 계약값으로 고정하는 근거 | 실패 시 던져지는 예외의 정확한 타입(`org.apache.kafka.common.errors.TimeoutException` 등)은 이 인용문 자체에는 명시되지 않는다 |
| KAFKA-PRODCFG-C6 | `batch.size`(기본값 16384 byte)는 파티션당 배치 크기의 상한이고, `linger.ms`(기본값 5ms, Kafka 4.0에서 0→5로 기본값 변경)는 그 상한에 도달하지 않았을 때 대기하는 시간 상한이다 — 배치 크기 도달 또는 linger 만료 중 먼저 오는 조건에 전송된다 | "This linger.ms setting defaults to 5, which means the producer will wait for 5ms or until the record batch is of batch.size (whichever happens first) before sending the record batch." | `official-vendor-doc` | `batch.size` + `linger.ms` 를 배치·지연 상한 계약값으로 고정하는 근거 | ca-skeleton 실제 topic/partition 개수·처리량에서 이 기본값 조합이 처리율/지연 목표를 만족하는지는 증명하지 않는다(벤치마크 필요) |
| KAFKA-PRODCFG-C7 | `compression.type` 기본값은 `none`(무압축)이며, 압축은 배치 단위로 이뤄지므로 배치 효율이 압축률에도 영향을 준다 | "The default is none (i.e. no compression)." ... "Compression is of full batches of data, so the efficacy of batching will also impact the compression ratio (more batching means better compression)." | `official-vendor-doc` | 압축을 계약값으로 고정할 때 `batch.size`/`linger.ms` 와 함께 고려해야 한다는 근거(배치가 작으면 압축 이득도 작음) | 어떤 `compression.type`(gzip/snappy/lz4/zstd) 이 ca-skeleton 워크로드에 최적인지는 증명하지 않는다 — 그 비교는 이 문서 범위 밖 |

### Strength 참고

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

## Usage Boundaries

- 이 자료가 직접 증명하는 것:
  - `KAFKA-PRODCFG-C1`: `delivery.timeout.ms` 정의·기본값·제약(≥ request.timeout.ms + linger.ms)
  - `KAFKA-PRODCFG-C2`: `retries` 기본값(사실상 무제한) + `delivery.timeout.ms` 가 재시도 예산을 지배한다는 권고
  - `KAFKA-PRODCFG-C3`: idempotence 활성 요건(max.in.flight≤5, retries>0, acks=all) + 상충 없으면 기본 활성화
  - `KAFKA-PRODCFG-C4`: `max.in.flight.requests.per.connection` 기본값(5)과 idempotence 하 상한(5)·순서 보존 조건
  - `KAFKA-PRODCFG-C5`: `buffer.memory`/`max.block.ms` 조합이 bounded blocking 계약이라는 것
  - `KAFKA-PRODCFG-C6`: `batch.size`/`linger.ms` 조합이 배치 상한·지연 상한 계약이라는 것 (Kafka 4.0 에서 linger.ms 기본값 0→5 변경 포함)
  - `KAFKA-PRODCFG-C7`: `compression.type` 기본값(none)과 압축-배치 효율 관계
- 이 자료가 증명하지 **않는** 것:
  - ca-skeleton 실제 워크로드에서 이 기본값들이 SLA(지연/처리율)를 만족한다는 것 — 벤치마크·측정 필요
  - idempotent producer 의 중복 제거가 "파티션 단위"라는 정확한 스코프 문구 — 본 문서(`enable.idempotence`, `max.in.flight.requests.per.connection`, `retries` 항목)는 "a single partition"(§retries 문맥, ordering 논의)이라는 표현은 쓰지만, idempotent 중복 제거 메커니즘 자체를 "per-partition" 이라고 명시하지 않는다. `[[raw/official-docs/kafka-message-delivery-semantics-design.md]]` 가 이미 지적한 동일 gap이 이 문서로도 메워지지 않는다 — 필요 시 Kafka Javadoc(`KafkaProducer`) 별도 인용 필요
  - `delivery.timeout.ms` 초과 시 던져지는 예외의 정확한 클래스명
  - 여러 `compression.type` 값 간 성능 비교
- 내 프로젝트에 적용하려면 추가 확인이 필요한 것:
  - ca-skeleton 이 실제로 `acks`/`enable.idempotence`/`max.in.flight.requests.per.connection` 을 기본값 그대로 두는지, 아니면 override 하는지 — 별도 구현 증거(코드/설정) 필요
  - `delivery.timeout.ms`/`request.timeout.ms`/`linger.ms` 3개 값의 실제 계약값(ca-skeleton 이 채택할 숫자) — 이 문서는 기본값과 제약식만 제공, 구체적 조정값은 branch-note `## 구현 가이드` 에서 별도 결정 필요

## 메모

- 원 요청 URL(`kafka.apache.org/documentation/#producerconfigs`)은 client-side JS redirect 셸이라 WebFetch 로는 본문에 도달 불가했다. `curl` 로 셸 HTML 을 받아 내부 `<script>` 의 해시→경로 매핑 테이블(`t="43"`, `"#producerconfigs":"configuration/producer-configs/"`)을 읽어 실제 목적지(`/43/configuration/producer-configs/`)를 특정했다. 동일 branch 의 `[[raw/official-docs/kafka-message-delivery-semantics-design.md]]` 는 같은 문제(`#semantics` 앵커)를 만나 Confluent fallback 을 썼는데, 본 문서는 redirect 매핑을 직접 풀어 **Apache 원문**에 도달했다 — 더 강한 출처.
- HTML → 텍스트 변환은 직접 작성한 스크립트(태그 제거, `<td>`/`<th>` 를 ` | ` 로 표시)로 했다. Self-Grep 은 원본 HTML 문자열이 그대로 남아있는 문장 단위 인용에 대해서만 수행했고, 표 서식 기호(` | `) 자체는 인용에 포함하지 않았다.
- `retries` 필드의 "Enabling idempotence requires this config value to be greater than 0." 문장(§retries, self-grep 가능)은 KAFKA-PRODCFG-C3 에서 이미 `enable.idempotence` 항목 인용으로 커버되므로 중복 인용하지 않았다.

## 관련

- 같은 branch 의 다른 official-doc: [[raw/official-docs/kafka-message-delivery-semantics-design.md]] — at-least-once/exactly-once 정의, idempotent/transactional producer semantics (같은 branch, 인접 관심사, "파티션 단위" 표현 gap 공유)
- 같은 branch 의 다른 official-doc: [[raw/official-docs/spring-kafka-sending-messages-kafkatemplate.md]] — `KafkaTemplate.send()` 반환 타입/동기 대기 메커니즘