프로듀서 설정

프로듀서 설정 (Producer Configs)

프로듀서(데이터를 Kafka로 보내는 클라이언트)의 설정 항목들을 정리한 문서예요. 직렬화, 배치(batching), 재시도, 압축, 멱등성(idempotence), 트랜잭션 같은 프로듀서 동작을 결정하는 값들이 여기 있어요.

출처: 문서

본문

아래는 프로듀서 설정 항목들이에요.

• bootstrap.servers — Kafka 클러스터에 초기 연결을 설정하는 데 쓰는 host/port 쌍 목록. 클라이언트가 이 목록으로 부트스트랩해 전체 Kafka 브로커 집합을 발견해요. 목록의 서버 순서는 상관없지만, 어떤 서버가 다운되더라도 복원력을 위해 두 개 이상의 서버를 포함하는 걸 권장해요. 이 목록에 브로커 전체가 포함될 필요는 없어요 — Kafka 클라이언트가 클러스터 연결을 효율적으로 자동 관리·갱신하거든요. 형식은 host1:port1,host2:port2,...이어야 해요.
  • 유형: list / 중요도: high
• key.serializer — org.apache.kafka.common.serialization.Serializer 인터페이스를 구현하는 키용 직렬화기 클래스.
  • 유형: class / 중요도: high
• value.serializer — org.apache.kafka.common.serialization.Serializer 인터페이스를 구현하는 값용 직렬화기 클래스.
  • 유형: class / 중요도: high
• buffer.memory — 프로듀서가 서버로 보내기 전에 대기 중인 레코드를 버퍼링하는 데 사용할 총 메모리 바이트. 레코드가 서버로 전달되는 속도보다 빠르게 전송되면 프로듀서는 max.block.ms 동안 블록된 뒤 예외와 함께 실패해요. 이 설정은 대략 프로듀서가 사용할 총 메모리와 맞아야 하지만, 프로듀서가 사용하는 모든 메모리가 버퍼링에 쓰이지는 않으므로 엄격한 상한은 아니에요. 압축(활성화된 경우)과 in-flight 요청 유지에도 추가 메모리가 사용돼요.
  • 유형: long / 기본값: 33554432 / 유효 값: [0,...] / 중요도: high
• compression.type — 프로듀서가 만드는 모든 데이터의 압축 유형. 기본값은 none(압축 없음)이에요. 유효 값은 none, gzip, snappy, lz4, zstd예요. 압축은 데이터의 전체 배치에 적용되므로 배칭의 효율도 압축률에 영향을 줘요(배칭이 많을수록 압축이 좋아짐).
  • 유형: string / 기본값: none / 유효 값: [none, gzip, snappy, lz4, zstd] / 중요도: high
• retries — 일시적(transient) 오류로 실패한 요청을 재시도하는 횟수. 0보다 큰 값을 설정하면 잠재적으로 일시적인 오류로 전송이 실패한 레코드를 클라이언트가 재전송해요. 요청은 성공하거나, 일시적이지 않은 오류로 실패하거나, delivery.timeout.ms가 만료될 때까지 이 횟수만큼 재시도돼요. 이 자동 재시도는 오류를 받으면 같은 레코드를 그냥 재전송한다는 점을 참고해요. 0으로 설정하면 이 자동 재시도 동작이 비활성화돼 일시적 오류가 애플리케이션으로 전파되어 처리돼요. 사용자는 일반적으로 이 구성을 설정하지 않고 대신 delivery.timeout.ms로 재시도 동작을 제어하는 걸 선호해요. 멱등성(idempotence)을 활성화하려면 이 구성 값이 0보다 커야 해요. 충돌하는 구성이 설정됐는데 멱등성이 명시적으로 활성화되지 않으면 멱등성은 비활성화돼요. enable.idempotence를 false로 설정하고 max.in.flight.requests.per.connection을 1보다 크게 설정하면서 재시도를 허용하면 레코드 순서가 바뀔 수 있어요 — 두 배치를 단일 파티션으로 보낼 때 첫 번째가 실패 후 재시도되는데 두 번째가 성공하면 두 번째 배치의 레코드가 먼저 나타날 수 있기 때문이에요.
  • 유형: int / 기본값: 2147483647 / 유효 값: [0,...,2147483647] / 중요도: high
