Mar 23, 2026

마지막 업데이트 Mar 30, 2026

Kafka max.poll.interval.ms 가이드

Kafka consumer가 group에서 자꾸 빠진다면 max.poll.interval.ms는 가장 먼저 확인할 만한 설정 중 하나이면서도 동시에 가장 오해하기 쉬운 값이기도 합니다.

짧게 말하면, 이 값을 throughput knob처럼 보지 말고, 먼저 poll 사이 실제 처리 시간이 얼마나 걸리는지 측정한 뒤 interval이 너무 작은지, 아니면 work unit이 너무 큰지를 판단해야 합니다.

`max.poll.interval.ms`가 실제로 지키는 것

Kafka consumer config 문서에서 max.poll.interval.ms는 poll() 호출 사이 허용되는 최대 지연 시간입니다.

즉 이 값은 group 입장에서 consumer liveness를 지키는 guardrail에 가깝습니다. 느린 작업, 큰 batch, blocked handler를 자동으로 해결해주지는 않습니다.

왜 이 설정이 lag incident에서 자주 보일까

팀은 보통 아래 증상을 먼저 보고 나서 이 값을 찾게 됩니다.

lag 증가
frequent rebalance
살아 있는 것처럼 보이는데 진전이 없는 consumer
partition이 member 사이를 너무 자주 이동함

이건 자연스럽습니다. 느린 handler가 먼저 throughput을 떨어뜨리고, 그다음 poll timing을 망치고, 마지막에 group stability까지 무너뜨리기 때문입니다.

실제 원인은 slow handler인 경우가 많습니다

이 설정 자체보다 아래가 더 본질적인 원인일 때가 많습니다.

느린 downstream DB나 API
너무 큰 batch 처리
유독 무거운 partition이나 message type
다음 poll 전에 너무 많은 synchronous business logic 수행

max.poll.interval.ms를 늘리면 증상 위치는 바뀔 수 있지만 consumer 설계가 좋아지는 것은 아닙니다.

값을 바꾸기 전에 무엇을 봐야 하나

아래 순서가 중요합니다.

poll 사이 실제 처리 시간은 얼마나 걸리는가
어떤 partition이나 message type이 특히 느린가
rebalance timing이 downstream slowdown과 겹치는가
max.poll.records가 한 번의 poll batch를 너무 비싸게 만드는가

이 순서로 봐야 interval이 작은 문제인지, work unit이 큰 문제인지 분리할 수 있습니다.

흔한 원인

1. handler가 현재 poll window보다 느림

consumer는 실제로 일을 하지만 group 기준으로 건강하게 남아 있기에는 너무 느립니다.

2. batch size가 너무 큼

한 번의 poll이 다음 poll을 너무 늦게 만듭니다.

3. rebalance churn이 문제를 더 키움

poll timing이 더 나빠지고 group이 rebalance하고 progress가 더 멈추면서 lag가 커지는 사이클이 생깁니다.

4. 작업량은 그대로인데 timeout만 늘림

증상은 뒤로 밀리지만 병목은 그대로 남습니다.

실전 점검 순서

1. poll 사이 실제 시간을 측정하세요

이것이 첫 번째 진실입니다.

2. handler latency와 `max.poll.interval.ms`를 비교하세요

작업 시간이 거의 항상 interval을 넘는다면 group은 원래 설계대로 반응하는 것입니다.

3. `max.poll.records`와 batch 비용을 보세요

값을 크게 늘리는 것보다 한 번의 work unit을 줄이는 것이 더 쉬운 해결책일 수 있습니다.

4. 느린 시점과 rebalance event를 비교하세요

application slowness와 pure group instability를 분리할 수 있습니다.

5. 실제 fix가 consumer design인지, batch size인지, poll interval인지 결정하세요

처음부터 timeout 값만 만지면 안 됩니다.

바로 확인할 수 있는 명령어

kafka-consumer-groups.sh --bootstrap-server <broker:9092> --group <group> --describe
grep -i "max.poll.interval" <consumer-log-file>
grep -i "poll" <consumer-log-file>

이 명령어들로 group progress와 delayed poll, interval violation 로그를 함께 비교할 수 있습니다.

실전 기준

max.poll.interval.ms를 늘리는 것이 가장 먼저 떠오른다면, 이미 한 레이어 뒤에서 증상만 보고 있을 가능성이 큽니다.

많은 incident에서 더 좋은 질문은 아래입니다.

왜 한 번의 작업 단위가 poll 사이에서 이렇게 오래 걸리는가

이 질문이 timeout만 늘리는 것보다 더 오래 가는 해결책으로 이어지는 경우가 많습니다.

하나 더 비교하면 좋은 것

poll 사이 시간을 측정할 때는 평균 처리 시간뿐 아니라 최악의 처리 구간도 같이 비교하세요.

많은 consumer는 평균적으로는 괜찮아 보여도 드문 무거운 batch에서 반복적으로 실패합니다. 실제 rebalance를 만드는 것은 그런 tail case인 경우가 많습니다.

FAQ

Q. 그냥 `max.poll.interval.ms`를 늘리면 되나요?

consumer가 poll 사이에 너무 많은 일을 하는지 먼저 알아야 합니다.

Q. 이 값이 lag에 직접 영향을 주나요?

간접적으로는 그렇습니다. poll deadline을 놓치면 instability가 생기고 useful work가 멈춥니다.

Q. 가장 빠른 첫 단계는 무엇인가요?

추측하지 말고 poll 사이 실제 처리 시간을 측정하는 것입니다.

Q. 다음으로 같이 보면 좋은 글은 무엇인가요?

보통 Kafka Rebalancing Too Often이나 Kafka Consumer Lag Increasing입니다.

먼저 읽어볼 가이드

검색 유입이 많은 핵심 글부터 이어서 보세요.