Introduction

To fetch data from a Kafka ConsumerRecord, call its accessor methods such as key(), value(), topic(), partition(), and offset(). The important distinction is whether you mean a field on the record metadata itself or a field inside the record's payload, because those are two different kinds of access.

Access the Built-In Record Fields

Kafka's ConsumerRecord already exposes the main metadata fields through methods.

1import java.time.Duration;
2import java.util.Collections;
3import java.util.Properties;
4import org.apache.kafka.clients.consumer.ConsumerRecord;
5import org.apache.kafka.clients.consumer.ConsumerRecords;
6import org.apache.kafka.clients.consumer.KafkaConsumer;
7
8public class SimpleConsumer {
9    public static void main(String[] args) {
10        Properties props = new Properties();
11        props.put("bootstrap.servers", "localhost:9092");
12        props.put("group.id", "test-group");
13        props.put("key.deserializer", "org.apache.kafka.common.serialization.StringDeserializer");
14        props.put("value.deserializer", "org.apache.kafka.common.serialization.StringDeserializer");
15
16        try (KafkaConsumer<String, String> consumer = new KafkaConsumer<>(props)) {
17            consumer.subscribe(Collections.singletonList("my-topic"));
18
19            while (true) {
20                ConsumerRecords<String, String> records = consumer.poll(Duration.ofMillis(500));
21                for (ConsumerRecord<String, String> record : records) {
22                    System.out.printf(
23                        "topic=%s partition=%d offset=%d key=%s value=%s%n",
24                        record.topic(),
25                        record.partition(),
26                        record.offset(),
27                        record.key(),
28                        record.value()
29                    );
30                }
31            }
32        }
33    }
34}

These methods fetch record metadata and the deserialized key and value, not fields inside a structured payload such as JSON or Avro.

Fetch a Field Inside the Value Payload

If the record value itself contains structured data, you must parse the value after calling record.value().

For a JSON payload:

1import com.fasterxml.jackson.databind.JsonNode;
2import com.fasterxml.jackson.databind.ObjectMapper;
3
4ObjectMapper mapper = new ObjectMapper();
5
6String payload = record.value();
7JsonNode root = mapper.readTree(payload);
8String customerId = root.get("customerId").asText();
9
10System.out.println(customerId);

So the flow becomes:

1. fetch the Kafka value with record.value()
2. parse that value according to its serialization format
3. read the field from the parsed structure

Headers Are a Separate Part of the Record

Kafka records can also carry headers. Those are not the same thing as key or value fields.

record.headers().forEach(header -> {
    System.out.println(header.key());
});

If you know the header name:

1var header = record.headers().lastHeader("trace-id");
2if (header != null) {
3    String traceId = new String(header.value());
4    System.out.println(traceId);
5}

Headers are often used for tracing, schema hints, or routing metadata.

Know Your Deserializer Types

What you can "fetch" depends heavily on the configured deserializers. With StringDeserializer, record.value() returns a String. With a custom Avro or JSON deserializer, record.value() may already be a domain object.

For example, if you consume typed objects:

ConsumerRecord<String, Order> record = ...;
Order order = record.value();
System.out.println(order.getCustomerId());

In that design, fetching a field is just ordinary Java object access after deserialization.

Handle Nulls Deliberately

Kafka records can have null keys or null values, depending on the producer and topic semantics. That means field access should sometimes be guarded instead of assumed.

1String key = record.key();
2String value = record.value();
3
4if (value != null) {
5    System.out.println(value);
6}

This matters especially for tombstone records in compacted topics, where a null value is meaningful rather than accidental.

Other Useful Record Metadata

Besides key and value, ConsumerRecord exposes metadata that is often useful in debugging and processing logic:

• 'record.timestamp()'
• 'record.serializedKeySize()'
• 'record.serializedValueSize()'
• 'record.headers()'

That information can help with audit logging, payload diagnostics, and throughput analysis.

Common Pitfalls

The most common mistake is trying to read a business field directly from ConsumerRecord when the field actually lives inside the serialized value payload. Another is forgetting that the meaning of record.value() depends on the configured deserializer. Developers also treat headers, key, and payload as if they were one flat structure, which makes debugging harder because Kafka keeps them separate by design.

Summary

• Use record.key(), record.value(), record.topic(), record.partition(), and record.offset() for built-in ConsumerRecord fields.
• Parse record.value() if the actual business field is inside JSON, Avro, or another payload format.
• Use record.headers() for Kafka headers.
• Deserializer choice determines what type record.value() returns.
• Distinguish clearly between Kafka metadata fields and fields inside the message payload.