• ssl.key.password — 키 저장소 파일의 개인 키 비밀번호 또는 ssl.keystore.key에 지정된 PEM 키의 비밀번호. 유형: password / 기본값: null / 중요도: high
• ssl.keystore.certificate.chain — ssl.keystore.type이 지정하는 형식의 인증서 체인. 기본 SSL 엔진 팩토리는 X.509 인증서 목록이 있는 PEM 형식만 지원해요. 유형: password / 기본값: null / 중요도: high
• ssl.keystore.key — ssl.keystore.type이 지정하는 형식의 개인 키. 기본 SSL 엔진 팩토리는 PKCS#8 키가 있는 PEM 형식만 지원해요. 키가 암호화된 경우 ssl.key.password로 키 비밀번호를 지정해야 해요. 유형: password / 기본값: null / 중요도: high
• ssl.keystore.location — 키 저장소 파일의 위치. 클라이언트에선 선택 사항이며 양방향 인증에 쓸 수 있어요. 유형: string / 기본값: null / 중요도: high
• ssl.keystore.password — 키 저장소 파일의 저장소 비밀번호. 클라이언트에선 선택 사항이며 ssl.keystore.location이 구성된 경우에만 필요해요. PEM 형식은 지원하지 않아요. 유형: password / 기본값: null / 중요도: high
• ssl.truststore.certificates — ssl.truststore.type이 지정하는 형식의 신뢰 인증서. 기본 SSL 엔진 팩토리는 X.509 인증서가 있는 PEM 형식만 지원해요. 유형: password / 기본값: null / 중요도: high
• ssl.truststore.location — 트러스트 저장소 파일의 위치. 유형: string / 기본값: null / 중요도: high
• ssl.truststore.password — 트러스트 저장소 파일의 비밀번호. 설정하지 않아도 구성된 트러스트 저장소 파일은 사용되지만 무결성 검사는 비활성화돼요. PEM 형식은 지원하지 않아요. 유형: password / 기본값: null / 중요도: high
• batch.size — 여러 레코드가 같은 파티션으로 전송될 때 프로듀서가 요청 수를 줄이려고 레코드를 배치하려 시도해요. 클라이언트·서버 성능에 모두 도움이 돼요. 이 구성은 기본 배치 크기(바이트)를 제어해요. 이보다 큰 레코드는 배치하려 시도하지 않아요. 브로커로 보내는 요청은 보낼 데이터가 있는 파티션마다 하나씩, 여러 배치를 포함해요. 작은 배치 크기는 배칭을 덜 흔하게 만들어 처리량을 줄일 수 있고(배치 크기 0은 배칭을 완전히 비활성화), 매우 큰 배치 크기는 추가 레코드를 예상해 지정된 배치 크기의 버퍼를 항상 할당하므로 메모리를 좀 더 낭비할 수 있어요. 참고: 이 설정은 보낼 배치 크기의 상한을 줘요. 파티션에 이만큼보다 적은 바이트가 쌓이면 linger.ms 시간 동안 '머무르며' 더 많은 레코드를 기다려요. 이 linger.ms 기본값은 5로, 프로듀서가 레코드 배치를 보내기 전에 5ms 또는 레코드 배치가 batch.size가 될 때까지(둘 중 먼저) 기다린다는 뜻이에요. 브로커 백프레셔가 이 설정보다 더 긴 실질 linger 시간을 만들 수 있다는 점도 참고해요. Apache Kafka 4.0에서 기본값이 0에서 5로 바뀌었는데, 더 큰 배치의 효율 이득이 linger 증가에도 불구하고 보통 유사하거나 더 낮은 프로듀서 지연을 만들기 때문이에요.
  • 유형: int / 기본값: 16384 / 유효 값: [0,...] / 중요도: medium
• client.dns.lookup — 클라이언트가 DNS 조회를 사용하는 방식을 제어해요. use_all_dns_ips로 설정하면 반환된 각 IP 주소에 순서대로 연결해서 성공할 때까지 시도해요. 연결이 끊기면 다음 IP를 사용해요. 모든 IP를 한 번씩 사용한 뒤에는 호스트 이름에서 IP를 다시 해석해요. resolve_canonical_bootstrap_servers_only로 설정하면 각 부트스트랩 주소를 정규 이름 목록으로 해석해요. 부트스트랩 단계 이후에는 use_all_dns_ips와 동일하게 동작해요.
  • 유형: string / 기본값: use_all_dns_ips / 유효 값: [use_all_dns_ips, resolve_canonical_bootstrap_servers_only] / 중요도: medium
• client.id — 요청을 만들 때 서버에 전달하는 ID 문자열. 서버 측 요청 로깅에 논리적 애플리케이션 이름을 포함해 ip/port를 넘어 요청의 출처를 추적하기 위한 목적이에요. 유형: string / 기본값: "" / 중요도: medium
• compression.gzip.level — compression.type이 gzip으로 설정된 경우 사용할 압축 수준. 유형: int / 기본값: -1 / 유효 값: [1,...,9] 또는 -1 / 중요도: medium
• compression.lz4.level — compression.type이 lz4로 설정된 경우 사용할 압축 수준. 유형: int / 기본값: 9 / 유효 값: [1,...,17] / 중요도: medium
• compression.zstd.level — compression.type이 zstd로 설정된 경우 사용할 압축 수준. 유형: int / 기본값: 3 / 유효 값: [-131072,...,22] / 중요도: medium
• connections.max.idle.ms — 이 구성이 지정하는 밀리초 수가 지난 뒤 유휴 연결을 닫아요. 유형: long / 기본값: 540000 (9분) / 중요도: medium
• delivery.timeout.ms — send() 호출이 반환된 뒤 성공 또는 실패를 보고하는 시간의 상한. 이는 레코드가 전송 전에 지연되는 총 시간, 브로커로부터 승인을 기다리는 시간(예상될 때), 재시도 가능한 전송 실패에 허용되는 시간을 제한해요. 복구할 수 없는 오류를 만나거나, 재시도가 소진되거나, 레코드가 더 이른 전달 만료 기한에 도달한 배치에 추가되면 프로듀서는 이 구성보다 먼저 전송 실패를 보고할 수 있어요. 이 값은 request.timeout.ms와 linger.ms의 합보다 크거나 같아야 해요.
  • 유형: int / 기본값: 120000 (2분) / 유효 값: [0,...] / 중요도: medium
• linger.ms — 프로듀서는 요청 전송 사이에 도착한 모든 레코드를 단일 배치 요청으로 묶어요. 보통 부하가 걸려 레코드가 보내는 속도보다 빨리 도착할 때만 발생해요. 하지만 일부 상황에서는 중간 부하에서도 요청 수를 줄이고 싶을 수 있어요. 이 설정은 약간의 인위적 지연을 더해서 이를 달성해요 — 즉 레코드를 즉시 보내지 않고 주어진 지연만큼 기다려 다른 레코드가 함께 전송되게 해 배치로 묶는 거예요. TCP의 Nagle 알고리즘과 유사하다고 볼 수 있어요. 이 설정은 배칭 지연의 상한을 줘요: 파티션에 batch.size만큼의 레코드가 쌓이면 이 설정과 무관하게 즉시 전송되지만, 파티션에 이만큼보다 적은 바이트가 쌓이면 지정된 시간 동안 '머무르며' 더 많은 레코드를 기다려요. 기본값은 5(즉 5ms 지연)예요. 예를 들어 linger.ms=50으로 늘리면 보내는 요청 수는 줄지만 부하가 없을 때 보내는 레코드에 최대 50ms의 지연을 추가해요. Apache Kafka 4.0에서 기본값이 0에서 5로 바뀌었어요.
  • 유형: long / 기본값: 5 / 유효 값: [0,...] / 중요도: medium
