kafka-topics.sh --list / --describe: Список топиков, детали партиций, проблемные реплики

Базовый синтаксис

Команда kafka-topics.sh — ваш основной инструмент для инспекции топиков. Без флагов она ничего не сделает, поэтому всегда используйте --list для перечисления или --describe для деталей.

Чтобы увидеть все топики в кластере, выполните:

kafka-topics.sh --bootstrap-server kafka-broker-1:9092 --list

Эта команда подключится к брокеру и вернет простой список имен топиков. Флаг --bootstrap-server обязателен — это точка входа в кластер.

Для получения детальной информации о конкретном топике используйте --describe вместе с --topic:

kafka-topics.sh --bootstrap-server kafka-broker-1:9092 --describe --topic orders-in

Вывод покажет количество партиций, лидеров, реплик и их расположение. Это основа для диагностики.

Полезные флаги

--topic — сужает область запроса. Когда в кластере тысячи топиков, а вам нужна информация об одном-двух, это экономит время и ресурсы.

kafka-topics.sh --bootstrap-server kafka-broker-1:9092 --describe --topic orders-in,logs-app

--under-replicated-partitions (--unreplicated) — ключевой флаг для мониторинга здоровья. Он фильтрует вывод, оставляя только партиции, где число актуальных реплик (Isr) меньше заданного фактора репликации (Replication Factor).

kafka-topics.sh --bootstrap-server kafka-broker-1:9092 --describe --under-replicated-partitions

Если команда вернула пустой вывод — это хороший знак. Если нет — начались проблемы с репликацией (сетевые проблемы, падение брокеров).

Типичные сценарии

1. Быстрая проверка перед деплоем конфигурации. Перед применением изменений в коде конфигурации топиков через IaC (например, Terraform с модулем Confluent), убедитесь, что целевые топики существуют и их параметры совпадают с ожидаемыми.

kafka-topics.sh --bootstrap-server kafka-broker-1:9092 --describe --topic payment-events | grep -E "PartitionCount|ReplicationFactor"

2. Поиск проблем после алерта. При срабатывании алерта “UnderReplicatedPartitions > 0” нужно быстро локализовать проблему. Эта команда покажет, какие именно топики и партиции затронуты, и на каких брокерах находятся их реплики.

kafka-topics.sh --bootstrap-server kafka-broker-1:9092 --describe --under-replicated-partitions | head -20

Затем по выводу смотрите, не совпадают ли все проблемные реплики с одним конкретным брокером — это сразу сужает круг расследования.

Частые ошибки

Забыть указать --bootstrap-server. Утилита не будет использовать переменные окружения из Kafka Client и завершится с ошибкой. Всегда явно указывайте брокер.

Путаница между --list и --describe без --topic. Команда kafka-topics.sh --describe (без --topic) выведет детальную информацию по всем топикам в кластере. На больших кластерах вывод будет огромным и может “подвесить” терминал. Всегда уточняйте топик или используйте grep для фильтрации.