The purpose of Describe Kafka Topic is to inspect how a Kafka topic is arranged inside the cluster. The command shows the topic partitions, the leader broker for each partition, the replica brokers, and the in-sync replica set. This is useful when you want to verify topic creation, check replication, or troubleshoot why a producer or consumer is not behaving as expected.

For creating a Kafka Topic, refer Create a Topic in Kafka Cluster.

Describe Kafka Topic Using kafka-topics.sh

In recent Kafka installations, topic administration commands are usually run with --bootstrap-server. Older ZooKeeper-based Kafka setups used --zookeeper. The output has the same purpose: it tells you how the topic is distributed across brokers.

Modern command with bootstrap server

Use the following command when your Kafka broker is reachable at localhost:9092.

</>
Copy
bin/kafka-topics.sh --bootstrap-server localhost:9092 --describe --topic my-topic

Replace my-topic with your topic name. If your broker is running on a different host or port, replace localhost:9092 with the correct bootstrap server address.

Topic: my-topic    TopicId: abc123    PartitionCount: 1    ReplicationFactor: 3    Configs:
    Topic: my-topic    Partition: 0    Leader: 1    Replicas: 1,2,0    Isr: 1,2,0

Legacy ZooKeeper command for older Kafka clusters

Consider there are three broker instances running on a local machine and to know which kafka broker is doing what with a kafka topic(say my-topic), run the following command

$ bin/kafka-topics.sh --describe --zookeeper localhost:2181 --topic my-topic

Replace my-topic with your topic name. And also, it is assumed that you are running kafka with default configuration (zookeeper running at 2181).

$ bin/kafka-topics.sh --describe --zookeeper localhost:2181 --topic my-topic
Topic:my-topic    PartitionCount:1 ReplicationFactor:3 Configs:
    Topic: my-topic    Partition: 0 Leader: 1 Replicas: 1,2,0 Isr: 1,2,0

Kafka Describe Topic Output Explained

The describe output should be read partition by partition. A topic can have one partition or many partitions. Each partition has one leader and zero or more follower replicas, depending on the replication factor configured for the topic.

Topic name, partition count, and replication factor

Topic: my-topic is the topic that was described. PartitionCount: 1 means the topic currently has one partition. ReplicationFactor: 3 means Kafka stores three copies of each partition log across brokers.

Partition count affects parallelism because consumers in a consumer group read topic partitions. Replication factor affects fault tolerance because replicas allow the cluster to keep a copy of partition data on more than one broker.

Leader broker for a Kafka topic partition

Leader: 1 meaning broker instance 1 is responsible for all reads and writes for the given partition. Reads and Writes are done by Kafka Consumers and Kafka Producers respectively.

If the topic has multiple partitions, the describe output will show one line for each partition. Different partitions of the same topic may have different leader brokers. This helps Kafka spread traffic across the cluster.

Replica brokers listed in Kafka topic describe output

Replicas: 1,2,0 meaning broker instances 0, 1 and 2 are acting as nodes that replicate the log irrespective of one being a leader.

The first broker in this list is often the preferred replica for that partition. Kafka keeps replicas so that a partition can continue to exist even when a broker is unavailable, as long as the cluster still has a usable in-sync replica.

ISR in Kafka describe topic command

Isr: 1,2,0 meaning broker instances 1, 2 and 0 are in-sync replicas.

ISR stands for in-sync replicas. These replicas are sufficiently caught up with the leader. When the ISR list has fewer brokers than the replica list, it usually means one or more replicas are lagging or unavailable. That is an important signal to check broker health, network connectivity, disk usage, and replication lag.

PartitionCount:1 and ReplicationFactor:3 are the details used while creating the topic.

Describe All Kafka Topics in a Cluster

If you omit --topic, Kafka describes all topics visible to the command. This is helpful for a quick cluster-level check, but the output can become long in clusters with many topics.

</>
Copy
bin/kafka-topics.sh --bootstrap-server localhost:9092 --describe

To list topic names first and then describe only the topic you need, run:

