컨슈머·공유 컨슈머 설정

컨슈머·공유 컨슈머 설정 (Consumer and Share Consumer Configs)

컨슈머(데이터를 Kafka에서 읽는 클라이언트)와 공유 컨슈머(Share Consumer)의 설정 항목들을 정리한 문서예요. 그룹 관리, 오프셋 리셋, fetch 크기, isolation level, 그리고 공유 컨슈머 전용 동작을 결정하는 값들이 여기 있어요.

출처: 문서

본문

아래는 컨슈머와 공유 컨슈머 설정 항목들이에요.

• bootstrap.servers — Kafka 클러스터에 초기 연결을 설정하는 데 쓰는 host/port 쌍 목록. 클라이언트가 이 목록으로 부트스트랩해 전체 Kafka 브로커 집합을 발견해요. 목록의 서버 순서는 상관없지만, 어떤 서버가 다운되더라도 복원력을 위해 두 개 이상의 서버를 포함하는 걸 권장해요. 이 목록에 브로커 전체가 포함될 필요는 없어요. 형식은 host1:port1,host2:port2,...이어야 해요.
  • 유형: list / 중요도: high
• key.deserializer — org.apache.kafka.common.serialization.Deserializer 인터페이스를 구현하는 키용 역직렬화기 클래스. 유형: class / 중요도: high
• value.deserializer — org.apache.kafka.common.serialization.Deserializer 인터페이스를 구현하는 값용 역직렬화기 클래스. 유형: class / 중요도: high
• fetch.min.bytes — fetch 요청에 서버가 반환해야 하는 최소 데이터 양. 데이터가 충분하지 않으면 요청은 그만큼 데이터가 쌓일 때까지 기다려요. 기본 설정 1바이트는 데이터가 그만큼(1바이트) 준비되거나 fetch 요청이 타임아웃될 때 응답한다는 뜻이에요. 더 큰 값으로 설정하면 서버가 더 많은 데이터가 쌓이길 기다리게 되어 서버 처리량을 약간 높일 수 있지만 추가 지연이 생겨요. 브로커의 총 데이터가 fetch.min.bytes를 초과해도, 파티션별 상한 max.partition.fetch.bytes와 반환 상한 fetch.max.bytes 때문에 실제 반환 크기가 이 값보다 작을 수 있어요.
  • 유형: int / 기본값: 1 / 유효 값: [0,...] / 중요도: high
• group.id — 이 컨슈머가 속한 컨슈머 그룹을 식별하는 고유 문자열. 컨슈머가 subscribe(topic)을 사용하는 그룹 관리 기능이나 Kafka 기반 오프셋 관리 전략을 쓰면 이 속성이 필요해요. 유형: string / 기본값: null / 중요도: high
• group.protocol — 컨슈머가 사용하는 그룹 프로토콜. 지원 값은 classic 또는 consumer예요. 기본값은 classic. 유형: string / 기본값: classic / 유효 값: (대소문자 무시) [CONSUMER, CLASSIC] / 중요도: high
• heartbeat.interval.ms — Kafka의 그룹 관리 기능을 쓸 때 컨슈머 코디네이터로 보내는 하트비트 사이의 예상 시간. 하트비트는 컨슈머 세션을 활성으로 유지하고 새 컨슈머가 그룹에 조인·탈퇴할 때 리밸런스를 돕는 데 사용돼요. 이 구성은 group.protocol이 classic으로 설정된 경우에만 지원돼요. 그 경우 값은 session.timeout.ms보다 낮아야 하고, 보통 그 값의 1/3 이하로 설정하는 게 좋아요. 정상 리밸런스의 예상 시간을 제어하려면 더 낮출 수도 있어요. group.protocol이 consumer로 설정되면 이 구성은 지원되지 않아요 — 하트비트 간격은 브로커의 group.consumer.heartbeat.interval.ms로 제어되거든요.
  • 유형: int / 기본값: 3000 (3초) / 중요도: high
