47 
Содержание
- Что делает kafka-log-dirs.sh
- Синтаксис и основные флаги
- Шаг 1. Смотрим лог-директории всех брокеров
- Шаг 2. Фильтруем по топику и брокеру
- Шаг 3. Читаем JSON-вывод
- Шаг 4. Считаем суммарный размер топика
- Шаг 5. Мониторинг переназначения партиций через isFuture
- Шаг 6. Обнаружение офлайн-директорий
- Практический сценарий. Дисковый аудит перед балансировкой
- Альтернативы kafka-log-dirs.sh
- Что дальше
- Ссылки
- Все уроки курса
В уроке 15 мы разобрали kafka-configs.sh — утилиту для управления динамическими конфигурациями топиков, брокеров и квот. Там мы меняли retention.ms, max.message.bytes и другие параметры без перезапуска кластера. Но одно дело выставить срок хранения, другое — понять, сколько места реально занимают данные прямо сейчас.
Именно тут нужна kafka-log-dirs.sh. Она показывает, сколько байт занимает каждая партиция на каждом брокере, в каких директориях лежат логи и насколько реплики отстают от лидера. Это первый инструмент, который открывают при проблемах с диском или перед тем, как запустить переназначение партиций.
Если вы занимаетесь администрированием кластеров Kafka в продакшене, дисковый аудит — ежедневная практика. В курсе «Администрирование кластера Kafka» разбирают полный цикл: от мониторинга лог-директорий до планирования балансировки партиций под нагрузкой.
Что делает kafka-log-dirs.sh
kafka-log-dirs.sh — утилита для инспекции лог-директорий брокеров Apache Kafka. Она запрашивает у брокеров метаданные о размещении партиций: в какой директории лежит каждая партиция, сколько байт она занимает, отстаёт ли реплика от лидера и является ли директория «будущей» при переназначении.
Утилита выводит результат в JSON. Вся информация о состоянии лог-директорий собрана в одном запросе к кластеру — без прямого доступа к файловой системе брокеров.
Вот что именно видно в выводе для каждой партиции.
- logDir. Путь к директории с логами на брокере, например /var/kafka-logs.
- size. Размер партиции в байтах — сумма всех сегментов лога, включая индексные файлы.
- offsetLag. Насколько эта реплика отстаёт от лидера в офсетах. У лидера всегда 0. Ненулевое значение у фолловера — сигнал проблем с репликацией.
- isFuture. Признак «будущей» директории при переносе партиции в другой путь. Пока переназначение идёт — true. После завершения исчезает из вывода.
- error. Если лог-директория недоступна или повреждена, здесь будет сообщение об ошибке вместо списка партиций.
Базовая структура ответа строится по принципу: один брокер — один или несколько logDir — список партиций в каждом.
Apache Kafka для инженеров данных
Код курса
DEVKI
Ближайшая дата курса
24 августа, 2026
Продолжительность
24 ак.часов
Стоимость обучения
76 800
Синтаксис и основные флаги
Утилита не использует подкоманды — достаточно передать нужные флаги при вызове. Минимальный обязательный флаг только один — подключение к кластеру.
| Флаг | Что делает | Обязательный |
|---|---|---|
| —bootstrap-server | Адрес брокера для подключения, host:port | да |
| —broker-list | Список ID брокеров через запятую: 0,1,2. Без этого флага запрашиваются все брокеры | нет |
| —topic-list | Список топиков через запятую. Без этого флага возвращаются все топики | нет |
Шаг 1. Смотрим лог-директории всех брокеров
Самый простой запуск — без фильтрации. Утилита опросит все брокеры кластера и вернёт полную картину по всем топикам и партициям.
# Полный вывод лог-директорий всех брокеров kafka-log-dirs.sh \ --bootstrap-server localhost:9092 \ 2>/dev/null
Вывод будет длинным, если топиков много. Редирект 2>/dev/null скрывает информационные сообщения о подключении, которые Kafka пишет в stderr — в продакшене это удобно при парсинге.
Шаг 2. Фильтруем по топику и брокеру
На практике интересует конкретный топик или конкретный брокер, а не весь кластер. Флаги —topic-list и —broker-list работают независимо и можно использовать оба вместе.
# Смотрим только топик orders на брокере 0 kafka-log-dirs.sh \ --bootstrap-server localhost:9092 \ --broker-list 0 \ --topic-list orders \ 2>/dev/null
# Несколько топиков одновременно kafka-log-dirs.sh \ --bootstrap-server localhost:9092 \ --topic-list orders,payments,events \ 2>/dev/null
Шаг 3. Читаем JSON-вывод
Результат возвращается в виде однострочного JSON. Для удобного чтения передайте его в python3 -m json.tool или в jq.
# Форматированный вывод через jq kafka-log-dirs.sh \ --bootstrap-server localhost:9092 \ --topic-list orders \ 2>/dev/null | jq .
Типичный ответ для одного брокера с двумя партициями выглядит так.
{
"version": 1,
"brokers": [
{
"broker": 0,
"logDirs": [
{
"logDir": "/var/kafka-logs",
"error": null,
"partitions": [
{
"partition": "orders-0",
"size": 1048576,
"offsetLag": 0,
"isFuture": false
},
{
"partition": "orders-1",
"size": 524288,
"offsetLag": 0,
"isFuture": false
}
]
}
]
}
]
}
Поле version: 1 — это версия формата ответа, а не версия Kafka. Оно появилось давно и пока не менялось.
Шаг 4. Считаем суммарный размер топика
Размер каждой партиции указан в байтах. Чтобы получить суммарный размер топика по всему кластеру — сложите size для всех реплик-лидеров. Учтите: реплики занимают то же место, что и лидер, поэтому брать нужно только по одному экземпляру каждой партиции.
Быстрый способ — jq: извлечь все значения size и сложить.
# Суммарный размер всех сегментов топика orders на всех брокерах (включая реплики) kafka-log-dirs.sh \ --bootstrap-server localhost:9092 \ --topic-list orders \ 2>/dev/null \ | jq '[.. | .size? | numbers] | add'
Результат — суммарный объём в байтах, включая реплики. Разделите на фактор репликации топика, чтобы получить объём «чистых данных».
Шаг 5. Мониторинг переназначения партиций через isFuture
Поле isFuture — самый важный признак при работе с kafka-reassign-partitions.sh (урок 22). Когда вы переносите партицию на другой брокер или в другую директорию, Kafka сначала копирует данные в «будущее» расположение. В этот момент в выводе kafka-log-dirs.sh появляется дополнительная запись с isFuture: true.
{
"partition": "orders-0",
"size": 892416,
"offsetLag": 15234,
"isFuture": true
}
Ненулевой offsetLag здесь норма — новая реплика догоняет лидера. Переназначение завершено, когда запись с isFuture: true исчезла из вывода. Это надёжнее, чем полагаться только на статус от kafka-reassign-partitions.sh —verify.
# Проверяем, остались ли будущие директории (isFuture: true) kafka-log-dirs.sh \ --bootstrap-server localhost:9092 \ 2>/dev/null \ | jq '[.. | .isFuture? | select(. == true)] | length'
Если команда вернула 0 — переназначение завершено для всех партиций кластера.
Шаг 6. Обнаружение офлайн-директорий
Если лог-директория недоступна — например, диск упал или смонтирован с ошибкой — Kafka не возвращает список партиций, а заполняет поле error. Брокер при этом остаётся живым и обслуживает данные из других директорий (если они есть).
# Найти все директории с ошибками
kafka-log-dirs.sh \
--bootstrap-server localhost:9092 \
2>/dev/null \
| jq '.brokers[].logDirs[] | select(.error != null) | {broker: .logDir, error: .error}'
Пример вывода при проблеме с диском.
{
"broker": "/var/kafka-logs-2",
"error": "KafkaStorageException: Log directory /var/kafka-logs-2 is offline"
}
Это сигнал для немедленного действия — партиции из этой директории недоступны на данном брокере, и нагрузка переехала на реплики.
Apache Kafka: администрирование кластера
Код курса
KAFKA
Ближайшая дата курса
13 июля, 2026
Продолжительность
24 ак.часов
Стоимость обучения
76 800
Практический сценарий. Дисковый аудит перед балансировкой
Типичная задача: перед запуском переназначения партиций нужно понять текущее распределение данных по брокерам. Цель — убедиться, что один брокер не перегружен, и спланировать перенос.
Сначала смотрим суммарный объём данных на каждом брокере.
# Суммарный размер данных по каждому брокеру
kafka-log-dirs.sh \
--bootstrap-server localhost:9092 \
2>/dev/null | jq '
.brokers[] |
{
broker: .broker,
totalBytes: [.logDirs[].partitions[].size] | add
}
'
Затем выявляем самые «тяжёлые» партиции — кандидаты на вынос.
# Топ-10 партиций по размеру на брокере 0
kafka-log-dirs.sh \
--bootstrap-server localhost:9092 \
--broker-list 0 \
2>/dev/null | jq '
[.brokers[0].logDirs[].partitions[]] |
sort_by(-.size) |
.[:10] |
.[] |
{partition: .partition, sizeMB: (.size / 1048576 | floor)}
'
После этого аудита у вас есть конкретные цифры для решения: какие партиции переносить, куда, и насколько это уменьшит нагрузку на диск.
Альтернативы kafka-log-dirs.sh
kafka-log-dirs.sh даёт данные через API брокера. Есть и другие способы получить похожую информацию, каждый со своими плюсами.
- Прямая проверка файловой системы. Команда du -sh /var/kafka-logs/topic-partition/ на сервере брокера покажет точный размер с учётом файловой системы. Минус — нужен SSH-доступ к каждому брокеру.
- JMX-метрики. Метрика kafka.log:type=Log,name=Size,topic=X,partition=N в реальном времени. Подходит для интеграции с Prometheus через jmx_exporter.
- AKHQ / Kafka UI. Графические интерфейсы отображают размеры партиций в браузере. Удобно, но требует отдельного развёртывания.
- kafka-metadata-shell.sh. Из урока 13 — позволяет просматривать метаданные партиций, но не возвращает размеры на диске.
Из всех вариантов kafka-log-dirs.sh остаётся единственным штатным CLI-инструментом, который дёшево и без SSH-доступа показывает размеры партиций прямо из скрипта.
Что дальше
В следующем уроке разберём kafka-dump-log.sh — утилиту для чтения содержимого лог-сегментов Kafka напрямую с диска. Это инструмент отладки: он покажет, что именно хранится в бинарных файлах Kafka, включая заголовки сообщений, офсеты и временные метки. Пригодится, когда нужно разобраться с потерянными сообщениями или понять структуру хранения.
Ссылки
- Apache Kafka Documentation — Log Directories and Partition Management — официальная документация по работе с лог-директориями и партициями.
- Apache Kafka 4.2 Release Notes — KRaft Mode — изменения в KRaft-режиме, включая работу с метаданными партиций.
- KIP-113 — Support replicas movement between log directories — оригинальный KIP, добавивший isFuture и поддержку нескольких лог-директорий на одном брокере.
- Confluent — Post-Deployment Operations — практические советы по дисковому аудиту и балансировке партиций.