• max.block.ms — KafkaProducer의 send(), partitionsFor(), initTransactions(), sendOffsetsToTransaction(), commitTransaction(), abortTransaction() 메서드가 얼마나 오래 블록될지 제어하는 구성. send()의 경우 이 타임아웃은 메타데이터 fetch와 버퍼 할당을 모두 기다리는 총 시간에 상한을 둬요(사용자 제공 직렬화기/파티셔너에서 블록되는 시간은 제외). partitionsFor()의 경우 이 타임아웃은 메타데이터가 없을 때 메타데이터를 기다리는 데 보내는 시간에 상한을 둬요. 트랜잭션 관련 메서드는 항상 블록되지만, 트랜잭션 코디네이터를 발견하지 못했거나 타임아웃 내 응답하지 않으면 타임아웃될 수 있어요.
  • 유형: long / 기본값: 60000 (1분) / 유효 값: [0,...] / 중요도: medium
• max.request.size — 요청의 최대 크기(바이트). 이 설정은 프로듀서가 단일 요청으로 보내는 레코드 배치 수를 제한해 매우 큰 요청을 피해요. 이는 실질적으로 최대 압축되지 않은 레코드 배치 크기의 상한이기도 해요. 참고로 서버는 (압축이 활성화된 경우 압축 후) 레코드 배치 크기에 대한 자체 상한을 가지며, 이 값과 다를 수 있어요.
  • 유형: int / 기본값: 1048576 / 유효 값: [0,...] / 중요도: medium
• partitioner.class — 레코드가 생산될 때 어느 파티션으로 보낼지 결정하는 설정. 사용 가능한 옵션은 다음과 같아요.
  • 설정하지 않으면 기본 파티셔닝 로직이 사용돼요. 이 전략은 파티션에 최소 batch.size 바이트가 생산될 때까지 레코드를 파티션으로 보내요. 키가 있으면 키의 해시로 파티션을 고르고, 파티션·키가 모두 없으면 파티션에 최소 batch.size 바이트가 생산될 때 바뀌는 sticky 파티션을 골라요. org.apache.kafka.clients.producer.RoundRobinPartitioner는 키 제공 여부와 무관하게 연속 레코드 각각을 다른 파티션으로 보내다가 파티션이 다 떨어지면 다시 처음부터 시작하는 전략이에요. 참고: 새 배치가 만들어질 때 불균등 분포를 일으키는 알려진 문제가 있어요. 자세한 내용은 KAFKA-9965를 참고해요.
  • org.apache.kafka.clients.producer.Partitioner 인터페이스를 구현하면 커스텀 파티셔너를 끼워 넣을 수 있어요.
  • 유형: class / 기본값: null / 중요도: medium
• partitioner.ignore.keys — true로 설정하면 프로듀서가 레코드 키를 사용해 파티션을 고르지 않아요. false면 키가 있을 때 키의 해시로 파티션을 골라요. 참고: 커스텀 파티셔너를 쓰면 이 설정은 효과가 없어요. 유형: boolean / 기본값: false / 중요도: medium
• receive.buffer.bytes — 데이터를 읽을 때 사용하는 TCP 수신 버퍼(SO_RCVBUF) 크기. -1이면 OS 기본값. 유형: int / 기본값: 32768 (32 kibibytes) / 유효 값: [-1,...] / 중요도: medium
• request.timeout.ms — 클라이언트가 요청의 응답을 기다리는 최대 시간. 타임아웃이 지나기 전에 응답을 받지 못하면 필요하면 재전송하고 재시도가 소진되면 실패 처리해요. 불필요한 프로듀서 재시도로 인한 메시지 중복 가능성을 줄이려면 replica.lag.time.max.ms(브로커 구성)보다 커야 해요. 유형: int / 기본값: 30000 (30초) / 유효 값: [0,...] / 중요도: medium
• sasl.client.callback.handler.class — AuthenticateCallbackHandler 인터페이스를 구현하는 SASL 클라이언트 콜백 핸들러 클래스의 완전한 이름. 유형: class / 기본값: null / 중요도: medium
• sasl.jaas.config — JAAS 구성 파일이 사용하는 형식의 SASL 연결용 JAAS 로그인 컨텍스트 파라미터. 값 형식은 loginModuleClass controlFlag (optionName=optionValue)*;. 브로커의 경우 리스너 접두사+소문자 SASL 메커니즘 이름으로 접두사가 붙어야 해요. 유형: password / 기본값: null / 중요도: medium
• sasl.kerberos.service.name — Kafka가 실행되는 Kerberos 주체 이름. 유형: string / 기본값: null / 중요도: medium
• sasl.login.callback.handler.class — AuthenticateCallbackHandler 인터페이스를 구현하는 SASL 로그인 콜백 핸들러 클래스의 완전한 이름. 유형: class / 기본값: null / 중요도: medium
• sasl.login.class — Login 인터페이스를 구현하는 클래스의 완전한 이름. 유형: class / 기본값: null / 중요도: medium
• sasl.mechanism — 클라이언트 연결에 사용하는 SASL 메커니즘. 기본은 GSSAPI. 유형: string / 기본값: GSSAPI / 중요도: medium
• sasl.oauthbearer.assertion.algorithm — 아이덴티티 제공자에게 보내는 어서션 서명에 사용할 알고리즘. JWT 어서션의 alg 헤더 값으로도 쓰여요. sasl.oauthbearer.assertion.file 값이 제공되면 무시돼요. 유형: string / 기본값: RS256 / 유효 값: (대소문자 무시) [ES256, RS256] / 중요도: medium
• sasl.oauthbearer.assertion.claim.aud — 로컬에서 만든 클라이언트 JWT 어서션에 포함될 aud(Audience) 클레임. sasl.oauthbearer.assertion.file 값이 제공되면 무시돼요. 유형: string / 기본값: null / 중요도: medium
• sasl.oauthbearer.assertion.claim.iss — 로컬에서 만든 클라이언트 JWT 어서션에 포함될 iss(Issuer) 클레임 값. sasl.oauthbearer.assertion.file 값이 제공되면 무시돼요. 유형: string / 기본값: null / 중요도: medium
• sasl.oauthbearer.assertion.claim.jti.include — JWT 어서션이 JWT용 고유 ID를 생성해 jti(JWT ID) 클레임에 포함할지 결정하는 플래그. sasl.oauthbearer.assertion.file 값이 제공되면 무시돼요. 유형: boolean / 기본값: false / 중요도: medium
• sasl.oauthbearer.assertion.claim.sub — 로컬에서 만든 클라이언트 JWT 어서션에 포함될 sub(Subject) 클레임 값. sasl.oauthbearer.assertion.file 값이 제공되면 무시돼요. 유형: string / 기본값: null / 중요도: medium
• sasl.oauthbearer.assertion.file — 미리 생성된 JWT 어서션이 들어 있는 파일. 내부 구현은 파일 내용을 캐시해 매번 로드하는 성능 손실을 피하고, 파일 변경을 감지해 다시 로드함으로써 Kafka 클라이언트 재시작 없이 "라이브" 어서션 교체가 가능해요. 직렬화된 3부분 JWT 형식(헤더·페이로드·서명)으로 어서션을 담아요. sasl.oauthbearer.assertion.file 값이 제공되면 다른 모든 sasl.oauthbearer.assertion.* 구성은 무시돼요. 유형: string / 기본값: null / 중요도: medium
  • 헤더 섹션: alg(Algorithm), typ(Type, 항상 리터럴 JWT) 같은 값이 담긴 base 64 인코딩 JWT 헤더
  • 페이로드 섹션: aud(Audience), iss(Issuer), sub(Subject) 같은 base 64 인코딩 JWT 클레임 집합
  • 서명 섹션: 개인 키로 서명된 헤더·페이로드 섹션의 연결