• max.partition.fetch.bytes — 서버가 반환하는 파티션별 최대 데이터 양. 컨슈머는 레코드를 배치로 가져와요. fetch에서 첫 번째 비어 있지 않은 파티션의 첫 레코드 배치가 이 한도보다 크면, 컨슈머가 진행할 수 있도록 그 배치는 여전히 반환돼요. 브로커가 받아들이는 최대 레코드 배치 크기는 message.max.bytes(브로커 구성)나 max.message.bytes(토픽 구성)로 정의돼요. 컨슈머 요청 크기 제한은 fetch.max.bytes를 참고해요.
  • 유형: int / 기본값: 1048576 (1 mebibyte) / 유효 값: [0,...] / 중요도: high
• session.timeout.ms — Kafka의 그룹 관리 기능을 쓸 때 클라이언트 장애를 감지하는 데 사용하는 타임아웃. 클라이언트는 주기적 하트비트를 보내 브로커에 활성 상태를 알려요. 이 세션 타임아웃이 만료되기 전에 브로커가 하트비트를 받지 못하면, 브로커는 이 클라이언트를 그룹에서 제거하고 리밸런스를 시작해요. 값은 브로커 구성의 group.min.session.timeout.ms와 group.max.session.timeout.ms로 구성된 허용 범위 안이어야 해요. 이 클라이언트 구성은 group.protocol이 consumer로 설정되면 지원되지 않아요 — 그 경우 세션 타임아웃은 브로커 구성 group.consumer.session.timeout.ms로 제어돼요.
  • 유형: int / 기본값: 45000 (45초) / 중요도: 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
• allow.auto.create.topics — 토픽을 구독·할당할 때 브로커에서 자동 토픽 생성을 허용할지 여부. 구독 중인 토픽은 브로커가 auto.create.topics.enable 브로커 구성으로 허용하는 경우에만 자동 생성돼요. 유형: boolean / 기본값: true / 중요도: medium
• auto.offset.reset — Kafka에 초기 오프셋이 없거나 현재 오프셋이 더 이상 서버에 없을 때(예: 데이터 삭제) 할 일:
  • earliest: 오프셋을 가장 이른 오프셋으로 자동 재설정
  • latest: 오프셋을 가장 최신 오프셋으로 자동 재설정
  • by_duration:<duration>: 현재 타임스탬프로부터 설정된 기간만큼 이전으로 오프셋을 자동 재설정. <duration>은 ISO8601 형식(PnDTnHnMn.nS)이어야 하고 음수 기간은 허용되지 않아요.
  • none: 컨슈머 그룹에 이전 오프셋이 없으면 컨슈머에게 예외를 던져요.
  • 그 밖의 값: 컨슈머에게 예외를 던져요.
  • 참고: 이 값을 latest로 설정하면서 파티션 수를 바꾸면 메시지 전달 손실이 생길 수 있어요 — 프로듀서가 컨슈머가 오프셋을 재설정하기 전에 새로 추가된 파티션(아직 초기 오프셋이 없음)으로 메시지를 보내기 시작할 수 있으니까요.
  • 유형: string / 기본값: latest / 유효 값: [latest, earliest, none, by_duration:PnDTnHnMn.nS] / 중요도: medium
