Introduction

RecordMetadata is the object Kafka gives you after a producer send has been acknowledged successfully. Its main purpose is to tell you where the record ended up, including topic, partition, offset, and timestamp, so it is mostly useful on the producer side for logging, auditing, routing decisions, and confirmation of successful writes.

What RecordMetadata Contains

After a successful producer send, the metadata tells you:

• the topic
• the partition chosen for the record
• the offset assigned inside that partition
• the broker-side timestamp

That means RecordMetadata answers questions like:

• which partition did my record go to
• what offset was assigned
• did the write actually succeed

It does not replace consumer offset tracking, and it is not something a consumer normally uses.

Synchronous Example

The simplest way to see RecordMetadata is to call .get() on the future returned by send():

1import org.apache.kafka.clients.producer.KafkaProducer;
2import org.apache.kafka.clients.producer.ProducerRecord;
3import org.apache.kafka.clients.producer.RecordMetadata;
4
5import java.util.Properties;
6
7public class ProducerWithMetadata {
8    public static void main(String[] args) throws Exception {
9        Properties props = new Properties();
10        props.put("bootstrap.servers", "localhost:9092");
11        props.put("key.serializer", "org.apache.kafka.common.serialization.StringSerializer");
12        props.put("value.serializer", "org.apache.kafka.common.serialization.StringSerializer");
13
14        try (KafkaProducer<String, String> producer = new KafkaProducer<>(props)) {
15            ProducerRecord<String, String> record =
16                new ProducerRecord<>("orders", "customer-1", "created");
17
18            RecordMetadata metadata = producer.send(record).get();
19
20            System.out.println("topic     = " + metadata.topic());
21            System.out.println("partition = " + metadata.partition());
22            System.out.println("offset    = " + metadata.offset());
23            System.out.println("timestamp = " + metadata.timestamp());
24        }
25    }
26}

This is fine for demos or low-throughput tools, but .get() blocks the calling thread.

Asynchronous Callback Example

In real producer code, a callback is often better:

1producer.send(record, (metadata, exception) -> {
2    if (exception != null) {
3        exception.printStackTrace();
4        return;
5    }
6
7    System.out.printf(
8        "Stored in %s-%d at offset %d%n",
9        metadata.topic(),
10        metadata.partition(),
11        metadata.offset()
12    );
13});

This keeps the send path asynchronous while still giving you access to the metadata after acknowledgement.

When RecordMetadata Is Useful

Typical producer-side use cases include:

• debug logging for message routing
• storing the produced offset for audit or trace correlation
• verifying partitioning behavior
• measuring latency between send attempt and broker acknowledgement

For example, if your producer keying logic is important, inspecting metadata.partition() helps confirm records are landing where you expect.

What It Is Not For

RecordMetadata is not how you track consumer progress, and it is not a guarantee that downstream consumers have seen the record. It only tells you the broker has accepted the write according to the producer's acknowledgement settings.

That distinction matters:

• producer metadata tells you where the write landed
• consumer offsets tell you what readers have processed

Those are different concerns.

Acknowledgements Still Matter

The meaning of successful metadata depends on producer configuration such as acks. If durability matters, you should understand the relationship between:

• 'acks'
• retries
• idempotence
• broker replication

RecordMetadata is useful, but it is only one part of reliable producer design.

Common Pitfalls

• Calling .get() in a hot path and accidentally making the producer effectively synchronous.
• Treating producer metadata as if it reflects consumer progress.
• Ignoring errors and reading metadata only on the success path.
• Assuming offset values are globally ordered across all partitions.
• Forgetting that the assigned partition is exactly the clue you need when debugging key-based routing.

Summary

• 'RecordMetadata tells a Kafka producer where a successfully written record was stored.'
• It includes topic, partition, offset, and timestamp.
• Use callbacks for high-throughput producer code instead of blocking on .get().
• It is useful for logging, auditing, and confirming partition placement.
• It does not replace consumer offset management or end-to-end delivery tracking.