• sasl.oauthbearer.assertion.private.key.file — 아이덴티티 제공자에게 보내는 JWT 어서션을 서명하는 데 사용하는, 표준 PEM 형식의 개인 키가 들어 있는 파일. 캐싱을 통해 재시작 없이 "라이브" 개인 키 교체가 가능해요. sasl.oauthbearer.assertion.file 값이 제공되면 무시돼요. 유형: string / 기본값: null / 중요도: medium
• sasl.oauthbearer.assertion.private.key.passphrase — sasl.oauthbearer.assertion.private.key.file이 지정하는 개인 키 파일을 복호화하는 선택적 구문. 런타임에 파일이 이전과 다른 구문으로 교체되면 클라이언트가 키에 접근하지 못하므로, 항상 같은 구문을 쓰거나 보안을 위해 새 구문 구성으로 클라이언트를 재시작해요. sasl.oauthbearer.assertion.file 값이 제공되면 무시돼요. 유형: password / 기본값: null / 중요도: medium
• sasl.oauthbearer.assertion.template.file — JWT 어서션을 만들 때 사용할 JWT 헤더/페이로드 클레임을 담은 파일을 지정하는 선택적 구성. 모든 아이덴티티 제공자가 같은 클레임 집합을 요구하지 않으므로, 이 구성으로 JWT에 포함할 정적 헤더 값과 클레임을 제공할 수 있어요. sasl.oauthbearer.assertion.file 값이 제공되면 무시돼요. 유형: string / 기본값: null / 중요도: medium
• sasl.oauthbearer.client.credentials.client.id — 토큰을 요청하는 클라이언트를 식별하는 ID. 이전에는 sasl.jaas.config의 clientId 키로 저장됐었어요. 하위 호환성을 위해 clientId JAAS 옵션을 쓸 수 있지만 비권장이며 향후 제거될 예정이에요. 우선순위: 구성의 sasl.oauthbearer.client.credentials.client.id → JAAS의 clientId. 유형: string / 기본값: null / 중요도: medium
• sasl.oauthbearer.client.credentials.client.secret — 토큰을 요청하는 클라이언트의 시크릿. 이전에는 sasl.jaas.config의 clientSecret 키로 저장됐었어요. clientSecret JAAS 옵션은 비권장이며 향후 제거될 예정이에요. 우선순위: 구성 → JAAS. 유형: password / 기본값: null / 중요도: medium
• sasl.oauthbearer.jwks.endpoint.url — 제공자의 JWKS(JSON Web Key Set)를 가져올 수 있는 OAuth/OIDC 제공자 URL. HTTP(S) 기반이거나 파일 기반일 수 있어요. HTTP(S) 기반이면 브로커 시작 시 키를 가져와 캐시하고, 캐시에 없는 kid가 포함된 JWT 요청이 오면 필요 시 다시 조회해요. 브로커는 sasl.oauthbearer.jwks.endpoint.refresh.ms마다 URL을 폴링해 키를 갱신해요. 유형: string / 기본값: null / 중요도: medium
• sasl.oauthbearer.jwt.retriever.class — 아이덴티티 제공자에게 토큰을 요청하는 데 사용하는 JwtRetriever 구현 클래스의 완전한 이름. 기본값은 하위 호환을 유지하는 클래스이며 구성을 사용해 구체 구현을 결정해요. 제공되는 구현: ClientCredentialsJwtRetriever, DefaultJwtRetriever, FileJwtRetriever, JwtBearerJwtRetriever. 유형: class / 기본값: org.apache.kafka.common.security.oauthbearer.DefaultJwtRetriever / 중요도: medium
• sasl.oauthbearer.jwt.validator.class — 아이덴티티 제공자의 JWT를 검증하는 데 사용하는 JwtValidator 구현 클래스의 완전한 이름. 기본값은 하위 호환을 유지해요. 내장 구현: BrokerJwtValidator, ClientJwtValidator, DefaultJwtValidator. 유형: class / 기본값: org.apache.kafka.common.security.oauthbearer.DefaultJwtValidator / 중요도: medium
• sasl.oauthbearer.scope — 클라이언트 애플리케이션이 리소스/API에 부여받는 접근 수준이며 토큰 요청에 포함돼요. 이전에는 sasl.jaas.config의 scope 키로 저장됐었어요. scope JAAS 옵션은 비권장이며 향후 제거될 예정이에요. 우선순위: 구성 → JAAS. 유형: string / 기본값: null / 중요도: medium
• sasl.oauthbearer.token.endpoint.url — OAuth/OIDC 아이덴티티 제공자 URL. HTTP(S) 기반이면 토큰 엔드포인트 URL, 파일 기반이면 인가에 사용할 접근 토큰(JWT 직렬화 형태)이 담긴 파일을 지정해요. 유형: string / 기본값: null / 중요도: medium
• security.protocol — 브로커와 통신할 때 사용하는 프로토콜. 유형: string / 기본값: PLAINTEXT / 유효 값: (대소문자 무시) [SASL_SSL, PLAINTEXT, SSL, SASL_PLAINTEXT] / 중요도: medium
• send.buffer.bytes — 데이터를 보낼 때 사용하는 TCP 송신 버퍼(SO_SNDBUF) 크기. -1이면 OS 기본값. 유형: int / 기본값: 131072 (128 kibibytes) / 유효 값: [-1,...] / 중요도: medium
• socket.connection.setup.timeout.max.ms — 클라이언트가 소켓 연결이 설정되기를 기다리는 최대 시간. 각 연속 실패마다 지수적으로 증가해 이 최대값까지. 연결 폭풍을 피하려고 0.2의 무작위화 요인이 적용돼요. 유형: long / 기본값: 30000 (30초) / 중요도: medium
• socket.connection.setup.timeout.ms — 클라이언트가 소켓 연결이 설정되기를 기다리는 시간. 초기 백오프 값이며 지수적으로 증가해 socket.connection.setup.timeout.max.ms까지. 유형: long / 기본값: 10000 (10초) / 중요도: medium
• ssl.enabled.protocols — SSL 연결에 활성화된 프로토콜 목록. 기본값은 TLSv1.2,TLSv1.3로, 둘 다 TLSv1.3을 지원하면 TLSv1.3을 선호하고 그렇지 않으면 TLSv1.2로 폴백해요. 빈 목록이면 SSLEngine 기본값 사용. 유형: list / 기본값: TLSv1.2,TLSv1.3 / 중요도: medium
• ssl.keystore.type — 키 저장소 파일 형식. 기본 ssl.engine.factory.class가 지원하는 값은 [JKS, PKCS12, PEM]. 유형: string / 기본값: JKS / 중요도: medium
• ssl.protocol — SSLContext 생성에 사용하는 SSL 프로토콜. 기본값은 TLSv1.3. 유형: string / 기본값: TLSv1.3 / 중요도: medium
• ssl.provider — SSL 연결에 사용하는 보안 공급자 이름. 기본값은 JVM 기본 보안 공급자. 유형: string / 기본값: null / 중요도: medium
• ssl.truststore.type — 트러스트 저장소 파일 형식. 기본 ssl.engine.factory.class가 지원하는 값은 [JKS, PKCS12, PEM]. 유형: string / 기본값: JKS / 중요도: medium
• acks — 프로듀서가 요청을 완료로 간주하기 전에 리더가 받아야 하는 승인 수. 보내는 레코드의 내구성을 제어해요. 허용 설정:
  • acks=0: 서버의 승인을 전혀 기다리지 않아요. 레코드는 즉시 소켓 버퍼에 추가되고 전송된 것으로 간주돼요. 서버가 레코드를 받았는지 보장할 수 없고 retries 구성이 적용되지 않아요. 각 레코드의 오프셋은 항상 -1로 설정돼요.
  • acks=1: 리더가 레코드를 로컬 로그에 쓰고, 모든 팔로워의 승인을 기다리지 않고 응답해요. 리더가 승인 직후 팔로워가 복제하기 전에 실패하면 레코드가 유실돼요.
  • acks=all: 리더가 동기화된 복제본(in-sync replicas) 전체의 승인을 기다려요. 동기화된 복제본이 하나 이상 살아있는 한 레코드가 유실되지 않음을 보장해요. 가장 강한 보장이며 acks=-1과 동등해요.
  • 참고: 멱등성을 활성화하려면 이 값이 all이어야 해요. 충돌하는 구성이 설정됐는데 멱등성이 명시적으로 활성화되지 않으면 멱등성은 비활성화돼요.
  • 유형: string / 기본값: all / 유효 값: [all, -1, 0, 1] / 중요도: low