• client.dns.lookup — 클라이언트가 DNS 조회를 사용하는 방식을 제어해요. use_all_dns_ips는 반환된 각 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
• connections.max.idle.ms — 이 구성이 지정하는 밀리초 수가 지난 뒤 유휴 연결을 닫아요. 유형: long / 기본값: 540000 (9분) / 중요도: medium
• default.api.timeout.ms — 클라이언트 API의 타임아웃(밀리초). timeout 파라미터를 지정하지 않은 모든 클라이언트 작업의 기본 타임아웃이에요. 유형: int / 기본값: 60000 (1분) / 유효 값: [0,...] / 중요도: medium
• enable.auto.commit — true면 컨슈머의 오프셋이 백그라운드에서 주기적으로 커밋돼요. 유형: boolean / 기본값: true / 중요도: medium
• exclude.internal.topics — 구독 패턴과 일치하는 내부 토픽을 구독에서 제외할지 여부. 내부 토픽에 명시적으로 구독하는 건 항상 가능해요. 유형: boolean / 기본값: true / 중요도: medium
• fetch.max.bytes — fetch 요청에 서버가 반환해야 하는 최대 데이터 양. fetch에서 첫 번째 비어 있지 않은 파티션의 첫 레코드 배치가 이 값보다 크면, 컨슈머가 진행할 수 있도록 그 배치는 여전히 반환돼요. 그래서 절대 상한은 아니에요. 브로커가 받아들이는 최대 레코드 배치 크기는 message.max.bytes(브로커)나 max.message.bytes(토픽)로 정의돼요. fetch 요청은 많은 파티션으로 구성되며, fetch 요청에서 각 파티션에 반환되는 데이터 양을 제어하는 또 다른 설정 max.partition.fetch.bytes가 있어요. 컨슈머는 여러 fetch를 병렬로 수행한다는 점을 참고해요.
  • 유형: int / 기본값: 52428800 (50 mebibytes) / 유효 값: [0,...] / 중요도: medium
• group.instance.id — 최종 사용자가 제공하는 컨슈머 인스턴스의 고유 식별자. 비어 있지 않은 문자열만 허용돼요. 설정하면 컨슈머가 정적 멤버(static member)로 간주되는데, 이는 언제든 그룹 안에 이 ID를 가진 인스턴스가 하나만 허용된다는 뜻이에요. 더 큰 세션 타임아웃과 함께 사용하면 일시적 사용 불가(예: 프로세스 재시작)로 인한 그룹 리밸런스를 피할 수 있어요. 설정하지 않으면 컨슈머는 전통적인 동작인 동적 멤버(dynamic member)로 그룹에 조인해요. 유형: string / 기본값: null / 유효 값: 비어 있지 않은 문자열 / 중요도: medium
• group.remote.assignor — 사용할 서버 측 할당자(assignor) 이름. 지정하지 않으면 그룹 코디네이터가 브로커 구성 group.consumer.assignors에 정의된 첫 번째 할당자를 골라요. 이 구성은 group.protocol이 consumer로 설정된 경우에만 적용돼요. 유형: string / 기본값: null / 중요도: medium
• isolation.level — 트랜잭션으로 작성된 메시지를 어떻게 읽을지 제어해요. read_committed로 설정하면 consumer.poll()이 커밋된 트랜잭션 메시지만 반환해요. read_uncommitted(기본값)로 설정하면 중단된 트랜잭션 메시지까지 모든 메시지를 반환해요. 비트랜잭션 메시지는 두 모드 모두에서 무조건 반환돼요. 메시지는 항상 오프셋 순서로 반환돼요. 따라서 read_committed 모드에서 consumer.poll()은 마지막 안정 오프셋(LSO, 첫 번째 열린 트랜잭션의 오프셋보다 하나 작은 값)까지만 반환해요. 특히 진행 중인 트랜잭션 메시지 뒤에 나타나는 메시지는 해당 트랜잭션이 완료될 때까지 보류돼요. 그 결과 read_committed 컨슈머는 진행 중인 트랜잭션이 있을 때 하이 워터마크(high watermark)까지 읽지 못해요. 또한 read_committed에서 seekToEnd는 LSO를 반환해요.
  • 유형: string / 기본값: read_uncommitted / 유효 값: [read_committed, read_uncommitted] / 중요도: medium
• max.poll.interval.ms — 컨슈머 그룹 관리 사용 시 poll() 호출 사이의 최대 지연. 더 많은 레코드를 가져오기 전에 컨슈머가 유휴 상태일 수 있는 시간의 상한을 둬요. 이 타임아웃이 만료되기 전에 poll()이 호출되지 않으면 컨슈머는 실패한 것으로 간주되고, 파티션을 다른 멤버에게 재할당하기 위해 그룹이 리밸런스해요. 이 타임아웃에 도달하는 컨슈머(비 null group.instance.id 사용)의 경우 파티션은 즉시 재할당되지 않아요. 대신 컨슈머가 하트비트 전송을 멈추고, 세션 타임아웃(Classic 리밸런스 프로토콜이면 클라이언트 구성 session.timeout.ms, Consumer 프로토콜이면 브로커 구성 group.consumer.session.timeout.ms)이 만료된 후 파티션이 재할당돼요. 이는 종료된 정적 컨슈머의 동작을 반영해요.
  • 유형: int / 기본값: 300000 (5분) / 유효 값: [1,...] / 중요도: medium
