Introduction

Kafka headers are optional key-value pairs attached to a record alongside the key and value. They are useful for metadata such as trace IDs, schema hints, and routing flags, and you can inspect them either from command-line tools or in client code.

Understand What a Header Looks Like

A Kafka record can contain:

• a topic
• a partition and offset
• a key
• a value
• zero or more headers

Each header has a key and a value stored as bytes. That last detail matters because when you “view” headers, tools often show raw bytes or strings decoded with whatever serializer you choose. A header is not automatically human-readable.

View Headers with the Console Consumer

The quickest option for debugging is the console consumer with header printing enabled.

1kafka-console-consumer \
2  --bootstrap-server localhost:9092 \
3  --topic orders \
4  --from-beginning \
5  --property print.headers=true \
6  --property print.key=true \
7  --property key.separator=' | '

That prints each record together with its headers when the tool and broker version support headers. If you are only looking for one message path, remove --from-beginning and consume just the live stream instead.

This is the fastest way to answer “did the producer send the header at all?” before moving on to code-level debugging.

Inspect Headers in Java Consumer Code

For application debugging or tests, reading headers programmatically is often clearer.

1import java.nio.charset.StandardCharsets;
2import java.time.Duration;
3import java.util.Collections;
4import java.util.Properties;
5import org.apache.kafka.clients.consumer.ConsumerConfig;
6import org.apache.kafka.clients.consumer.ConsumerRecord;
7import org.apache.kafka.clients.consumer.ConsumerRecords;
8import org.apache.kafka.clients.consumer.KafkaConsumer;
9import org.apache.kafka.common.header.Header;
10import org.apache.kafka.common.serialization.StringDeserializer;
11
12public class HeaderReader {
13    public static void main(String[] args) {
14        Properties props = new Properties();
15        props.put(ConsumerConfig.BOOTSTRAP_SERVERS_CONFIG, "localhost:9092");
16        props.put(ConsumerConfig.GROUP_ID_CONFIG, "header-reader");
17        props.put(ConsumerConfig.KEY_DESERIALIZER_CLASS_CONFIG, StringDeserializer.class.getName());
18        props.put(ConsumerConfig.VALUE_DESERIALIZER_CLASS_CONFIG, StringDeserializer.class.getName());
19        props.put(ConsumerConfig.AUTO_OFFSET_RESET_CONFIG, "earliest");
20
21        try (KafkaConsumer<String, String> consumer = new KafkaConsumer<>(props)) {
22            consumer.subscribe(Collections.singletonList("orders"));
23
24            ConsumerRecords<String, String> records = consumer.poll(Duration.ofSeconds(2));
25            for (ConsumerRecord<String, String> record : records) {
26                for (Header header : record.headers()) {
27                    String value = new String(header.value(), StandardCharsets.UTF_8);
28                    System.out.println(header.key() + " = " + value);
29                }
30            }
31        }
32    }
33}

This is more flexible than the console tool because you can decode bytes exactly the way your application expects.

Use a Diagnostic Tool When You Need Raw Visibility

If you want a quick external check without writing code, a CLI such as kcat can be useful in environments where it is available.

kcat -b localhost:9092 -t orders -C -f 'Headers: %h\nKey: %k\nValue: %s\n\n'

That kind of tool is convenient when you need to compare producer output, broker behavior, and consumer expectations from outside the application. It is not required, but it can shorten debugging sessions considerably.

Use Headers for Diagnostics, Not Hidden Payloads

Headers work well for compact metadata such as:

• correlation IDs
• message type tags
• tenant or region markers
• content type hints

They are not a good substitute for the payload itself. If you start hiding large business data in headers, observability gets worse and consumers become harder to reason about.

A useful debugging workflow is to log key, partition, offset, and selected headers together so message tracing stays consistent across services.

Common Pitfalls

• Expecting headers to display clearly when the values are raw bytes that need decoding.
• Forgetting to enable print.headers=true when using the console consumer.
• Looking for headers on very old records or systems that predate Kafka header support.
• Storing large or business-critical payload data in headers instead of in the record value.
• Assuming a missing printed header means the broker removed it when the real issue is producer or consumer serialization.

Summary

• Kafka headers are byte-based metadata attached to individual records.
• The console consumer can show them with print.headers=true.
• Client code gives you more control over decoding and debugging.
• External tools can help when you want broker-side visibility without changing code.
• Headers are best for lightweight metadata, not for replacing the payload.