</>
Copy
bin/kafka-topics.sh --bootstrap-server localhost:9092 --list
bin/kafka-topics.sh --bootstrap-server localhost:9092 --describe --topic my-topic

Kafka Topic With Multiple Partitions Describe Example

A topic with more than one partition produces multiple partition lines. In the following example, the topic has three partitions and a replication factor of three.

Topic: orders    PartitionCount: 3    ReplicationFactor: 3    Configs:
    Topic: orders    Partition: 0    Leader: 1    Replicas: 1,2,0    Isr: 1,2,0
    Topic: orders    Partition: 1    Leader: 2    Replicas: 2,0,1    Isr: 2,0,1
    Topic: orders    Partition: 2    Leader: 0    Replicas: 0,1,2    Isr: 0,1,2

This output shows that leaders are distributed across brokers 1, 2, and 0. That is generally healthier than all partitions being led by the same broker, because read and write load is not concentrated on one broker.

Common Checks After Running Kafka Describe Topic

  • Check whether the topic exists: If the command says the topic is not present, confirm the topic name and the bootstrap server.
  • Check partition count: Confirm that the partition count matches the expected consumer parallelism.
  • Check replication factor: Make sure the replication factor is suitable for the number of brokers in the cluster.
  • Check leader distribution: If many partitions have the same leader, one broker may be handling more traffic than others.
  • Check ISR against replicas: If the ISR list is smaller than the replica list, investigate broker availability or replication lag.

Kafka Topic Describe Command Troubleshooting

If the describe command fails, first check whether the broker address is correct. For local development, localhost:9092 is common, but containerized Kafka setups may expose a different listener address.

If you see authorization errors, the Kafka cluster may require ACL permissions for topic description. In secured clusters, your client configuration may also need SSL or SASL properties.

</>
Copy
bin/kafka-topics.sh \
  --bootstrap-server localhost:9092 \
  --command-config client.properties \
  --describe \
  --topic my-topic

In this command, client.properties contains the security settings required by your Kafka cluster.

Kafka Describe Topic Editorial QA Checklist

  • The command uses --bootstrap-server for current Kafka usage and mentions --zookeeper only for legacy clusters.
  • The tutorial explains Leader, Replicas, Isr, PartitionCount, and ReplicationFactor separately.
  • The examples make it clear that leader and ISR values are broker IDs, not topic IDs or partition IDs.
  • The troubleshooting section covers missing topics, incorrect broker addresses, and secured clusters.
  • The tutorial links readers to related Kafka producer, consumer, and topic creation examples where those steps are needed.

Now Kafka Producers may send messages to the Kafka topic, my-topic and Kafka Consumers may subscribe to the Kafka Topic.

FAQs on Kafka Describe Topic

What is Kafka topic in simple words?

A Kafka topic is a named stream or category of records. Producers write records to a topic, and consumers read records from that topic. Internally, Kafka stores a topic as one or more partitions.

How do I define a Kafka topic before describing it?

A Kafka topic is usually defined by its name, partition count, replication factor, and optional topic-level configuration. After creating it, use the describe command to confirm that Kafka created the topic with the expected partition and replica layout.

What does Leader mean in Kafka describe topic output?

Leader is the broker currently responsible for reads and writes for a specific partition. Each partition has one leader at a time, while the other replicas follow that leader.

What is the difference between Replicas and Isr in Kafka?

Replicas are the brokers assigned to store copies of a partition. Isr, or in-sync replicas, are the replicas that are currently caught up with the leader. If some replicas are missing from Isr, they may be lagging or unavailable.

Can I describe multiple Kafka topics with one command?

Yes. You can omit the --topic option to describe all topics in the cluster. For large clusters, it is usually easier to list topics first and then describe only the topic you want to inspect.

Conclusion

In this Apache Kafka Tutorial – Describe Kafka Topic, we have learnt to check Kafka Broker Instance that is acting as leader for a Kafka Topic, and the Broker Instances acting as replicas and in-sync replicas for the Kafka Topic. We also looked at the modern --bootstrap-server command, legacy ZooKeeper usage, multi-partition output, and practical checks for topic troubleshooting.