• config.providers — ConfigProvider 인터페이스를 구현하는 클래스의 쉼표로 구분된 별칭 이름. 외부 소스에서 구성 데이터(비밀번호, API 키, 자격 증명)를 로드할 수 있게 해줘요. 유형: list / 기본값: "" / 중요도: low
• enable.idempotence — true로 설정하면 프로듀서가 각 메시지의 정확히 하나의 사본만 스트림에 쓰이는지 보장해요. false면 브로커 장애 등으로 인한 재시도가 재시도된 메시지의 중복을 스트림에 쓸 수 있어요. 멱등성 활성화는 max.in.flight.requests.per.connection이 5 이하(허용 값에 대해 메시지 순서 보존), retries가 0보다 크고, acks가 all이어야 해요. 충돌하는 구성이 없으면 멱등성은 기본 활성화돼요. 충돌하는 구성이 있고 명시적으로 활성화되지 않으면 비활성화, 명시적으로 활성화되고 충돌 구성이 있으면 ConfigException이 발생해요. 유형: boolean / 기본값: true / 중요도: low
• enable.metrics.push — 클러스터에 이 클라이언트와 일치하는 클라이언트 지표 구독이 있는 경우 클라이언트 지표를 클러스터로 푸시할지 여부. 유형: boolean / 기본값: true / 중요도: low
• interceptor.classes — 인터셉터로 사용할 클래스 목록. org.apache.kafka.clients.producer.ProducerInterceptor 인터페이스를 구현하면 프로듀서가 받은 레코드를 Kafka 클러스터에 게시하기 전에 가로챌 수(선택적으로 변경할 수) 있어요. 기본적으로 인터셉터는 없어요. 유형: list / 기본값: "" / 중요도: low
• max.in.flight.requests.per.connection — 블록되기 전에 클라이언트가 단일 연결에서 보낼 미승인 요청의 최대 수. 이 값이 1보다 크고 enable.idempotence가 false로 설정되면 재시도로 인해 실패한 전송 후 메시지 순서가 바뀔 위험이 있어요. 재시도가 비활성화되거나 enable.idempotence가 true면 순서가 보존돼요. 또한 멱등성 활성화는 이 값이 5 이하여야 해요(브로커가 프로듀서당 최대 5개 배치만 유지하므로). 5보다 크면 이전 배치가 브로커 쪽에서 제거될 수 있어요. 유형: int / 기본값: 5 / 유효 값: [1,...] / 중요도: low
• metadata.max.age.ms — 파티션 리더십 변경을 보지 못했더라도 새 브로커·파티션을 능동적으로 발견하기 위해 메타데이터 갱신을 강제하는 시간(밀리초). 유형: long / 기본값: 300000 (5분) / 유효 값: [0,...] / 중요도: low
• metadata.max.idle.ms — 프로듀서가 유휴 토픽의 메타데이터를 캐시하는 시간을 제어해요. 마지막으로 생산된 이후 경과 시간이 유휴 지속 시간을 넘으면 토픽 메타데이터가 잊혀지고 다음 접근이 메타데이터 fetch를 강제해요. 유형: long / 기본값: 300000 (5분) / 유효 값: [5000,...] / 중요도: low
• metadata.recovery.rebootstrap.trigger.ms — metadata.recovery.strategy=rebootstrap로 구성된 클라이언트가 이 간격 동안 어떤 알려진 브로커에서도 메타데이터를 얻지 못하면 bootstrap.servers를 사용해 부트스트랩을 반복해요. 유형: long / 기본값: 300000 (5분) / 유효 값: [0,...] / 중요도: low
• metadata.recovery.strategy — 클라이언트가 아는 브로커 중 아무것도 사용할 수 없을 때 어떻게 복구할지 제어해요. none이면 실패, rebootstrap이면 부트스트랩 과정을 반복해요. 리부트스트랩은 브로커 집합이 메타데이터 갱신 전에 완전히 바뀔 수 있을 때 유용해요. 유형: string / 기본값: rebootstrap / 유효 값: (대소문자 무시) [REBOOTSTRAP, NONE] / 중요도: low
• metric.reporters — 지표 리포터로 사용할 클래스 목록. org.apache.kafka.common.metrics.MetricsReporter 인터페이스 구현 가능. 커스텀 리포터를 쓸 때 JmxReporter가 필요하면 목록에 명시적으로 추가해야 해요. 유형: list / 기본값: org.apache.kafka.common.metrics.JmxReporter / 중요도: low
• metrics.num.samples — 지표 계산을 위해 유지하는 샘플 수. 유형: int / 기본값: 2 / 유효 값: [1,...] / 중요도: low
• metrics.recording.level — 지표의 최고 기록 수준. INFO(필수 지표만, 프로덕션), DEBUG(대부분, 개발·테스트), TRACE(전부, 오버헤드 큼). 유형: string / 기본값: INFO / 유효 값: [INFO, DEBUG, TRACE] / 중요도: low
• metrics.sample.window.ms — 지표 샘플이 계산되는 시간 창. 유형: long / 기본값: 30000 (30초) / 유효 값: [0,...] / 중요도: low
• partitioner.adaptive.partitioning.enable — true로 설정하면 프로듀서가 브로커 성능에 적응해 더 빠른 브로커에 호스팅된 파티션에 더 많은 메시지를 생산해요. false면 균등 분포를 시도해요. 커스텀 파티셔너를 쓰면 효과가 없어요. 유형: boolean / 기본값: true / 중요도: low
• partitioner.availability.timeout.ms — 브로커가 파티션의 produce 요청을 이 시간 동안 처리하지 못하면 파티셔너가 그 파티션을 사용 불가로 간주해요. 값 0이면 이 로직을 비활성화. 커스텀 파티셔너를 쓰거나 partitioner.adaptive.partitioning.enable이 false면 효과가 없어요. 유형: long / 기본값: 0 / 유효 값: [0,...] / 중요도: low
• reconnect.backoff.max.ms — 반복 연결 실패한 브로커에 재연결할 때 기다리는 최대 시간. 각 연속 실패마다 지수적으로 증가하고 20% 무작위 지터가 추가돼요. 유형: long / 기본값: 1000 (1초) / 유효 값: [0,...] / 중요도: low
• reconnect.backoff.ms — 주어진 호스트에 재연결을 시도하기 전 기다리는 기본 시간. 초기 백오프 값이며 지수적으로 증가해 reconnect.backoff.max.ms까지. 유형: long / 기본값: 50 / 유효 값: [0,...] / 중요도: low
• retry.backoff.max.ms — 반복 실패한 브로커에 요청을 재시도할 때 기다리는 최대 시간. 클라이언트별 백오프가 각 실패마다 지수적으로 증가하고 0.2 무작위 지터가 적용돼요. retry.backoff.ms가 retry.backoff.max.ms보다 높으면 상수 백오프로 사용돼요. 유형: long / 기본값: 1000 (1초) / 유효 값: [0,...] / 중요도: low
• retry.backoff.ms — 주어진 토픽 파티션에 실패한 요청을 재시도하기 전에 기다리는 시간. 초기 백오프 값이며 지수적으로 증가해 retry.backoff.max.ms까지. 유형: long / 기본값: 100 / 유효 값: [0,...] / 중요도: low
• sasl.kerberos.kinit.cmd — Kerberos kinit 명령 경로. 유형: string / 기본값: /usr/bin/kinit / 중요도: low
• sasl.kerberos.min.time.before.relogin — 갱신 시도 사이의 로그인 스레드 수면 시간. 유형: long / 기본값: 60000 / 중요도: low
• sasl.kerberos.ticket.renew.jitter — 갱신 시간에 더하는 무작위 지터 비율. 유형: double / 기본값: 0.05 / 중요도: low
• sasl.kerberos.ticket.renew.window.factor — 로그인 스레드가 마지막 갱신 이후 티켓 만료까지 시간의 지정된 윈도우 요인에 도달할 때까지 수면하고 그때 티켓을 갱신해요. 유형: double / 기본값: 0.8 / 중요도: low
• sasl.login.connect.timeout.ms — 외부 인증 제공자 연결 타임아웃(밀리초)의 선택적 값. 현재 OAUTHBEARER에만 적용돼요. 유형: int / 기본값: null / 중요도: low
• sasl.login.read.timeout.ms — 외부 인증 제공자 읽기 타임아웃(밀리초)의 선택적 값. 현재 OAUTHBEARER에만 적용돼요. 유형: int / 기본값: null / 중요도: low
• sasl.login.refresh.buffer.seconds — 자격 증명 갱신 시 만료 전에 유지하는 버퍼 시간(초). 허용 값 0~3600(1시간), 기본 300(5분). 이 값과 sasl.login.refresh.min.period.seconds의 합이 남은 수명을 초과하면 둘 다 무시돼요. OAUTHBEARER만 적용. 유형: short / 기본값: 300 / 유효 값: [0,...,3600] / 중요도: low
• sasl.login.refresh.min.period.seconds — 로그인 갱신 스레드가 자격 증명을 갱신하기 전 기다리는 원하는 최소 시간(초). 허용 값 0~900(15분), 기본 60(1분). 합이 남은 수명을 초과하면 무시돼요. OAUTHBEARER만 적용. 유형: short / 기본값: 60 / 유효 값: [0,...,900] / 중요도: low
• sasl.login.refresh.window.factor — 로그인 갱신 스레드가 자격 증명 수명에 상대적인 지정된 윈도우 요인에 도달할 때까지 수면하고 그때 갱신해요. 허용 값 0.5~1.0, 기본 0.8(80%). OAUTHBEARER만 적용. 유형: double / 기본값: 0.8 / 유효 값: [0.5,...,1.0] / 중요도: low
• sasl.login.refresh.window.jitter — 로그인 갱신 스레드 수면 시간에 더하는, 자격 증명 수명에 상대적인 최대 무작위 지터. 허용 값 0~0.25, 기본 0.05(5%). OAUTHBEARER만 적용. 유형: double / 기본값: 0.05 / 유효 값: [0.0,...,0.25] / 중요도: low
• sasl.login.retry.backoff.max.ms — 외부 인증 제공자에 대한 로그인 시도 사이의 최대 대기(밀리초)의 선택적 값. 지수 백오프 사용. OAUTHBEARER만 적용. 유형: long / 기본값: 10000 (10초) / 중요도: low
• sasl.login.retry.backoff.ms — 외부 인증 제공자에 대한 로그인 시도 사이의 초기 대기(밀리초)의 선택적 값. 지수 백오프 사용. OAUTHBEARER만 적용. 유형: long / 기본값: 100 / 중요도: low
• sasl.oauthbearer.assertion.claim.exp.seconds — JWT가 유효한 미래의 초 수. 현재 시스템 시간을 기준으로 exp(Expiration) 클레임을 결정해요. 공식: exp = x + y(x=현재 타임스탬프 초, y=이 구성 값). sasl.oauthbearer.assertion.file 값이 제공되면 무시돼요. 유형: int / 기본값: 300 / 유효 값: [0,...,86400] / 중요도: low
• sasl.oauthbearer.assertion.claim.nbf.seconds — JWT가 유효한 과거의 초 수. 현재 시스템 시간을 기준으로 nbf(Not Before) 클레임을 결정해요. 공식: nbf = x - y. sasl.oauthbearer.assertion.file 값이 제공되면 무시돼요. 유형: int / 기본값: 60 / 유효 값: [0,...,3600] / 중요도: low
• sasl.oauthbearer.clock.skew.seconds — OAuth/OIDC 제공자와 브로커 사이의 시간 차이를 허용할 (선택적) 값(초). 유형: int / 기본값: 30 / 중요도: low
• sasl.oauthbearer.expected.audience — 브로커가 JWT가 예상 audience 중 하나에 대해 발급됐는지 검증하는 데 사용할 (선택적) 쉼표로 구분된 설정. JWT의 aud 클레임과 정확히 일치하지 않으면 JWT를 거부하고 인증이 실패해요. 유형: list / 기본값: "" / 중요도: low
• sasl.oauthbearer.expected.issuer — 브로커가 JWT가 예상 발급자에 의해 생성됐는지 검증하는 데 사용할 (선택적) 설정. JWT의 iss 클레임과 정확히 일치하지 않으면 JWT를 거부하고 인증이 실패해요. 유형: string / 기본값: null / 중요도: low
• sasl.oauthbearer.header.urlencode — OAuth 클라이언트가 RFC6749에 따라 인가 헤더에서 client_id와 client_secret을 URL 인코딩하게 할지 여부. 하위 호환성을 위해 기본값은 false. 유형: boolean / 기본값: false / 중요도: low
• sasl.oauthbearer.jwks.endpoint.refresh.ms — JWKS 캐시를 갱신하는 사이에 브로커가 기다리는 (선택적) 값(밀리초). 유형: long / 기본값: 3600000 (1시간) / 중요도: low
• sasl.oauthbearer.jwks.endpoint.retry.backoff.max.ms — 외부 인증 제공자에서 JWKS를 가져오는 시도 사이의 최대 대기(밀리초)의 선택적 값. 지수 백오프 사용. 유형: long / 기본값: 10000 (10초) / 중요도: low
• sasl.oauthbearer.jwks.endpoint.retry.backoff.ms — 외부 인증 제공자에서 JWKS 조회 시도 사이의 초기 대기(밀리초)의 선택적 값. 지수 백오프 사용. 유형: long / 기본값: 100 / 중요도: low
• sasl.oauthbearer.scope.claim.name — scope의 OAuth 클레임은 흔히 scope지만, 제공자가 다른 이름을 쓰면 JWT 페이로드에 포함할 scope 클레임의 다른 이름을 제공할 수 있어요. 유형: string / 기본값: scope / 중요도: low
• sasl.oauthbearer.sub.claim.name — subject의 OAuth 클레임은 흔히 sub지만, 제공자가 다른 이름을 쓰면 JWT 페이로드에 포함할 subject 클레임의 다른 이름을 제공할 수 있어요. 유형: string / 기본값: sub / 중요도: low
• security.providers — 각각 보안 알고리즘을 구현하는 공급자를 반환하는, 구성 가능한 creator 클래스 목록. org.apache.kafka.common.security.auth.SecurityProviderCreator 인터페이스를 구현해야 해요. 유형: string / 기본값: null / 중요도: low
• ssl.cipher.suites — 암호 스위트 목록. TLS/SSL을 사용한 연결의 보안 설정을 협상하는 인증·암호화·MAC·키 교환 알고리즘의 명명된 조합. 기본적으로 사용 가능한 모든 암호 스위트가 지원돼요. 유형: list / 기본값: "" / 중요도: low
• ssl.endpoint.identification.algorithm — 서버 인증서로 서버 호스트 이름을 검증하는 엔드포인트 식별 알고리즘. 유형: string / 기본값: https / 중요도: low
• ssl.engine.factory.class — SSLEngine 객체를 제공하는 org.apache.kafka.common.security.auth.SslEngineFactory 유형의 클래스. 기본값은 org.apache.kafka.common.security.ssl.DefaultSslEngineFactory. CommonNameLoggingSslEngineFactory로 설정하면 만료된 SSL 인증서의 공통 이름을 INFO 로그로 기록해요(새 연결 설정에 약간의 지연 발생, 커스텀 truststore라 보안 위험 간주될 수 있음). 유형: class / 기본값: null / 중요도: low
• ssl.keymanager.algorithm — SSL 연결을 위해 키 매니저 팩토리가 사용하는 알고리즘. 기본값은 JVM에 구성된 것. 유형: string / 기본값: SunX509 / 중요도: low
• ssl.secure.random.implementation — SSL 암호화 작업에 사용할 SecureRandom PRNG 구현. 유형: string / 기본값: null / 중요도: low
• ssl.trustmanager.algorithm — SSL 연결을 위해 트러스트 매니저 팩토리가 사용하는 알고리즘. 기본값은 JVM에 구성된 것. 유형: string / 기본값: PKIX / 중요도: low
• transaction.timeout.ms — 코디네이터가 트랜잭션을 능동적으로 중단하기 전에 트랜잭션이 열려 있을 수 있는 최대 시간(밀리초). 트랜잭션 시작은 첫 파티션이 추가된 시점으로 설정돼요. 이 값이 브로커의 transaction.max.timeout.ms 설정보다 크면 요청이 InvalidTxnTimeoutException 오류로 실패해요. 유형: int / 기본값: 60000 (1분) / 중요도: low
• transaction.two.phase.commit.enable — true로 설정하면 클라이언트가 two phase commit 프로토콜에 참여하고 있음을 브로커에 알리고, 이 클라이언트가 시작한 트랜잭션은 결코 만료되지 않아요. 유형: boolean / 기본값: false / 중요도: low
• transactional.id — 트랜잭션 전달에 사용할 TransactionalId. 여러 프로듀서 세션에 걸친 신뢰성 의미(semantics)를 가능하게 해요 — 같은 TransactionalId를 쓰는 트랜잭션이 새 트랜잭션을 시작하기 전에 완료됐음을 클라이언트가 보장할 수 있으니까요. TransactionalId를 제공하지 않으면 프로듀서는 멱등 전달로 제한돼요. TransactionalId가 구성되면 enable.idempotence가 암시돼요. 기본적으로 TransactionId는 구성되지 않아 트랜잭션을 쓸 수 없어요. 참고로 기본적으로 트랜잭션은 최소 3개 브로커의 클러스터를 요구하며, 개발용으로는 브로커 설정 transaction.state.log.replication.factor를 조정할 수 있어요. 유형: string / 기본값: null / 유효 값: 비어 있지 않은 문자열 / 중요도: low

더 알아보기 (Learn more)

• 프로듀서 내구성은 acks(0/1/all)로 결정되고, 멱등성(enable.idempotence)을 켜면 순서·중복 방지가 강화돼요.
• 배칭 성능은 batch.size·linger.ms로, 재시도는 retries보다 delivery.timeout.ms로 제어하는 걸 권장해요.
• 트랜잭션 전달을 쓰려면 transactional.id를 설정해야 해요.