• max.poll.records — 단일 poll() 호출에서 반환되는 최대 레코드 수. max.poll.records는 기본 fetch 동작에는 영향을 주지 않아요. 컨슈머는 각 fetch 요청의 레코드를 캐시하고 각 poll에서 점진적으로 반환해요. 유형: int / 기본값: 500 / 유효 값: [1,...] / 중요도: medium
• partition.assignment.strategy — 그룹 관리 사용 시 컨슈머 인스턴스 간 파티션 소유권을 분배하기 위해 클라이언트가 사용할, 지원되는 파티션 할당 전략의 선호 순으로 정렬된 클래스 이름/클래스 유형 목록. 사용 가능한 옵션:
  • org.apache.kafka.clients.consumer.RangeAssignor: 토픽별로 파티션 할당.
  • org.apache.kafka.clients.consumer.RoundRobinAssignor: 라운드 로빈 방식으로 파티션 할당.
  • org.apache.kafka.clients.consumer.StickyAssignor: 가능한 한 많은 기존 파티션 할당을 보존하면서 최대 균형을 이룬 할당을 보장.
  • org.apache.kafka.clients.consumer.CooperativeStickyAssignor: StickyAssignor와 같은 로직을 따르되 협력적(cooperative) 리밸런싱 허용.
  • 기본 할당자는 [RangeAssignor, CooperativeStickyAssignor]로, 기본적으로 RangeAssignor를 사용하되 목록에서 RangeAssignor를 제거하는 단일 롤링 바운스만으로 CooperativeStickyAssignor로 업그레이드할 수 있어요. org.apache.kafka.clients.consumer.ConsumerPartitionAssignor 인터페이스를 구현하면 커스텀 할당 전략을 끼워 넣을 수 있어요.
  • 유형: list / 기본값: class org.apache.kafka.clients.consumer.RangeAssignor,class org.apache.kafka.clients.consumer.CooperativeStickyAssignor / 중요도: medium
• receive.buffer.bytes — 데이터를 읽을 때 사용하는 TCP 수신 버퍼(SO_RCVBUF) 크기. -1이면 OS 기본값. 유형: int / 기본값: 65536 (64 kibibytes) / 유효 값: [-1,...] / 중요도: medium
• request.timeout.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)*;. 유형: 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 어서션이 들어 있는 파일. 캐싱·파일 변경 감지를 통해 재시작 없이 "라이브" 어서션 교체가 가능해요. 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.file 값이 제공되면 무시돼요. 유형: password / 기본값: null / 중요도: medium
• sasl.oauthbearer.assertion.template.file — JWT 어서션 만들 때 사용할 JWT 헤더/페이로드 클레임을 담은 파일을 지정하는 선택적 구성. 모든 제공자가 같은 클레임을 요구하지 않으므로 정적 헤더 값·클레임을 제공할 수 있게 해줘요. sasl.oauthbearer.assertion.file 값이 제공되면 무시돼요. 유형: string / 기본값: null / 중요도: medium
• sasl.oauthbearer.client.credentials.client.id — 토큰을 요청하는 클라이언트를 식별하는 ID. 이전에는 JAAS의 clientId로 저장됐었어요(하위 호환용, 비권장). 우선순위: 구성 → JAAS clientId. 유형: string / 기본값: null / 중요도: medium
• sasl.oauthbearer.client.credentials.client.secret — 토큰을 요청하는 클라이언트의 시크릿. 이전에는 JAAS의 clientSecret로 저장(하위 호환용, 비권장). 우선순위: 구성 → JAAS. 유형: password / 기본값: null / 중요도: medium
• sasl.oauthbearer.jwks.endpoint.url — 제공자의 JWKS(JSON Web Key Set)를 가져올 수 있는 OAuth/OIDC 제공자 URL. HTTP(S) 기반이면 시작 시 키를 가져와 캐시하고 필요 시 재조회, 파일 기반이면 시작 시 파일을 로드해요. 유형: 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에 부여받는 접근 수준이며 토큰 요청에 포함돼요. 이전에는 JAAS의 scope로 저장(비권장). 우선순위: 구성 → 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
• share.acknowledgement.mode — 공유 컨슈머의 승인(acknowledgement) 모드를 제어해요. implicit으로 설정하면 컨슈머의 승인 모드가 암시적이며, 레코드 전달을 승인하기 위해 org.apache.kafka.clients.consumer.ShareConsumer.acknowledge()를 사용해선 안 돼요. 대신 다음 poll() 또는 커밋 호출에서 전달이 암시적으로 승인돼요. explicit으로 설정하면 컨슈머의 승인 모드가 명시적이며, 레코드 전달을 승인하기 위해 SharedConsumer.acknowledge()를 반드시 사용해야 해요.
  • 유형: string / 기본값: implicit / 유효 값: [implicit, explicit] / 중요도: medium
