Consumer API basics in Kafka - Deep Dive

Overview - Consumer API basics

What is it?

The Consumer API in Kafka is a way for applications to read messages from Kafka topics. It allows programs to subscribe to one or more topics and receive data streams in real time. Consumers manage their position in the stream, called offsets, to keep track of which messages they have processed. This API is essential for building systems that react to data as it arrives.

Why it matters

Without the Consumer API, applications would have no structured way to get data from Kafka topics, making real-time data processing impossible. It solves the problem of efficiently and reliably reading continuous streams of data. Without it, systems would struggle to keep up with fast data flows or risk losing messages, leading to outdated or incomplete information.

Where it fits

Before learning the Consumer API, you should understand Kafka basics like topics, partitions, and producers. After mastering the Consumer API, you can explore advanced topics like consumer groups, offset management, and stream processing frameworks that build on this foundation.

Mental Model

Core Idea

The Consumer API lets applications read and track their place in a continuous stream of messages from Kafka topics.

Think of it like...

Imagine a newspaper subscriber who receives daily papers (messages) and keeps a bookmark (offset) to know which page they last read, so they never miss or reread articles.

┌───────────────┐       ┌───────────────┐       ┌───────────────┐
│ Kafka Topic 1 │──────▶│ Consumer App  │──────▶│ Processed Data│
│ Partition 0   │       │ (reads stream)│       │ (business use)│
└───────────────┘       └───────────────┘       └───────────────┘
       ▲                      │
       │                      ▼
   Offsets tracked       Commits offsets
   per message batch    to remember position

Build-Up - 7 Steps

1

Foundation

What is a Kafka Consumer

Concept: Introduces the basic role of a Kafka consumer in reading messages.

A Kafka consumer is a program that connects to Kafka and reads messages from one or more topics. It listens for new messages and processes them as they arrive. Each message has an offset, which is a number that marks its position in the topic partition.

Result

You understand that a consumer reads messages and that each message has a unique position called an offset.

Understanding that consumers read messages sequentially and track offsets is the foundation for reliable data processing.

2

Foundation

Subscribing to Topics

Concept: Shows how consumers subscribe to topics to receive messages.

Consumers must subscribe to one or more topics to start receiving messages. This subscription tells Kafka which streams the consumer wants to read. The Consumer API provides methods to subscribe by topic name or pattern.

Result

The consumer begins receiving messages from the subscribed topics.

Knowing how to subscribe is key to controlling what data your application processes.

3

Intermediate

Understanding Offsets and Their Management

🤔Before reading on: do you think Kafka automatically remembers which messages your consumer has read, or must the consumer manage this?

Concept: Explains how consumers track their reading position using offsets and the importance of managing them.

Each message in a Kafka partition has an offset number. Consumers keep track of the last offset they processed to avoid reading the same message twice or missing messages. The Consumer API allows committing offsets automatically or manually to Kafka or external storage.

Result

Consumers can resume reading from the correct position after restarts or failures.

Knowing offset management prevents data loss or duplication, which is critical for accurate processing.

4

Intermediate

Consumer Groups and Load Balancing

🤔Before reading on: do you think multiple consumers can read the same partition simultaneously, or is each partition read by only one consumer in a group?

Concept: Introduces consumer groups that allow multiple consumers to share the work of reading partitions.

Consumers can join a group identified by a group ID. Kafka divides partitions among consumers in the same group so each partition is read by only one consumer. This balances load and allows scaling. The Consumer API manages group membership and partition assignment automatically.

Result

Multiple consumers can work together to process data faster without overlap.

Understanding consumer groups is essential for building scalable and fault-tolerant data processing.

5

Intermediate

Polling for Messages

Concept: Shows how consumers fetch messages using the poll method.

Consumers use a poll() method to request messages from Kafka. This method waits for new data and returns a batch of messages. Polling must be done regularly to keep the consumer alive and maintain group membership.

Result

The consumer receives batches of messages to process.

Knowing how polling works helps avoid common issues like consumer timeouts or missed messages.

6

Advanced

Manual Offset Control for Precise Processing

🤔Before reading on: do you think automatic offset commits always guarantee no message loss or duplication?

Concept: Explains how manual offset commits give control to ensure messages are processed before marking them done.

Automatic offset commits can cause messages to be marked as read before processing completes, risking data loss if the consumer crashes. Manual commits let the application commit offsets only after successful processing, ensuring exactly-once or at-least-once delivery semantics.

Result

More reliable message processing with control over when offsets are saved.

