Implementation:Apache Kafka KafkaAdminClient DescribeTopics

Knowledge Sources	Apache Kafka
Domains	Administration, Monitoring
Last Updated	2026-02-09 12:00 GMT

Overview

Concrete tool for describing Kafka topic metadata via the AdminClient API provided by KafkaAdminClient.

Description

The KafkaAdminClient.describeTopics method retrieves detailed topic metadata. It supports querying by topic name or topic ID. For topic names, it uses either the DescribeTopicPartitions API (newer) or falls back to MetadataRequest. Results include partition information (leader, replicas, ISR) and topic-level properties.

Usage

Use via kafka-topics.sh --describe or programmatically through the Admin interface.

Code Reference

Source Location

• Repository: Apache Kafka
• File: clients/src/main/java/org/apache/kafka/clients/admin/KafkaAdminClient.java
• Lines: L2136-2200

Signature

public DescribeTopicsResult describeTopics(
    final TopicCollection topics,
    DescribeTopicsOptions options
)

Import

import org.apache.kafka.clients.admin.Admin;
import org.apache.kafka.clients.admin.TopicDescription;
import org.apache.kafka.clients.admin.DescribeTopicsResult;
import org.apache.kafka.common.TopicCollection;

I/O Contract

Inputs

Name	Type	Required	Description
topics	TopicCollection	Yes	TopicNameCollection or TopicIdCollection to describe
options	DescribeTopicsOptions	No	Options for the describe request

Outputs

Name	Type	Description
DescribeTopicsResult	DescribeTopicsResult	Contains KafkaFuture<TopicDescription> per topic with partitions, leader, replicas, ISR

Usage Examples

Describe Topic via CLI

bin/kafka-topics.sh --bootstrap-server localhost:9092 --describe --topic my-topic
bin/kafka-topics.sh --bootstrap-server localhost:9092 --describe --under-replicated-partitions

Describe Topic Programmatically

try (Admin admin = Admin.create(props)) {
    TopicDescription desc = admin.describeTopics(
        TopicCollection.ofTopicNames(Set.of("my-topic"))
    ).topicNameValues().get("my-topic").get();

    desc.partitions().forEach(p ->
        System.out.printf("Partition %d: leader=%d, replicas=%s, isr=%s%n",
            p.partition(), p.leader().id(), p.replicas(), p.isr()));
}

Related Pages

Implements Principle

• Principle:Apache_Kafka_Topic_Description