• share.acquire.mode — 공유 컨슈머의 획득(acquire) 모드를 제어해요. record_limit으로 설정하면 각 poll()에서 반환되는 레코드 수가 max.poll.records 값을 넘지 않아요. batch_optimized로 설정하면 각 poll() 호출에서 반환되는 레코드 수가 최적화를 위해 배치 경계에 맞춰 max.poll.records를 넘을 수 있어요.
  • 유형: string / 기본값: BATCH_OPTIMIZED / 유효 값: [batch_optimized, record_limit] / 중요도: 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. 유형: 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
• auto.commit.interval.ms — enable.auto.commit이 true로 설정된 경우 컨슈머 오프셋이 Kafka에 자동 커밋되는 빈도(밀리초). 유형: int / 기본값: 5000 (5초) / 유효 값: [0,...] / 중요도: low
• check.crcs — 소비되는 레코드의 CRC32를 자동으로 검사할지 여부. 전송 중·디스크의 메시지 손상을 방지해요. 약간의 오버헤드를 추가하므로 극단적인 성능을 원하는 경우 비활성화할 수 있어요. 유형: boolean / 기본값: true / 중요도: low
• client.id — 요청 시 서버에 전달하는 ID 문자열. 서버 측 요청 로깅에 애플리케이션 이름을 포함해 요청 출처를 추적하기 위한 목적. 유형: string / 기본값: "" / 중요도: low
• client.rack — 이 클라이언트의 랙 식별자. 클라이언트가 물리적으로 어디 있는지 나타내는 아무 문자열이 될 수 있고, 브로커 구성 broker.rack과 대응돼요. 유형: string / 기본값: "" / 중요도: low
• config.providers — ConfigProvider 인터페이스를 구현하는 클래스의 쉼표로 구분된 별칭 이름. 외부 소스에서 구성 데이터를 로드할 수 있게 해줘요. 유형: list / 기본값: "" / 중요도: low
• enable.metrics.push — 클러스터에 이 클라이언트와 일치하는 클라이언트 지표 구독이 있는 경우 클라이언트 지표를 클러스터로 푸시할지 여부. 유형: boolean / 기본값: true / 중요도: low
• fetch.max.wait.ms — fetch.min.bytes가 주는 요구를 즉시 충족할 데이터가 없을 때, fetch 요청에 응답하기 전에 서버가 블록하는 최대 시간. 이 구성은 로컬 로그 fetch에만 사용돼요. 원격 fetch 최대 대기 시간은 브로커 구성 remote.fetch.max.wait.ms를 참고해요. 유형: int / 기본값: 500 / 유효 값: [0,...] / 중요도: low
• interceptor.classes — 인터셉터로 사용할 클래스 목록. org.apache.kafka.clients.consumer.ConsumerInterceptor 인터페이스를 구현하면 컨슈머가 받은 레코드를 가로챌 수 있어요. 기본적으로 없어요. 유형: list / 기본값: "" / 중요도: low
• metadata.max.age.ms — 파티션 리더십 변경을 보지 못했더라도 새 브로커·파티션을 발견하기 위해 메타데이터 갱신을 강제하는 시간(밀리초). 유형: long / 기본값: 300000 (5분) / 유효 값: [0,...] / 중요도: 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 — 지표 리포터 클래스 목록. 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
• 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 지터. 유형: 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, 기본 300. 합이 남은 수명을 초과하면 무시. OAUTHBEARER만 적용. 유형: short / 기본값: 300 / 유효 값: [0,...,3600] / 중요도: low
• sasl.login.refresh.min.period.seconds — 자격 증명 갱신 전 기다리는 원하는 최소 시간(초). 허용 0~900, 기본 60. 합이 남은 수명을 초과하면 무시. OAUTHBEARER만 적용. 유형: short / 기본값: 60 / 유효 값: [0,...,900] / 중요도: low
• sasl.login.refresh.window.factor — 자격 증명 수명에 상대적인 지정된 윈도우 요인에 도달할 때까지 수면하고 그때 갱신. 허용 0.5~1.0, 기본 0.8. OAUTHBEARER만 적용. 유형: double / 기본값: 0.8 / 유효 값: [0.5,...,1.0] / 중요도: low
• sasl.login.refresh.window.jitter — 갱신 스레드 수면 시간에 더하는, 자격 증명 수명에 상대적인 최대 무작위 지터. 허용 0~0.25, 기본 0.05. 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 클레임 결정. 공식 exp = x + y. sasl.oauthbearer.assertion.file 값이 제공되면 무시돼요. 유형: int / 기본값: 300 / 유효 값: [0,...,86400] / 중요도: low
• sasl.oauthbearer.assertion.claim.nbf.seconds — JWT가 유효한 과거의 초 수. 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 클레임과 일치하지 않으면 거부. 유형: list / 기본값: "" / 중요도: low
• sasl.oauthbearer.expected.issuer — 브로커가 JWT가 예상 발급자에 의해 생성됐는지 검증하는 (선택적) 설정. iss 클레임과 일치하지 않으면 거부. 유형: 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 클래스 목록. SecurityProviderCreator 인터페이스 구현 필요. 유형: string / 기본값: null / 중요도: low
• ssl.cipher.suites — 암호 스위트 목록. 기본적으로 사용 가능한 모든 암호 스위트 지원. 유형: list / 기본값: "" / 중요도: low
• ssl.endpoint.identification.algorithm — 서버 인증서로 서버 호스트 이름을 검증하는 엔드포인트 식별 알고리즘. 유형: string / 기본값: https / 중요도: low
• ssl.engine.factory.class — SSLEngine 객체를 제공하는 SslEngineFactory 유형의 클래스. 기본값은 DefaultSslEngineFactory. 유형: class / 기본값: null / 중요도: low
• ssl.keymanager.algorithm — 키 매니저 팩토리가 사용하는 알고리즘. 기본값은 JVM에 구성된 것. 유형: string / 기본값: SunX509 / 중요도: low
• ssl.secure.random.implementation — SSL 암호화 작업에 사용할 SecureRandom PRNG 구현. 유형: string / 기본값: null / 중요도: low
• ssl.trustmanager.algorithm — 트러스트 매니저 팩토리가 사용하는 알고리즘. 기본값은 JVM에 구성된 것. 유형: string / 기본값: PKIX / 중요도: low

더 알아보기 (Learn more)

• 컨슈머 그룹의 핵심은 group.id, 하트비트·세션 타임아웃, 그리고 max.poll.interval.ms예요. 이 값들을 크게 벗어나면 리밸런스가 잦아질 수 있어요.
• 트랜잭션 메시지를 읽는지에 따라 isolation.level을 read_committed로 바꿔야 할 수 있어요.
• 공유 컨슈머(Share Consumer)는 share.* 항목으로 승인·획득 동작을 제어해요.