Understanding manual commits is key to building robust systems that handle failures gracefully.

7

Expert

Rebalancing and Its Impact on Consumers

🤔Before reading on: do you think consumer rebalancing happens instantly and without any message processing interruption?

Concept: Describes how Kafka redistributes partitions among consumers when group membership changes and the challenges it creates.

When consumers join or leave a group, Kafka triggers a rebalance to reassign partitions. During this time, consumers stop polling and may lose their current processing state. Handling rebalances properly requires saving offsets and managing state to avoid duplicate or missed messages.

Result

Consumers can handle group changes without data loss or downtime.

Knowing the rebalance process helps prevent subtle bugs and downtime in production systems.

Under the Hood

The Consumer API works by maintaining a TCP connection to Kafka brokers and sending fetch requests for assigned partitions. Kafka brokers respond with batches of messages starting from the requested offset. The consumer tracks offsets locally and can commit them back to Kafka's internal __consumer_offsets topic. Group coordination is managed by a group coordinator broker that handles membership and partition assignments using a protocol called the group coordinator protocol.

Why designed this way?

Kafka's Consumer API was designed to handle high-throughput, distributed data streams with fault tolerance. Using offset tracking allows consumers to resume exactly where they left off. The group coordinator protocol enables scalable load balancing among consumers. This design avoids centralized bottlenecks and supports flexible consumption patterns.

┌───────────────┐       ┌───────────────┐       ┌───────────────┐
│ Kafka Broker  │◀──────│ Consumer API  │──────▶│ Application   │
│ (stores data) │ fetch │ (fetches data)│ process│ (business logic)
└───────────────┘       └───────────────┘       └───────────────┘
       ▲                      │
       │                      ▼
  __consumer_offsets       Commit offsets
  topic stores offsets     to broker
       │
       ▼
