Mar 23, 2026

마지막 업데이트 Mar 31, 2026

Kafka 메시지가 소비되지 않을 때 무엇부터 확인할까

Kafka에서 메시지는 생산되는데 소비되지 않을 때 가장 먼저 물어야 할 질문은 “offset reset을 해야 하나?”가 아닙니다. “이 consumer group이 실제로 partition을 할당받고 polling을 하면서 offset을 기대한 방식으로 앞으로 보내고 있는가?”가 더 중요합니다. 많은 incident가 offset 문제처럼 보여도 실제로는 assignment, poll loop, rebalance churn 문제인 경우가 많습니다.

이 글은 가장 빠른 점검 순서부터 갑니다. group 상태가 건강한지, consumer가 partition을 할당받는지, consumer loop가 살아 있기만 한 채 실제 polling은 안 하는 건 아닌지부터 확인합니다.

consumer group이 실제로 동작 중인지 먼저 보세요

실무에서 messages not consumed는 보통 아래 중 하나입니다.

어떤 consumer도 partition을 할당받지 못함
consumer group이 불안정함
consumer는 살아 있지만 polling을 하지 않음
offset 위치가 운영자가 생각한 것과 다름

그래서 애플리케이션 로그보다 group 상태를 먼저 보는 편이 훨씬 빠를 때가 많습니다.

partition assignment를 확인하세요

Kafka consumer는 partition을 할당받아야 실제 일을 합니다.

메시지는 생산되는데 consumer가 아무것도 못 본다면 먼저 아래를 확인해야 합니다.

topic이 맞는가
group에 active member가 있는가
그 member들이 partition을 할당받고 있는가
관련 partition을 다른 member가 이미 들고 있어 이 consumer가 idle 상태는 아닌가

partition assignment가 없으면 프로세스가 살아 있어도 실질적으로는 아무 일도 못 합니다.

offset보다 poll 동작을 먼저 보세요

Kafka consumer 설정 문서에서 poll()은 consumer lifecycle의 중심입니다.

그래서 멈춘 consumer는 보통 아래 패턴 중 하나로 보입니다.

group에는 들어가지만 poll을 멈춤
poll 간격이 너무 길어 rebalance가 발생함
downstream 처리에 너무 오래 묶임
commit 전에 실패해서 offset progress가 기대와 다름

group이 불안정해 보인다면 Kafka Consumer Lag Increasing가 가장 직접적인 다음 글입니다.

다른 broker에서의 유사 증상과 비교해보고 싶다면 RabbitMQ Consumers Not Receiving Messages도 좋은 비교점입니다.

offset은 중요하지만 전부는 아닙니다

offset은 중요하지만 그것만으로 상태가 설명되지는 않습니다.

흔한 경우는 아래와 같습니다.

consumer가 기대한 레코드보다 이미 앞으로 가 있음
auto.offset.reset을 잘못 이해하고 있음
다른 consumer group은 읽고 있지만 이 group은 아님
partial work 뒤 commit이 일어나서 레코드를 다시 읽지 않음

즉 메시지가 존재한다와 이 consumer가 지금 그 메시지를 읽는다는 같은 말이 아닙니다.

흔한 원인

1. partition assignment가 없음

group이 비어 있거나 불안정하거나, 다른 곳에 할당되어 있습니다.

2. poll loop가 앞으로 나가지 않음

프로세스는 떠 있지만 active consumer처럼 동작하지 않습니다.

3. offset 기대치가 다름

group의 현재 위치가 운영자의 기대와 다릅니다.

4. rebalance가 진전을 자꾸 끊음

유효한 소비 작업이 반복적으로 중단됩니다.

실전 점검 순서

topic에 레코드가 실제로 들어오는지 확인
consumer group membership과 assignment 확인
consumer loop가 polling 하는지 확인
offset 위치와 commit 동작 확인
rebalance 빈도와 처리 latency 확인

이 순서가 offset reset부터 하는 것보다 훨씬 설명력이 좋습니다.

초반 분기에 좋은 shortcut

producer는 active한데 한 group만 아무것도 못 본다면 이렇게 갈라보세요.

member가 없거나 assignment가 없다: group state부터
member는 있는데 offset이 안 움직인다: poll behavior부터
offset이 이미 많이 앞서 있다: offset expectation부터
assignment가 계속 바뀐다: rebalance churn부터

이 분기만으로도 모든 incident를 offset reset 문제로 착각하는 실수를 줄일 수 있습니다.

증상별 진입 힌트

producer는 쓰고 있는데 이 consumer group이 아무것도 못 읽는 것 같으면 여기서 시작하면 됩니다.
소비는 하는데 lag만 계속 늘면 lag 가이드를 먼저 보세요.

바로 확인할 명령

kafka-consumer-groups.sh --bootstrap-server <broker:9092> --group <group> --describe
kafka-consumer-groups.sh --bootstrap-server <broker:9092> --list
kafka-topics.sh --bootstrap-server <broker:9092> --describe --topic <topic>

이 명령으로 group 존재 여부, partition assignment, offset 이동 여부를 먼저 확인할 수 있습니다.

빈 group인지, assignment가 없는지, producer는 계속 쓰는데 current offset이 멈춰 있는지를 보세요.

FAQ

Q. producer는 정상인데 consumer는 왜 아무것도 못 보나요?

topic 생산, group assignment, offset 위치가 서로 다른 문제이기 때문입니다.

Q. offset reset부터 해야 하나요?

group 상태와 assignment가 맞는지 먼저 확인해야 합니다.

Q. 가장 먼저 무엇을 봐야 하나요?

group membership, partition assignment, poll 동작, 현재 offset 위치입니다.

먼저 읽어볼 가이드

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