┌───────────────┐
│ Group         │
│ Coordinator   │
│ (manages     │
│ consumer group│
└───────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Does Kafka guarantee that each message is delivered exactly once to consumers by default? Commit to yes or no.

Common Belief: Kafka ensures that each message is delivered exactly once to consumers automatically.

Reality: Kafka guarantees at-least-once delivery by default; consumers may receive duplicates unless they implement idempotent processing or manual offset control.

Why it matters: Assuming exactly-once delivery can lead to data corruption or duplicate processing in applications.

Quick: Can multiple consumers in the same group read the same partition at the same time? Commit to yes or no.

Common Belief: Multiple consumers in the same group can read the same partition simultaneously to speed up processing.

Reality: Each partition is assigned to only one consumer in a group at a time to avoid duplicate processing.

Why it matters: Misunderstanding this can cause confusion about how load balancing works and lead to incorrect scaling strategies.

Quick: Does committing offsets automatically mean messages are fully processed? Commit to yes or no.

Common Belief: Automatic offset commits mean messages are processed and safe to forget.

Reality: Automatic commits may happen before processing finishes, risking message loss if the consumer crashes.

Why it matters: Relying on automatic commits without manual control can cause data loss in failure scenarios.

Quick: Does consumer rebalancing happen instantly without affecting message processing? Commit to yes or no.

Common Belief: Rebalancing is a quick background task that does not interrupt consumers.

Reality: Rebalancing pauses consumers and can cause temporary unavailability or duplicate processing if not handled properly.

Why it matters: Ignoring rebalance effects can cause downtime or inconsistent data processing in production.

Expert Zone

1

Offset commits can be asynchronous or synchronous; choosing between them affects latency and reliability tradeoffs.

2

The choice of partition assignment strategy (range, round-robin, sticky) impacts load balancing and message ordering guarantees.

3

Handling rebalance callbacks properly is critical to avoid losing uncommitted offsets or processing duplicates.

When NOT to use

The Consumer API is not suitable when you need complex event processing or transformations; in such cases, Kafka Streams or ksqlDB are better alternatives. Also, for very low-latency or exactly-once semantics, specialized frameworks or external transaction managers may be required.

Production Patterns

In production, consumers often run in groups across multiple servers for scalability. They use manual offset commits after processing batches to ensure reliability. Rebalance listeners handle state cleanup and offset commits to avoid duplicates. Monitoring consumer lag and health is standard practice to detect processing delays.

Connections

Publish-Subscribe Messaging Pattern

The Consumer API implements the subscribe side of the pub-sub pattern.

Understanding pub-sub helps grasp why consumers subscribe to topics and how messages flow from producers to multiple consumers.

Checkpointing in Stream Processing

Offset commits in Kafka consumers are a form of checkpointing to save progress.

Knowing checkpointing concepts from stream processing clarifies why and when consumers commit offsets to avoid reprocessing.

Bookmarking in Reading Apps

Tracking offsets is like bookmarking your place in a book or article.

This cross-domain idea helps understand why consumers must remember their position to continue reading without missing or repeating content.

Common Pitfalls

#1 Relying on automatic offset commits without ensuring message processing is complete.

Wrong approach:

consumerConfig.put("enable.auto.commit", "true");
// process messages
// no manual commit

Correct approach:

consumerConfig.put("enable.auto.commit", "false");
// process messages
consumer.commitSync();

Root cause:

Misunderstanding that automatic commits happen independently of processing completion.

#2 Not handling consumer rebalances, causing lost offsets or duplicate processing.

Wrong approach:

// No rebalance listener
consumer.subscribe(topics);

Correct approach:

consumer.subscribe(topics, new ConsumerRebalanceListener() {
public void onPartitionsRevoked(Collection partitions) {
consumer.commitSync();
}
public void onPartitionsAssigned(Collection partitions) {}
});

Root cause:

Ignoring the rebalance lifecycle and its impact on offset management.

#3 Multiple consumers in the same group subscribing to the same partition, expecting parallel reads.

Wrong approach:

Two consumers with same group ID manually assigned to same partition.

Correct approach:

Let Kafka assign partitions automatically or ensure each partition is assigned to only one consumer.

Root cause:

Misunderstanding how Kafka enforces partition ownership within consumer groups.

Key Takeaways

Kafka's Consumer API allows applications to read messages from topics while tracking their position using offsets.

Consumers subscribe to topics and use polling to fetch messages in batches, maintaining group membership through regular polls.

Offset management is crucial to avoid message loss or duplication; manual commits provide precise control over processing state.

Consumer groups enable load balancing by assigning partitions exclusively to one consumer in the group at a time.

Handling rebalances properly is essential to maintain processing continuity and data consistency in production.

Practice

1. What is the primary purpose of the Kafka Consumer API?

easy

A. To send messages to Kafka topics

B. To delete Kafka topics

C. To create Kafka topics

D. To read messages from Kafka topics

Solution

1. Step 1: Understand Kafka Consumer API role

   The Consumer API is designed to read or consume messages from Kafka topics.

2. Step 2: Differentiate from Producer API

   The Producer API sends messages, while Consumer API reads them.

3. Final Answer:

   To read messages from Kafka topics -> Option D

4. Quick Check:

   Consumer API = Read messages [OK]

Hint: Consumer API reads messages, Producer API sends messages [OK]

Common Mistakes:

• Confusing Consumer API with Producer API
• Thinking Consumer API creates or deletes topics
• Mixing up reading and writing operations

2. Which of the following is the correct way to create a Kafka consumer in Java?

easy

A. new KafkaProducer<>(properties);

B. new KafkaConsumer<>(properties);

C. KafkaConsumer.create(properties);

D. KafkaConsumer.start(properties);

Solution

1. Step 1: Recall Kafka consumer instantiation syntax

   Kafka consumer is created by calling the constructor: new KafkaConsumer<>(properties);

2. Step 2: Eliminate incorrect options

   Producer is for sending messages, so new KafkaProducer<>(properties); is wrong. Options C and D are not valid KafkaConsumer methods.

3. Final Answer:

   new KafkaConsumer<>(properties); -> Option B

4. Quick Check:

   Constructor new KafkaConsumer<>(props) = Correct [OK]

Hint: Use new KafkaConsumer<>(props) to create consumer [OK]

Common Mistakes:

• Using KafkaProducer instead of KafkaConsumer
• Calling non-existent static methods
• Confusing method names for creation

3. Given the following Java code snippet, what will be the output if the topic has two messages "Hello" and "World"?

Properties props = new Properties();
props.put("bootstrap.servers", "localhost:9092");
props.put("group.id", "test-group");
props.put("key.deserializer", "org.apache.kafka.common.serialization.StringDeserializer");
props.put("value.deserializer", "org.apache.kafka.common.serialization.StringDeserializer");
KafkaConsumer consumer = new KafkaConsumer<>(props);
consumer.subscribe(Collections.singletonList("my-topic"));
ConsumerRecords records = consumer.poll(Duration.ofMillis(1000));
for (ConsumerRecord record : records) {
    System.out.println(record.value());
}

medium

A. Compilation error

B. No output

C. Hello\nWorld

D. Runtime exception

Solution

1. Step 1: Understand consumer subscription and poll

   The consumer subscribes to "my-topic" and polls messages for 1 second.

2. Step 2: Process messages in the topic

   Since the topic has two messages "Hello" and "World", the poll will fetch both, and the loop prints each value.

3. Final Answer:

   Hello\nWorld -> Option C

4. Quick Check:

   poll() fetches messages = Hello and World printed [OK]

Hint: poll() fetches messages; loop prints each value [OK]

Common Mistakes:

• Assuming poll returns no messages immediately
• Confusing subscribe with assign
• Expecting compile or runtime errors without cause

4. Identify the error in this Kafka consumer code snippet:

Properties props = new Properties();
props.put("bootstrap.servers", "localhost:9092");
props.put("group.id", "group1");
props.put("key.deserializer", "StringDeserializer");
props.put("value.deserializer", "StringDeserializer");
KafkaConsumer consumer = new KafkaConsumer<>(props);
consumer.subscribe(List.of("topic1"));
ConsumerRecords records = consumer.poll(Duration.ofMillis(100));
for (ConsumerRecord record : records) {
    System.out.println(record.value());
}

medium

A. Deserializer class names are incomplete and will cause ClassNotFoundException

B. Missing call to consumer.close()

C. Incorrect subscription method used

D. poll() duration is too short and causes timeout

Solution

1. Step 1: Check deserializer configuration

   The deserializer class names must be fully qualified, e.g., "org.apache.kafka.common.serialization.StringDeserializer".

2. Step 2: Identify impact of incorrect class names

   Using "StringDeserializer" alone will cause ClassNotFoundException at runtime.

3. Final Answer:

   Deserializer class names are incomplete and will cause ClassNotFoundException -> Option A

4. Quick Check:

   Deserializer full class name required = Deserializer class names are incomplete and will cause ClassNotFoundException [OK]

Hint: Use full deserializer class names to avoid errors [OK]

Common Mistakes:

• Using short class names for deserializers
• Ignoring missing consumer.close() (not error here)
• Assuming poll duration causes errors

5. You want to process messages from multiple topics and commit offsets manually after processing. Which code snippet correctly sets up the Kafka consumer for this use case?

hard

A. props.put("enable.auto.commit", "false");
consumer.subscribe(Arrays.asList("topicA", "topicB"));
while (true) {
ConsumerRecords records = consumer.poll(Duration.ofMillis(1000));
for (ConsumerRecord record : records) {
process(record.value());
}
consumer.commitSync();
}

B. props.put("enable.auto.commit", "true");
consumer.subscribe(Collections.singletonList("topicA"));
while (true) {
ConsumerRecords records = consumer.poll(Duration.ofMillis(1000));
for (ConsumerRecord record : records) {
process(record.value());
}
}

C. props.put("enable.auto.commit", "false");
consumer.assign(Arrays.asList(new TopicPartition("topicA", 0)));
consumer.subscribe(Arrays.asList("topicB"));
while (true) {
ConsumerRecords records = consumer.poll(Duration.ofMillis(1000));
for (ConsumerRecord record : records) {
process(record.value());
}
consumer.commitAsync();
}

D. props.put("enable.auto.commit", "false");
consumer.subscribe(Arrays.asList("topicA", "topicB"));
while (true) {
ConsumerRecords records = consumer.poll(Duration.ofMillis(1000));
for (ConsumerRecord record : records) {
process(record.value());
}
}

Solution

1. Step 1: Disable auto commit for manual offset control

   Setting "enable.auto.commit" to "false" allows manual offset commits.

2. Step 2: Subscribe to multiple topics correctly

   Use consumer.subscribe(Arrays.asList("topicA", "topicB")) to listen to multiple topics.

3. Step 3: Commit offsets after processing

   Calling consumer.commitSync() after processing ensures offsets are saved manually.

4. Final Answer:

   Code snippet with manual commit, multiple topic subscription, and commitSync() -> Option A

5. Quick Check:

   Manual commit + multiple topics = props.put("enable.auto.commit", "false"); consumer.subscribe(Arrays.asList("topicA", "topicB")); while (true) { ConsumerRecords records = consumer.poll(Duration.ofMillis(1000)); for (ConsumerRecord record : records) { process(record.value()); } consumer.commitSync(); } [OK]

Hint: Disable auto commit and call commitSync() after processing [OK]

Common Mistakes:

• Using auto commit when manual commit is needed
• Mixing assign() and subscribe() incorrectly
• Forgetting to commit offsets after processing